geoutils.ErrorStructure

class geoutils.ErrorStructure(components, *, empirical_variogram=None, fit_diagnostics=None, metadata=None)

Error structure, a sum of independent error components of varying magnitude and autocorrelation.

The ErrorStructure class combines ErrorComponent objects, each with an error magnitude and spatial correlation, stored in components. Estimate it using estimate_error_structure() from a raster or point object, or ErrorStructure.estimate().

Use predict_magnitude() and predict_covariance() to compute values of magnitude and covariance according to the error model. Pass this object to an interpolation/reduction with uncertainty, or use generate_random_field() to draw errors over a raster or point cloud.

For example, to draw independent measurement errors with standard deviation 2 over a raster:

errors = ErrorStructure([ErrorComponent("measurement", magnitude=2.0)])
field = errors.generate_random_field(like=raster, random_state=42)

Combine measurement noise of 3 m with a spatial component of 4 m. Their variances add (9 m² + 16 m²), giving a total magnitude of 5 m (i.e. 25 m²):

import geoutils as gu
from geoutils.stats.variography import VariogramModel

measurement = gu.ErrorComponent("measurement", magnitude=3.0)
correlation = VariogramModel("spherical", effective_range=100, partial_sill=1)
spatial = gu.ErrorComponent("spatial", magnitude=4.0, correlation=correlation)
errors = gu.ErrorStructure([measurement, spatial])
errors.predict_magnitude()  # 5.0
errors.predict_covariance([0.0, 100.0])  # array([25., 0.])

__init__(components, *, empirical_variogram=None, fit_diagnostics=None, metadata=None)

Construct a named collection of mutually independent error components.

Parameters:

• components (Mapping[str, ErrorComponent] | Sequence[ErrorComponent]) – Sequence of ErrorComponent objects, or a dictionary keyed by their names.

• empirical_variogram (Variogram | None) – Optional measured variogram used to estimate this model.

• fit_diagnostics (Mapping[str, Any] | None) – Optional details about how the model was fitted.

• metadata (Mapping[str, Any] | None) – Other information to store with the model.

Methods

__init__(components, *[, ...])	Construct a named collection of mutually independent error components.
estimate(error_proxy, *[, other, ...])	Estimate error structure from an error proxy variable.
generate_random_field([like, coordinates, ...])	Generate one or more error fields over a raster, point cloud, or set of coordinates.
info(*[, verbose])	Summarize the reusable error model and its components.
iter_samples(source_ids, *[, coordinates, ...])	Yield random errors, or source values plus those errors, for the selected observations.
plot(**kwargs)	Plot every available magnitude and correlation diagnostic.
plot_correlation([ax, show_error])	Plot the empirical and combined fitted variogram.
plot_magnitude(*[, component, min_count])	Plot grouped magnitude statistics and sample counts.
predict_correlation(distance)	Summarize correlation across components using their typical error magnitudes.
predict_covariance(distance, *[, ...])	Calculate covariance for pairs of locations.
predict_magnitude([predictors, component, ...])	Calculate the error magnitude of one component or of all components together.
predict_variance([predictors, component])	Calculate the variance of one component or of all components together.
refit([correlation_models, fit_kwargs])	Refit correlations and their component magnitude contributions.
to_covariance_matrix(coordinates, *[, ...])	Calculate covariance between every pair of supplied coordinates.

Attributes

components	Return the components by name, as a mapping that cannot be modified.
required_predictors	List the predictors needed to calculate error magnitudes, in the order they first appear.