Reducer Overview

Reducers are the way to aggregate data over time, space, bands, arrays and other data structures in Earth Engine. The ee.Reducer class specifies how data is aggregated. The reducers in this class can specify a simple statistic to use for the aggregation (e.g. minimum, maximum, mean, median, standard deviation, etc.), or a more complex summary of the input data (e.g. histogram, linear regression, list). Reductions may occur over time (imageCollection.reduce()), space (image.reduceRegion(), image.reduceNeighborhood()), bands (image.reduce()), or the attribute space of a FeatureCollection (featureCollection.reduceColumns() or FeatureCollection methods that start with aggregate_).

Reducers have inputs and outputs

Reducers take an input dataset and produce a single output. When a single input reducer is applied to a multi-band image, Earth Engine automatically replicates the reducer and applies it separately to each band. As a result, the output image has the same number of bands as the input image; each band in the output is the reduction of pixels from the corresponding band in the input data. Some reducers take tuples of input datasets. These reducers will not be automatically replicated for each band. For example, ee.Reducer.LinearRegression() takes multiple predictor datasets (representing independent variables in the regression) in a particular order (see Regression reducers).

Some reducers produce multiple outputs, for example ee.Reducer.minMax(), ee.Reducer.histogram() or ee.Reducer.toList(). For example:

Code Editor (JavaScript)

// Load and filter the Sentinel-2 image collection.
var collection = ee.ImageCollection('COPERNICUS/S2_HARMONIZED')
    .filterDate('2016-01-01', '2016-12-31')
    .filterBounds(ee.Geometry.Point([-81.31, 29.90]));

// Reduce the collection.
var extrema = collection.reduce(ee.Reducer.minMax());

Python setup

See the Python Environment page for information on the Python API and using geemap for interactive development.

import ee
import geemap.core as geemap

Colab (Python)

# Load and filter the Sentinel-2 image collection.
collection = (
    ee.ImageCollection('COPERNICUS/S2_HARMONIZED')
    .filterDate('2016-01-01', '2016-12-31')
    .filterBounds(ee.Geometry.Point([-81.31, 29.90]))
)

# Reduce the collection.
extrema = collection.reduce(ee.Reducer.minMax())

This will produce an output with twice the number of bands of the inputs, where band names in the output have '_min' or '_max' appended to the band name.

The output type should match the computation. For example, a reducer applied to an ImageCollection has an Image output. Because the output is interpreted as a pixel value, you must use reducers with a numeric output to reduce an ImageCollection (reducers like toList() or histogram() won't work).

Reducers use weighted inputs

By default, reductions over pixel values are weighted by their mask, though this behavior can be changed (see the Weighting section). Pixels with mask equal to 0 will not be used in the reduction.

Combining reducers

If your intent is to apply multiple reducers to the same inputs, it's good practice to combine() the reducers for efficiency. Specifically, calling combine() on a reducer with sharedInputs set to true will result in only a single pass over the data. For example, to compute the mean and standard deviation of pixels in an image, you could use something like this:

Code Editor (JavaScript)

// Load a Landsat 8 image.
var image = ee.Image('LANDSAT/LC08/C02/T1/LC08_044034_20140318');

// Combine the mean and standard deviation reducers.
var reducers = ee.Reducer.mean().combine({
  reducer2: ee.Reducer.stdDev(),
  sharedInputs: true
});

// Use the combined reducer to get the mean and SD of the image.
var stats = image.reduceRegion({
  reducer: reducers,
  bestEffort: true,
});

// Display the dictionary of band means and SDs.
print(stats);

Python setup

See the Python Environment page for information on the Python API and using geemap for interactive development.

import ee
import geemap.core as geemap

Colab (Python)

# Load a Landsat 8 image.
image = ee.Image('LANDSAT/LC08/C02/T1/LC08_044034_20140318')

# Combine the mean and standard deviation reducers.
reducers = ee.Reducer.mean().combine(
    reducer2=ee.Reducer.stdDev(), sharedInputs=True
)

# Use the combined reducer to get the mean and SD of the image.
stats = image.reduceRegion(reducer=reducers, bestEffort=True)

# Display the dictionary of band means and SDs.
display(stats)

In the output, note that the names of the reducers have been appended to the names of the inputs to distinguish the reducer outputs. This behavior also applies to image outputs, which will have the name of the reducer appended to output band names.

If you are combining reducers using unweighted inputs and reducers using weighted inputs, all weighted inputs must be before all unweighted inputs.