geoutils.ErrorComponent

geoutils.ErrorComponent#

class geoutils.ErrorComponent(name, magnitude, correlation=None, metadata=dict())[source]#

Error component describing both the error magnitude and its spatial autocorrelation.

One or several ErrorComponent can be combined into an ErrorStructure. These combined error components are assumed independent of each other, but each component can be autocorrelated in space.

An error component should generally be estimated jointly with error structure through higher-level function such as estimate_error_structure() from a raster or point object, or ErrorStructure.estimate(). Otherwise, to create it manually, define the magnitude and correlation manually using an ErrorMagnitude and a Variogram object, as demonstrated below.

As an example, defining independent measurement errors with a constant standard deviation of 2 m needs only a name and magnitude:

import geoutils as gu

measurement = gu.ErrorComponent("measurement", magnitude=2.0)
measurement.predict_magnitude()  # 2.0

Independent errors can also have magnitudes that vary with any predictor, for instance slope:

import pandas as pd

statistics = pd.DataFrame(
    {"std": [1.0, 3.0], "count": [20, 30]},
    index=pd.Index([0.0, 30.0], name="slope"),
)
magnitude = gu.ErrorMagnitude.variable_from_grouped_stats(statistics)
terrain = gu.ErrorComponent("terrain", magnitude)
terrain.predict_magnitude({"slope": [0.0, 15.0, 30.0]})  # array([1., 2., 3.])

Add a variogram model to describe spatial correlation. Here errors have a constant magnitude of 2 m and become uncorrelated at distances of 100 m or more, assuming coordinates are in metres:

from geoutils.stats.variography import VariogramModel

correlation = VariogramModel("spherical", effective_range=100, partial_sill=1)
spatial = gu.ErrorComponent("spatial", magnitude=2.0, correlation=correlation)
spatial.predict_correlation([0.0, 100.0])  # array([1., 0.])

The same correlation model can also be combined with the slope-dependent error magnitude above:

spatial_terrain = gu.ErrorComponent("spatial_terrain", magnitude, correlation)
errors = gu.ErrorStructure([spatial_terrain])
errors.predict_magnitude({"slope": [0.0, 30.0]})  # array([1., 3.])
Parameters:

  • name (str) – Unique component name.

  • magnitude (ErrorMagnitude | float) – Constant or variable error magnitude.

  • correlation (VariogramModel | Variogram | None) – Spatial variogram scaled to unit variance, or None for independent observations.

  • metadata (Mapping[str, Any]) – Additional details about estimation or diagnostics.

__init__(name, magnitude, correlation=None, metadata=<factory>)#

Methods

__init__(name, magnitude[, correlation, ...])

predict_correlation(distance)

Calculate correlation from this component at the given distances.

predict_magnitude([predictors])

Calculate error magnitude from this component.

Attributes

correlation

name

magnitude

metadata