Plot Image

The geetools extention contains a set of functions for reducing ee.Image objects by region(s) and rendering charts from the results. 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 and chart type for your purpose.

Set up environment

Install all the requireed 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

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 Image data are PRISM climate normals, where bands describe climate variables per month; e.g., July precipitation or January mean temperature.

ecoregions = ee.FeatureCollection("projects/google/charts_feature_example").select(["label", "value","warm"])
normClim = ee.ImageCollection('OREGONSTATE/PRISM/Norm91m').toBands()

Plot by regions

Reduction regions are plotted along the x-axis, labeled by values of a selected feature property. Series are defined by band names whose region reduction results are plotted along the y-axis.

If you want to use another plotting library, you can use the byRegions function to get the data and plot it with your favorite library.

See API

• plot_by_regions: Plot the reduced values for each region.

• byRegions: Compute a reducer in each region of the image for eah band.

Column chart

In this example, image bands representing average monthly temperature are reduced to the mean among pixels intersecting each of three ecoregions. The results are plotted as columns per month by ecoregion, where column height indicates the respective mean monthly temperature.

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

normClim.geetools.plot_by_regions(
    type = "bar",
    regions = ecoregions,
    reducer = "mean",
    scale = 500,
    regionId = "label",
    bands = ["01_tmean", "02_tmean", "03_tmean", "04_tmean", "05_tmean", "06_tmean", "07_tmean", "08_tmean", "09_tmean", "10_tmean", "11_tmean", "12_tmean"],
    labels = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"],
    colors = ['#604791', '#1d6b99', '#39a8a7', '#0f8755', '#76b349', '#f0af07', '#e37d05', '#cf513e', '#96356f', '#724173', '#9c4f97', '#696969'],
    ax = ax
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_title("Average Monthly Temperature by Ecoregion")
ax.set_xlabel("Ecoregion")
ax.set_ylabel("Temperature (°C)")
plt.show()

Bar chart

The previous column chart can be swiped from vertical column to horizontal bars a bar chart by changing the type input from ‘bar’ to ‘barh’.

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

fc = normClim.geetools.plot_by_regions(
    type = "barh",
    regions = ecoregions,
    reducer = "mean",
    scale = 500,
    regionId = "label",
    bands = ["01_tmean", "02_tmean", "03_tmean", "04_tmean", "05_tmean", "06_tmean", "07_tmean", "08_tmean", "09_tmean", "10_tmean", "11_tmean", "12_tmean"],
    labels = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"],
    colors = ['#604791', '#1d6b99', '#39a8a7', '#0f8755', '#76b349', '#f0af07', '#e37d05', '#cf513e', '#96356f', '#724173', '#9c4f97', '#696969'],
    ax = ax
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_title("Average Monthly Temperature by Ecoregion")
ax.set_ylabel("Ecoregion")
ax.set_xlabel("Temperature (°C)")
plt.show()

Stacked bar chart

An absolute stacked bar chart relates the total of a numeric variable by increments of a contributing categorical variable series. For instance, in this example, total precipitation is plotted as the accumulation of monthly precipitation over a year, by ecoregion. Monthly precipitation totals are derived from image bands, where each band represents a grid of average total precipitation for a given month, reduced to the mean of the pixels intersecting each of three ecoregions.

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

fc = normClim.geetools.plot_by_regions(
    type = "stacked",
    regions = ecoregions,
    reducer = "mean",
    scale = 500,
    regionId = "label",
    bands = ['01_ppt', '02_ppt', '03_ppt', '04_ppt', '05_ppt', '06_ppt', '07_ppt', '08_ppt', '09_ppt', '10_ppt', '11_ppt', '12_ppt'],
    labels = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"],
    colors = ['#604791', '#1d6b99', '#39a8a7', '#0f8755', '#76b349', '#f0af07', '#e37d05', '#cf513e', '#96356f', '#724173', '#9c4f97', '#696969'],
    ax = ax
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_title("Average Monthly Temperature by Ecoregion")
ax.set_xlabel("Ecoregion")
ax.set_ylabel("Temperature (°C)")
plt.show()

Plot by bands

Bands are plotted along the x-axis. Series are labeled by values of a feature property. Reduction of the region defined by the geometry of respective series features are plotted along the y-axis.

Colmun chart

This chart shows total average precipitation per month for three ecoregions. The results are derived from the region reduction of an image where each band is a grid of average total precipitation for a given month. Bands are plotted along the x-axis and regions define the series.

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

fc = normClim.geetools.plot_by_bands(
    type = "bar",
    regions = ecoregions,
    reducer = "mean",
    scale = 500,
    regionId = "label",
    bands = ['01_ppt', '02_ppt', '03_ppt', '04_ppt', '05_ppt', '06_ppt', '07_ppt', '08_ppt', '09_ppt', '10_ppt', '11_ppt', '12_ppt'],
    labels = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"],
    colors = ["#f0af07", "#0f8755", "#76b349"],
    ax = ax
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_title("Average Monthly Precipitation by Ecoregion")
ax.set_xlabel("Month")
ax.set_ylabel("Precipitation (mm)")
plt.show()

Line chart

The previous column chart can be rendered as a line chart by changing the type input from “bar” to “plot”.

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

fc = normClim.geetools.plot_by_bands(
    type = "plot",
    regions = ecoregions,
    reducer = "mean",
    scale = 500,
    regionId = "label",
    bands = ['01_ppt', '02_ppt', '03_ppt', '04_ppt', '05_ppt', '06_ppt', '07_ppt', '08_ppt', '09_ppt', '10_ppt', '11_ppt', '12_ppt'],
    labels = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"],
    colors = ["#f0af07", "#0f8755", "#76b349"],
    ax = ax
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_title("Average Monthly Precipitation by Ecoregion")
ax.set_xlabel("Month")
ax.set_ylabel("Precipitation (mm)")
plt.show()

Area chart

The previous column chart can be rendered as a line chart by changing the type input from “plot” to “fill_between”.

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

fc = normClim.geetools.plot_by_bands(
    type = "fill_between",
    regions = ecoregions,
    reducer = "mean",
    scale = 500,
    regionId = "label",
    bands = ['01_ppt', '02_ppt', '03_ppt', '04_ppt', '05_ppt', '06_ppt', '07_ppt', '08_ppt', '09_ppt', '10_ppt', '11_ppt', '12_ppt'],
    labels = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"],
    colors = ["#f0af07", "#0f8755", "#76b349"],
    ax = ax
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_title("Average Monthly Precipitation by Ecoregion")
ax.set_xlabel("Month")
ax.set_ylabel("Precipitation (mm)")
plt.show()

Pie chart

Average monthly precipitation is displayed as a proportion of the average total annual precipitation for a forest ecoregion. Image bands representing monthly precipitation are subset from a climate normals dataset and reduced to the mean of pixels intersecting the ecoregion.

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

normClim.geetools.plot_by_bands(
    type = "pie",
    regions = ecoregions.filter(ee.Filter.eq("label", "Forest")),
    reducer = "mean",
    scale = 500,
    regionId = "label",
    bands = ['01_ppt', '02_ppt', '03_ppt', '04_ppt', '05_ppt', '06_ppt', '07_ppt', '08_ppt', '09_ppt', '10_ppt', '11_ppt', '12_ppt'],
    labels = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"],
    colors = ['#604791', '#1d6b99', '#39a8a7', '#0f8755', '#76b349', '#f0af07', '#e37d05', '#cf513e', '#96356f', '#724173', '#9c4f97', '#696969'],
    ax = ax
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_title("Average Monthly Precipitation in Forest")
plt.show()

Donuts chart

The previous chart can be represented as a donut by replacing the type parameter with donut.

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

fc = normClim.geetools.plot_by_bands(
    type = "donut",
    regions = ecoregions.filter(ee.Filter.eq("label", "Forest")),
    reducer = "mean",
    scale = 500,
    regionId = "label",
    bands = ['01_ppt', '02_ppt', '03_ppt', '04_ppt', '05_ppt', '06_ppt', '07_ppt', '08_ppt', '09_ppt', '10_ppt', '11_ppt', '12_ppt'],
    labels = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"],
    colors = ['#604791', '#1d6b99', '#39a8a7', '#0f8755', '#76b349', '#f0af07', '#e37d05', '#cf513e', '#96356f', '#724173', '#9c4f97', '#696969'],
    ax = ax
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_title("Average Monthly Precipitation in Forest")
plt.show()

histogram plot

A histogram of pixel values within a region surrounding Salt Lake City, Utah, USA are displayed for three MODIS surface reflectance bands. The histogram is plotted as a line chart, where x-axis values are pixel values and y-axis values are the frequency of pixels with the respective value.

# custom image for this specific chart
modisSr = (
    ee.ImageCollection("MODIS/061/MOD09A1")
    .filter(ee.Filter.date("2018-06-01", "2018-09-01"))
    .select(["sur_refl_b01", "sur_refl_b02", "sur_refl_b06"])
    .mean()
)
histRegion = ee.Geometry.Rectangle([-112.60, 40.60, -111.18, 41.22])

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

# initialize the plot with the ecoregions data
modisSr.geetools.plot_hist(
    bands = ["sur_refl_b01", "sur_refl_b02", "sur_refl_b06"],
    labels = [['Red', 'NIR', 'SWIR']],
    colors = ["#cf513e", "#1d6b99", "#f0af07"],
    ax = ax,
    bins = 100,
    scale = 500,
    region = histRegion,
)

# once created the axes can be modified as needed using pure matplotlib functions
ax.set_title("Modis SR Reflectance Histogram")
ax.set_xlabel("Reflectance (x1e4)")
plt.show()