reduceRegions#

geetools.ee_image_collection.ImageCollectionAccessor.reduceRegions(reducer, collection, idProperty='system:index', idType=ee.Number, idReducer='first', idFormat=None, scale=None, crs=None, crsTransform=None, tileScale=1)#

Apply a reducer to all the pixels in specific regions on each images of a collection.

The result will be shaped as a FeatureCollection with the idProperty as key and for each of them the reduced band values over one regions. Each feature will have the same properties as the original feature collection and thus be identified by a key pair: “system:id” + “system:image_property”

Here is a simple table representation of the result striped from the geometry:

image_id

feature_id

property1

property2

…

reduced_band1

reduced_band2

…

sentinel2_id_1

feature_1

feature1_prop1

feature1_prop2

…

reduced_image1_band1_feature1

reduced_image1_band2_feature1

…

sentinel2_id_2

feature_1

feature1_prop1

feature1_prop2

…

reduced_image2_band1_feature1

reduced_image2_band2_feature1

…

sentinel2_id_3

feature_1

feature1_prop1

feature1_prop2

…

reduced_image3_band1_feature1

reduced_image3_band2_feature1

…

sentinel2_id_1

feature_2

feature2_prop1

feature2_prop2

…

reduced_image1_band1_feature2

reduced_image1_band2_feature2

…

sentinel2_id_2

feature_2

feature2_prop1

feature2_prop2

…

reduced_image2_band1_feature2

reduced_image2_band2_feature2

…

sentinel2_id_3

feature_2

feature2_prop1

feature2_prop2

…

reduced_image3_band1_feature2

reduced_image3_band2_feature2

…

Warning

The method makes a call to the pure Python uuid package so it cannot be used in a server-side map function.

Parameters:

  • reducer (str | ee.Reducer) – The reducer to apply.

  • collection (ee.FeatureCollection) – The regions to reduce the data on.

  • idProperty (str | ee.String) – The property to use as the key of the resulting dictionary. If not specified, the key of the dictionary is the index of the image in the collection. One should use a meaningful property to avoid conflicts. in case of conflicts, the images with the same property will be mosaicked together (e.g. all raw satellite imagery with the same date) to make sure the final reducer have 1 single entry per idProperty.

  • idType (type) – The type of the idProperty. Default is ee.Number. As Dates are stored as numbers in metadata, we need to know what parsing to apply to the property in advance.

  • idReducer (str | ee.Reducer) – If the multiple images have the same idProperty, they will be aggregated beforehand using the provided reducer. default to a mosaic behaviour to match most of the satellite imagery collection where the world is split for each date between multiple images.

  • idFormat (str | ee.String | None) – If a date format is used for the IdProperty, the values will be formatted as “YYYY-MM-ddThh-mm-ss”. If a number format is used for the IdProperty, the values will be formatted as a string (“%s”). You can specify any other format compatible with band names.

  • scale (int | float | None) – A nominal scale in meters to work in.

  • crs (str | None) – The projection to work in. If unspecified, the projection of the image’s first band is used. If specified in addition to scale, rescaled to the specified scale.

  • crstransform – The list of CRS transform values. This is a row-major ordering of the 3x2 transform matrix. This option is mutually exclusive with ‘scale’, and replaces any transform already set on the projection.

  • tileScale (float | ee.Number) – A scaling factor between 0.1 and 16 used to adjust aggregation tile size; setting a larger tileScale (e.g., 2 or 4) uses smaller tiles and may enable computations that run out of memory with the default.

  • crsTransform (list | None)

Returns:

A FeatureCollection with the reduced values for each image.

Return type:

ee.FeatureCollection

Examples

import ee
import geetools
from geetools.utils import initialize_documentation
import geopandas as gpd

initialize_documentation()

## 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", "2010-05-30"))
    .select(["NDVI", "EVI"])
)

data = vegIndices.geetools.reduceRegions(
    collection=ecoregions,
    reducer="mean",
    idProperty="system:time_start",
    idType=ee.Date,
    scale=10000,
)

# display them as a dataframe
gdf = gpd.GeoDataFrame.from_features(data.getInfo()["features"])
gdf.head(15)
geometry EVI NDVI feature_id image_id label value warm
0 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 1029.865316 1829.181223 00000000000000000000 2010-01-01T00-00-00 Desert 0 1
1 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 981.652473 1919.515781 00000000000000000000 2010-01-17T00-00-00 Desert 0 1
2 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 984.046138 1852.502812 00000000000000000000 2010-02-02T00-00-00 Desert 0 1
3 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 1001.357741 1821.733272 00000000000000000000 2010-02-18T00-00-00 Desert 0 1
4 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 1096.367439 1814.529324 00000000000000000000 2010-03-06T00-00-00 Desert 0 1
5 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 1264.786813 1918.765178 00000000000000000000 2010-03-22T00-00-00 Desert 0 1
6 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 1397.797831 2200.882876 00000000000000000000 2010-04-07T00-00-00 Desert 0 1
7 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 1512.982670 2305.773155 00000000000000000000 2010-04-23T00-00-00 Desert 0 1
8 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 1531.141168 2265.504017 00000000000000000000 2010-05-09T00-00-00 Desert 0 1
9 POLYGON ((-109.21 31.42, -108.3 31.42, -108.3 ... 1504.562780 2207.268966 00000000000000000000 2010-05-25T00-00-00 Desert 0 1
10 POLYGON ((-122.73 43.45, -122.28 43.45, -122.2... 2015.141896 3493.780122 00000000000000000001 2010-01-01T00-00-00 Forest 1 1
11 POLYGON ((-122.73 43.45, -122.28 43.45, -122.2... 3233.357492 7411.121254 00000000000000000001 2010-01-17T00-00-00 Forest 1 1
12 POLYGON ((-122.73 43.45, -122.28 43.45, -122.2... 2987.606575 7862.647095 00000000000000000001 2010-02-02T00-00-00 Forest 1 1
13 POLYGON ((-122.73 43.45, -122.28 43.45, -122.2... 3300.417584 7975.378899 00000000000000000001 2010-02-18T00-00-00 Forest 1 1
14 POLYGON ((-122.73 43.45, -122.28 43.45, -122.2... 3234.411468 7691.665596 00000000000000000001 2010-03-06T00-00-00 Forest 1 1