geoutils.operators.Reducer

class geoutils.operators.Reducer(neighborhood=None)

Reducer of nearby input values into one result.

A reducer uses all values selected in a neighborhood (rasters or points within a radius or window), potentially accounting for fractional overlap area on rasters, then applies a reducing function. Typical reducing functions are mean, median, etc.

To define your own reducer, implement reduce(). It receives a LocalData object with the selected values and any available weights. Implement coefficients() instead when the result is a linear combination that can also be used for weighting or uncertainty propagation.

Sample weights are used to describe the weight of each observation, while support weights are used to describe the fraction of a source raster cell covered by an output area (source points do not have fractional areas).

The optional default_neighborhood selects raster cells for resample_at_points() or source points for grid(). Without one, resample_at_points() uses a 3 x 3 window and grid() uses its dist_nodata_pixel radius. reproject() selects cells from each output pixel’s footprint by default. With GridNeighbours, it selects source cells around the cell containing each transformed output pixel center, without fractional area weights.

For example, this reducer averages the parts of source cells covered by each output cell:

import numpy as np
import geoutils as gu

class CoveredMean(gu.operators.Reducer):
    accepts_support_weights = True

    def reduce(self, data):
        return float(np.average(data.values, weights=data.support_weights))

reduced = raster.reproject(reference_raster, resampling=CoveredMean())

A linear reducer should implement coefficients() instead to support weights or uncertainty propagation. The reducer example below sums all cells in the window, so its linear formulation is a weight of one to each, which can then be used with an error structure:

class WindowSum(gu.operators.Reducer):
    '''Sum the raster cells in a window around each point.'''

    def coefficients(self, data):
        '''Give every selected cell a weight of one.'''

        return gu.operators.LinearCoefficients(np.ones(len(data.values)))

errors = gu.ErrorStructure([gu.ErrorComponent("measurement", 2.0)])
summary = gu.uncertainty.propagate(
    raster.resample_at_points, error_structure=errors,
    operation_kwargs=dict(points=(x, y), method=WindowSum(), as_array=True),
)
total = summary.estimate

A Reducer receives a 3 x 3 raster window by default. Here GridNeighbours selects a 5 x 5 window instead:

wider_window = gu.operators.GridNeighbours(size=5)
total = raster.resample_at_points(
    (x, y), WindowSum(neighborhood=wider_window), as_array=True
)

PointNeighbours can instead select source observations when the Reducer grids a point cloud:

from geoutils.operators import PointNeighbours
from geoutils.operators.reducer import Mean

nearby = PointNeighbours(max_points=8, radius=50)
gridded = point_cloud.grid(ref=reference_raster, resampling=Mean(neighborhood=nearby))

__init__(neighborhood=None)

Choose the nearby raster cells or point observations to reduce.

Parameters:

neighborhood (GridNeighbours | PointNeighbours | None) – GridNeighbours for raster resample_at_points() or reproject(), or PointNeighbours for grid(). Without one, resample_at_points() and grid() use their default windows or radii, and reproject() uses the output pixel’s footprint.

Methods

__init__([neighborhood])	Choose the nearby raster cells or point observations to reduce.
coefficients(data)	Return weights and an optional constant offset for a weighted sum of values.
evaluate(data, *[, nodata_propagation])	Check nodata and weights before calculating a result.
reduce(data)	Combine a group of values into one result.
reduce_batch(data, *[, nodata_propagation])	Calculate a result for each group of values by calling evaluate().

Attributes

accepts_sample_weights
accepts_support_weights
default_neighborhood
default_nodata_propagation
error_structure
minimum_inputs