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') .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());
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);
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.