Announcement: All noncommercial projects registered to use Earth Engine before April 15, 2025 must verify noncommercial eligibility to maintain Earth Engine access.
Stay organized with collections
Save and categorize content based on your preferences.
You can get statistics in each zone of an Image or
FeatureCollection by using reducer.group() to group the output
of a reducer by the value of a specified input. For example, to compute the total
population and number of housing units in each state, this example groups the output of
a reduction of a census block FeatureCollection as follows:
The groupField argument is the index of the input in the selectors array
that contains the codes by which to group, the groupName argument specifies
the name of the property to store the value of the grouping variable. Since the reducer
is not automatically repeated for each input, the repeat(2) call is needed.
To group output of image.reduceRegions() you can specify a grouping band
that defines groups by integer pixel values. This type of computation is sometimes called
"zonal statistics" where the zones are specified as the grouping band and the statistic
is determined by the reducer. In the following example, change in nightlights in the
United States is grouped by land cover category:
Note that in this example, the groupField is the index of the band
containing the zones by which to group the output. The first band is index 0, the second
is index 1, etc.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-01-02 UTC."],[[["\u003cp\u003eUse \u003ccode\u003ereducer.group()\u003c/code\u003e with \u003ccode\u003ereduceColumns()\u003c/code\u003e on \u003ccode\u003eFeatureCollection\u003c/code\u003e to compute statistics for groups based on a property, like calculating total population per state.\u003c/p\u003e\n"],["\u003cp\u003eUtilize \u003ccode\u003ereducer.group()\u003c/code\u003e with \u003ccode\u003ereduceRegion()\u003c/code\u003e on \u003ccode\u003eImage\u003c/code\u003e to compute zonal statistics, such as averaging nightlight changes within different land cover categories.\u003c/p\u003e\n"],["\u003cp\u003eSpecify the \u003ccode\u003egroupField\u003c/code\u003e argument in \u003ccode\u003ereducer.group()\u003c/code\u003e as the index of the selector or band containing the grouping categories.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003egroupName\u003c/code\u003e argument in \u003ccode\u003ereducer.group()\u003c/code\u003e determines the name of the property storing the grouping variable's value in the output dictionary.\u003c/p\u003e\n"],["\u003cp\u003eRemember to use \u003ccode\u003erepeat()\u003c/code\u003e with \u003ccode\u003ereduceColumns()\u003c/code\u003e when applying multiple reducers, ensuring calculations are performed for each selected property.\u003c/p\u003e\n"]]],[],null,["# Grouped Reductions and Zonal Statistics\n\nYou can get statistics in each zone of an `Image` or\n`FeatureCollection` by using `reducer.group()` to group the output\nof a reducer by the value of a specified input. For example, to compute the total\npopulation and number of housing units in each state, this example groups the output of\na reduction of a census block `FeatureCollection` as follows:\n\n### Code Editor (JavaScript)\n\n```javascript\n// Load a collection of US census blocks.\nvar blocks = ee.FeatureCollection('TIGER/2010/Blocks');\n\n// Compute sums of the specified properties, grouped by state code.\nvar sums = blocks\n .filter(ee.Filter.and(\n ee.Filter.neq('pop10', null),\n ee.Filter.neq('housing10', null)))\n .reduceColumns({\n selectors: ['pop10', 'housing10', 'statefp10'],\n reducer: ee.Reducer.sum().repeat(2).group({\n groupField: 2,\n groupName: 'state-code',\n })\n});\n\n// Print the resultant Dictionary.\nprint(sums);\n```\nPython setup\n\nSee the [Python Environment](/earth-engine/guides/python_install) page for information on the Python API and using\n`geemap` for interactive development. \n\n```python\nimport ee\nimport geemap.core as geemap\n```\n\n### Colab (Python)\n\n```python\n# Load a collection of US census blocks.\nblocks = ee.FeatureCollection('TIGER/2010/Blocks')\n\n# Compute sums of the specified properties, grouped by state code.\nsums = blocks.filter(\n ee.Filter.And(\n ee.Filter.neq('pop10', None), ee.Filter.neq('housing10', None)\n )\n).reduceColumns(\n selectors=['pop10', 'housing10', 'statefp10'],\n reducer=ee.Reducer.sum()\n .repeat(2)\n .group(groupField=2, groupName='state-code'),\n)\n\n# Print the resultant Dictionary.\ndisplay(sums)\n```\n\nThe `groupField` argument is the index of the input in the selectors array\nthat contains the codes by which to group, the `groupName` argument specifies\nthe name of the property to store the value of the grouping variable. Since the reducer\nis not automatically repeated for each input, the `repeat(2)` call is needed.\n\nTo group output of `image.reduceRegions()` you can specify a grouping band\nthat defines groups by integer pixel values. This type of computation is sometimes called\n\"zonal statistics\" where the zones are specified as the grouping band and the statistic\nis determined by the reducer. In the following example, change in nightlights in the\nUnited States is grouped by land cover category:\n\n### Code Editor (JavaScript)\n\n```javascript\n// Load a region representing the United States\nvar region = ee.FeatureCollection('USDOS/LSIB_SIMPLE/2017')\n .filter(ee.Filter.eq('country_na', 'United States'));\n\n// Load MODIS land cover categories in 2001.\nvar landcover = ee.Image('MODIS/051/MCD12Q1/2001_01_01')\n // Select the IGBP classification band.\n .select('Land_Cover_Type_1');\n\n// Load nightlights image inputs.\nvar nl2001 = ee.Image('NOAA/DMSP-OLS/NIGHTTIME_LIGHTS/F152001')\n .select('stable_lights');\nvar nl2012 = ee.Image('NOAA/DMSP-OLS/NIGHTTIME_LIGHTS/F182012')\n .select('stable_lights');\n\n// Compute the nightlights decadal difference, add land cover codes.\nvar nlDiff = nl2012.subtract(nl2001).addBands(landcover);\n\n// Grouped a mean reducer: change of nightlights by land cover category.\nvar means = nlDiff.reduceRegion({\n reducer: ee.Reducer.mean().group({\n groupField: 1,\n groupName: 'code',\n }),\n geometry: region.geometry(),\n scale: 1000,\n maxPixels: 1e8\n});\n\n// Print the resultant Dictionary.\nprint(means);\n```\nPython setup\n\nSee the [Python Environment](/earth-engine/guides/python_install) page for information on the Python API and using\n`geemap` for interactive development. \n\n```python\nimport ee\nimport geemap.core as geemap\n```\n\n### Colab (Python)\n\n```python\n# Load a region representing the United States\nregion = ee.FeatureCollection('USDOS/LSIB_SIMPLE/2017').filter(\n ee.Filter.eq('country_na', 'United States')\n)\n\n# Load MODIS land cover categories in 2001.\nlandcover = ee.Image('MODIS/051/MCD12Q1/2001_01_01').select(\n # Select the IGBP classification band.\n 'Land_Cover_Type_1'\n)\n\n# Load nightlights image inputs.\nnl_2001 = ee.Image('NOAA/DMSP-OLS/NIGHTTIME_LIGHTS/F152001').select(\n 'stable_lights'\n)\nnl_2012 = ee.Image('NOAA/DMSP-OLS/NIGHTTIME_LIGHTS/F182012').select(\n 'stable_lights'\n)\n\n# Compute the nightlights decadal difference, add land cover codes.\nnl_diff = nl_2012.subtract(nl_2001).addBands(landcover)\n\n# Grouped a mean reducer: change of nightlights by land cover category.\nmeans = nl_diff.reduceRegion(\n reducer=ee.Reducer.mean().group(groupField=1, groupName='code'),\n geometry=region.geometry(),\n scale=1000,\n maxPixels=1e8,\n)\n\n# Print the resultant Dictionary.\ndisplay(means)\n```\n\nNote that in this example, the `groupField` is the index of the band\ncontaining the zones by which to group the output. The first band is index 0, the second\nis index 1, etc."]]