geoutils.ErrorMagnitude

geoutils.ErrorMagnitude#

class geoutils.ErrorMagnitude(kind, value=None, grouped_statistics=None, predictor_names=(), value_name='error', statistic=None, min_count=0, scale=1.0, variance_offset=0.0, floor=0.0)[source]#

Error magnitude, either constant or variable (i.e. heteroscedastic) with named predictors.

An ErrorMagnitude describes the statistical spread for an ErrorComponent, in the source units. Statistical spread can be derived from any spread estimator (such as STD, NMAD, percentiles…).

It should generally be estimated jointly with error correlation through higher-level function such as estimate_error_structure() from a raster or point object, or ErrorStructure.estimate(). Otherwise, to create it manually, use one of two methods:

  • For a constant error, use constant(value) with a single value,

  • For a variable error, use variable_from_grouped_stats(statistics) with a pandas DataFrame of spread estimates and counts, indexed by named predictors; the output of stats(by=) on an error proxy.

Grouped tables can use plain statistic columns such as “nmad” and “count”. Two-level (variable, statistic) columns from stats() are also accepted; use value_name to select the variable name.

With statistic=None, “std” or “nmad” is selected automatically. If both are present, “std” is used with a warning. Pass statistic explicitly to select another spread estimate or override this choice.

For example, a constant standard deviation of 2 m for elevation measurements:

import geoutils as gu

measurement = gu.ErrorMagnitude.constant(2.0)
measurement.predict()  # 2.0

Another example can use variable error magnitudes increasing from 1 to 3 m between slopes of 0 and 30 degrees. Then predicts interpolates linearly between groups, estimating an error of 2 m for a slope of 15 degrees:

import pandas as pd

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

Multiple predictors can be used at once, for instance slope and elevation, with a different dispersion column “std”:

terrain_statistics = pd.DataFrame(
    {"std": [1.0, 2.0, 3.0, 4.0], "count": [20, 20, 20, 20]},
    index=pd.MultiIndex.from_product(
        [[0.0, 30.0], [100.0, 1000.0]], names=["slope", "elevation"]
    ),
)
terrain = gu.ErrorMagnitude.variable_from_grouped_stats(terrain_statistics, statistic="std")
terrain.predict({"slope": [0.0, 30.0], "elevation": [100.0, 1000.0]})  # array([1., 4.])
Parameters:

  • kind (Literal['constant', 'variable']) – Kind of error magnitude, “constant” or “variable”; set automatically by constant() and variable_from_grouped_stats().

  • value (float | None) – Standard deviation for “constant” error magnitude, must be None for “variable”.

  • grouped_statistics (DataFrame | None) – Statistics table as described above, required for “variable”; None for “constant”.

  • predictor_names (tuple[str, ...]) – Predictor names in index order, required for direct “variable” construction. variable_from_grouped_stats() infers them from the table; leave empty for “constant”.

  • value_name (str) – Variable to select from two-level columns; unneeded for plain statistic columns.

  • statistic (str | None) – Spread statistic selected from grouped statistics.

  • min_count (int) – Minimum number of values required to use a group’s statistic.

  • scale (float) – Factor applied to error magnitudes from grouped statistics.

  • variance_offset (float) – Variance assigned to other error components, subtracted from the squared error magnitude.

  • floor (float) – Minimum error magnitude after subtracting the variance offset.

__init__(kind, value=None, grouped_statistics=None, predictor_names=(), value_name='error', statistic=None, min_count=0, scale=1.0, variance_offset=0.0, floor=0.0)#

Methods

__init__(kind[, value, grouped_statistics, ...])

constant(value)

Create an error magnitude that is the same for every observation.

predict([predictors])

Calculate the error magnitude for the supplied predictor values.

variable_from_grouped_stats(statistics, *[, ...])

Create an error magnitude that varies with observations, as described by grouped stats with predictor values.

Attributes

floor

grouped_statistics

min_count

predictor_names

reference_value

Return either the constant error magnitude, or the median of all valid groups for a variable error magnitude.

scale

statistic

value

value_name

variance_offset

kind