Plot ImageCollection#

The geetools extention contains a set of functions for rendering charts from the results of spatiotemporal reduction of images within an ee.ImageCollection. The choice of function dictates the arrangement of data in the chart, i.e., what defines x- and y-axis values and what defines the series. Use the following function descriptions and examples to determine the best function for your purpose.

github colab

Set up environment#

Install all the required libs if necessary and perform the import satements upstream.

# uncomment if installation of libs is necessary
# !pip install earthengine-api geetools

from matplotlib import pyplot as plt
from datetime import datetime as dt

import ee
import geetools #noqa: F401

# uncomment if authetication to GEE is needed
# ee.Authenticate()
# ee.Intialize(project="<your_project>")

Example data#

The following examples rely on a ee.FeatureCollection composed of three ecoregion features that define regions by which to reduce image data. The ImageCollection data loads the modis vegetation indicies and subset the 2010 2020 decade of images.

## Import the example feature collection and drop the data property.
ecoregions = (
    ee.FeatureCollection("projects/google/charts_feature_example")
    .select(["label", "value", "warm"])
)


## Load MODIS vegetation indices data and subset a decade of images.
vegIndices = (
    ee.ImageCollection("MODIS/061/MOD13A1")
    .filter(ee.Filter.date("2010-01-01", "2020-01-01"))
    .select(["NDVI", "EVI"])
)

Plot dates#

The plot_dates* methods will plot the values of the image collection using their dates as x-axis values.

series by bands#

Image date is plotted along the x-axis according to the dateProperty property. Series are defined by image bands. Y-axis values are the reduction of images, by date, for a single region.

../../_images/ca2798367d4b640453188ef0f027254acf71eb897cdf0e4c18cb326868546fdf.png

Use plot_series_by_bands to display an image time series for a given region; each image band is presented as a unique series. It is useful for comparing the time series of individual image bands. Here, a MODIS image collection with bands representing NDVI and EVI vegetation indices are plotted. The date of every image observation is included along the x-axis, while the mean reduction of pixels intersecting a forest ecoregion defines the y-axis.

fig, ax = plt.subplots(figsize=(10, 4))
region = ecoregions.filter(ee.Filter.eq("label", "Forest"))
vegIndices.geetools.plot_dates_by_bands(
    region = region.geometry(),
    reducer = "mean",
    scale = 500,
    bands = ["NDVI", "EVI"],
    ax = ax,
    dateProperty = "system:time_start",
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_ylabel("Vegetation indices (x1e4)")
ax.set_title("Average Vegetation index Values by date in the Forest ecoregion")

plt.show()
../../_images/b55dcc237e930d4422632afd8be884ff983a916a00bd7a1fe7bfc244d0c92925.png

See API

  • plot_dates_by_bands: Plot the reduced data for each image in the collection by bands on a specific region.

  • datesByBands: Reduce the data for each image in the collection by bands on a specific region.

Plot series by region#

Image date is plotted along the x-axis according to the dateProperty property. Series are defined by regions. Y-axis values are the reduction of images, by date, for a single image band.

../../_images/1f883297f9bea6e7860c032b716f14ffcd0716a263a20fc5af086dfa6e107db4.png

Use plot_dates_by_regions to display a single image band time series for multiple regions; each region is presented as a unique series. It is useful for comparing the time series of a single band among several regions. Here, a MODIS image collection representing an NDVI time series is plotted for three ecoregions. The date of every image observation is included along the x-axis, while mean reduction of pixels intersecting forest, desert, and grasslands ecoregions define y-axis series.

fig, ax = plt.subplots(figsize=(10, 4))
region = ecoregions.filter(ee.Filter.eq("label", "Forest"))
vegIndices.geetools.plot_dates_by_regions(
    band = "NDVI",
    regions = ecoregions,
    label = "label",
    reducer = "mean",
    scale = 500,
    ax = ax,
    dateProperty = "system:time_start",
    colors = ['#f0af07', '#0f8755', '#76b349']
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_ylabel("Vegetation indices (x1e4)")
ax.set_title("Average Vegetation index Values by date in the Forest ecoregion")

plt.show()
../../_images/76edb24e3d171cb499e9ffd1b9328b9fcfac79e14f9da6eea86ab221bbeedc3b.png

See API

  • plot_dates_by_regions: Plot the reduced data for each image in the collection by regions for a single band.

  • datesByRegions: Reduce the data for each image in the collection by regions for a single band.

PLot DOY#

DOY stands for day of year. The plot_doyseries* methods will plot the values of the image collection using the day of year as x-axis values.

Note that .plot_doyseries* functions take two reducers: one for region reduction (regionReducer) and another for intra-annual coincident day-of-year reduction (yearReducer). Examples in the following sections use ee.Reducer.mean() as the argument for both of these parameters.

Plot DOY by bands#

Image day-of-year is plotted along the x-axis according to the dateProperty property. Series are defined by image bands. Y-axis values are the reduction of image pixels in a given region, grouped by day-of-year.

../../_images/bb7d9533b3c087b327f44772cedfb6d328d5650ed3026f468dfa4a406ed33bb2.png

Use plot_doy_by_bands to display a day-of-year time series for a given region; each image band is presented as a unique series. It is useful for reducing observations occurring on the same day-of-year, across multiple years, to compare e.g. average annual NDVI and EVI profiles from MODIS, as in this example.

fig, ax = plt.subplots(figsize=(10,4))

vegIndices.geetools.plot_doy_by_bands(
    region = ecoregions.filter(ee.Filter.eq("label", "Grassland")).geometry(),
    spatialReducer = "mean",
    timeReducer = "mean",
    scale = 500,
    bands = ["NDVI", "EVI"],
    ax = ax,
    dateProperty = "system:time_start",
    colors = ['#e37d05', '#1d6b99']
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_ylabel("Vegetation indices (x1e4)")
ax.set_title("Average Vegetation index Values by doy in the Grassland ecoregion")

plt.show()
../../_images/040bf0004f55a1b7b7edb861c76da7ed09792bca4f7026754fa188eddcd62fc0.png

See API

  • plot_doy_by_bands: Plot the reduced data for each image in the collection by bands on a specific region.

  • doyByBands: Aggregate the images that occurs on the same day and then reduce each band on a single region.

Plot doy by regions#

Image day-of-year is plotted along the x-axis according to the dateProperty property. Series are defined by regions. Y-axis values are the reduction of image pixels in a given region, grouped by day-of-year, for a selected image band.

../../_images/48b9c5092a2017ed79e5ec8214752785ee85f813b5502fb7a27b0ab1f4064f30.png

Use plot_doy_by_regions to display a single image band day-of-year time series for multiple regions, where each distinct region is presented as a unique series. It is useful for comparing annual single-band time series among regions. For instance, in this example, annual MODIS-derived NDVI profiles for forest, desert, and grassland ecoregions are plotted, providing a convenient comparison of NDVI response by region. Note that intra-annual observations occurring on the same day-of-year are reduced by their mean.

fig, ax = plt.subplots(figsize=(10,4))

vegIndices.geetools.plot_doy_by_regions(
    regions = ecoregions,
    label = "label",
    spatialReducer = "mean",
    timeReducer = "mean",
    scale = 500,
    band = "NDVI",
    ax = ax,
    dateProperty = "system:time_start",
    colors = ['#f0af07', '#0f8755', '#76b349']
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_ylabel("NDVI (x1e4)")
ax.set_title("Average NDVI Values by doy in each ecoregion")

plt.show()
../../_images/4fab08f6d1c54c144ed983987a99725bc3eceb1caf318d9b4f766f7ca819d7ba.png

See API

  • plot_doy_by_regions: Plot the reduced data for each image in the collection by regions for a single band.

  • doyByRegions: Aggregate the images that occurs on the same day and then reduce a single band on multiple regions.

plot doy by year#

Image day-of-year is plotted along the x-axis according to the dateProperty property. Series are defined by years present in the ImageCollection. Y-axis values are the reduction of image pixels in a given region, grouped by day-of-year, for a selected image band.

../../_images/52c93a45b9bdaa2c935fd140e0b312ef3b0e50485ad14476e11e01646a0cf067.png

Use plot_doy_by_years to display a day-of-year time series for a given region and image band, where each distinct year in the image collection is presented as a unique series. It is useful for comparing annual time series among years. For instance, in this example, annual MODIS-derived NDVI profiles for a grassland ecoregion are plotted for years 2012 and 2019, providing convenient year-over-year interpretation.

# reduce the regions to grassland
grassland = ecoregions.filter(ee.Filter.eq("label", "Grassland"))

# for plot speed and lisibility only keep 2 years (2010 and 2020) for the example
indices = vegIndices.filter(
        ee.Filter.Or(
            ee.Filter.date("2012-01-01", "2012-12-31"),
            ee.Filter.date("2019-01-01", "2019-12-31"),
        )
)

fig, ax = plt.subplots(figsize=(10,4))

indices.geetools.plot_doy_by_years(
    band = "NDVI",
    region = grassland.geometry(),
    reducer = "mean",
    scale = 500,
    ax = ax,
    colors = ['#39a8a7', '#9c4f97']
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_ylabel("NDVI (x1e4)")
ax.set_title("Average NDVI Values by day of year for Grassland")

plt.show()
../../_images/5a1a8ac3585bcc159e01ffd61baa960575383a454fabb6133f04ab2ca44e9386.png

See API

  • plot_doy_by_years: Plot the reduced data for each image in the collection by years for a single band.

  • doyByYears: Aggregate for each year on a single region a single band.

plot doy by seasons#

In case the observation you want to analyse are only meaningful on a subset of the year a variant of the previous method allows you to plot the data by season. The season is defined by the seasonStart and seasonEnd parameters, which are 2 numbers between 1 and 366 representing the start and end of the season. To set them, the user can use the or time.struct_time method to get the day of the year.

ee.Date("2022-06-01").getRelative("day", "year").getInfo()

151

dt(2022, 6, 1).timetuple().tm_yday

152

fig, ax = plt.subplots(figsize=(10,4))

indices.geetools.plot_doy_by_seasons(
    band = "NDVI",
    region = grassland.geometry(),
    seasonStart = ee.Date("2022-04-15").getRelative("day", "year"),
    seasonEnd = ee.Date("2022-09-15").getRelative("day", "year"),
    reducer = "mean",
    scale = 500,
    ax = ax,
    colors = ['#39a8a7', '#9c4f97']
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_ylabel("NDVI (x1e4)")
ax.set_title("Average NDVI Values during growing season in Grassland")

plt.show()
../../_images/464859862b8fa8b018d10c6d1e3ae641e37e4a3d5b54f8ca6818d38c1f8fa72f.png

See API

  • plot_doy_by_seasons: Plot the reduced data for each image in the collection by years for a single band.

  • doyBySeasons: Aggregate for each year on a single region a single band.