pygeostats.variogram

Variogram modeling and analysis.

AnisotropyResult dataclass

AnisotropyResult(is_anisotropic: bool, major_direction: float, minor_direction: float, anisotropy_ratio: float, ranges: Dict[float, float], sill: float, diagnostics: Dict[str, float])

Summary of detected geometric anisotropy.

DirectionalVariogram

DirectionalVariogram(coordinates: ndarray, values: ndarray, directions: Optional[Sequence[float]] = None, tolerance: float = 22.5, bandwidth: Optional[float] = None, max_distance: Optional[float] = None, n_bins: int = 12, bin_edges: Optional[ndarray] = None)

Directional empirical variogram computation.

Parameters:

Name	Type	Description	Default
coordinates	(array - like, shape(n_samples, 2))	Sampling locations. Only planar (2D) coordinates are supported.	required
values	(array - like, shape(n_samples))	Sample values.	required
directions	sequence of float	Directions (degrees) for which directional variograms are computed, measured counter-clockwise from the x-axis. A direction and its opposite select the same pairs. Defaults to (0, 45, 90, 135) if not provided.	None
tolerance	float	Angular tolerance (degrees) defining the half-window around each direction.	22.5
bandwidth	float	Maximum perpendicular distance (same units as coordinates) allowed when classifying pairs within a directional sector. If None no limit is applied.	None
max_distance	float	Maximum separation distance considered. Defaults to half of the maximum pairwise distance.	None
n_bins	int	Number of lag bins.	12
bin_edges	array - like	Custom bin edges. If provided n_bins is ignored.	None

is_fitted property

is_fitted: bool

Whether compute has been executed.

automatic_direction_set staticmethod

automatic_direction_set(coords: ndarray, n_directions: int = 4) -> List[float]

Return evenly spaced directions aligned with principal axes.

compute

compute() -> DirectionalVariogram

Compute directional variograms for the configured directions.

directional_summary

directional_summary() -> Dict[float, Dict[str, np.ndarray]]

Return a dictionary summarising directional variograms.

detect_anisotropy

detect_anisotropy(sill_fraction: float = 0.95, ratio_threshold: float = 1.2, range_difference: float = 0.0) -> AnisotropyResult

Detect geometric anisotropy from directional variograms.

Each direction's range is the first lag at which its variogram reaches sill_fraction of the largest semivariance in any direction, or its largest lag if it never does. With three or more directions an ellipse is fitted through those ranges: major_direction is the angle of its long axis, in degrees counter-clockwise from the x-axis in [0, 180), and anisotropy_ratio is its long axis over its short one. The ratio runs low, because ranges are capped at the largest lag and a noisy maximum sets the threshold, so treat it as a detection statistic rather than an estimate of the true ratio.

estimate_initial_parameters

estimate_initial_parameters(strategies: Optional[Sequence[str]] = None, min_weight: int = 5, sill_fraction: float = 0.95) -> NoReturn

Generate anisotropic variogram initialisation candidates.

Not implemented. This method was committed in feca441 calling estimate_anisotropy_initialization, and returning an AnisotropyInitializationSummary, neither of which was ever written. Use :class:~.initialization.InitializationEnsemble or :class:~.initialization.RangeInitializer directly instead; both are implemented and cover the same ground.

anisotropy_rose_data

anisotropy_rose_data() -> Tuple[np.ndarray, np.ndarray]

Return angles and ranges suitable for rose-diagram plotting.

EmpiricalVariogram

EmpiricalVariogram(coordinates: Union[ndarray, GeoDataFrame, DataFrame], values: Union[ndarray, Series], max_distance: Optional[float] = None, n_bins: int = 15, bin_edges: Optional[ndarray] = None)

Compute and analyze empirical variograms.

Parameters:

Name	Type	Description	Default
coordinates	(array - like, shape(n_samples, n_features))	Sample coordinates.	required
values	(array - like, shape(n_samples))	Sample values.	required
max_distance	float	Maximum distance for variogram computation. If None, uses half the maximum distance in the dataset.	None
n_bins	int	Number of distance bins.	15
bin_edges	array - like	Custom bin edges. If provided, overrides n_bins.	None

compute

compute() -> EmpiricalVariogram

Compute the empirical variogram.

Returns:

Name	Type	Description
self	EmpiricalVariogram	Returns self for method chaining.

plot

plot(ax=None, **kwargs)

Plot the empirical variogram.

Parameters:

Name	Type	Description	Default
ax	Axes	Axes to plot on. If None, creates new figure.	None
**kwargs		Additional arguments passed to matplotlib.pyplot.scatter.	{}

Returns:

Name	Type	Description
ax	Axes	The axes object.

Variogram

Variogram(model: str = 'exponential', nugget: float = 0.0, sill: Optional[float] = None, range: Optional[float] = None)

Bases: BaseEstimator

Theoretical variogram model.

Parameters:

Name	Type	Description	Default
model	str	Variogram model type. Options: 'exponential', 'spherical', 'gaussian', 'matern'.	'exponential'
nugget	float	Nugget effect (variance at distance 0).	0.0
sill	float	Sill (total variance). If None, estimated from data.	None
range	float	Range parameter. If None, estimated from data.	None

fit

fit(distances: ndarray, gamma: ndarray, weights: Optional[ndarray] = None, fix: Optional[Dict[str, bool]] = None) -> Variogram

Fit variogram model to empirical data.

Parameters:

Name	Type	Description	Default
distances	(array - like, shape(n_points))	Distance values.	required
gamma	(array - like, shape(n_points))	Semivariance values.	required
weights	(array - like, shape(n_points))	Weights for fitting. Typically the number of point pairs in each bin.	None
fix	dict	Dictionary indicating parameters to keep fixed during optimisation. Accepted keys: "nugget", "sill", "range". Example: {"nugget": True}.	None

Returns:

Name	Type	Description
self	Variogram	Returns self for method chaining.

predict

predict(distances: ndarray) -> np.ndarray

Predict semivariance at given distances.

Parameters:

Name	Type	Description	Default
distances	(array - like, shape(n_points))	Distance values to predict at.	required

Returns:

Name	Type	Description
gamma	(ndarray, shape(n_points))	Predicted semivariance values.

covariance

covariance(distances: ndarray) -> np.ndarray

Calculate covariance at given distances.

Parameters:

Name	Type	Description	Default
distances	(array - like, shape(n_points))	Distance values.	required

Returns:

Name	Type	Description
cov	(ndarray, shape(n_points))	Covariance values.

StreamingVariogramBuilder

StreamingVariogramBuilder(bin_edges: NumericArray)

Incremental variogram computation helper.

StreamingVariogramDenseResult dataclass

StreamingVariogramDenseResult(centers: ndarray, gamma: ndarray, weights: ndarray)

Dense representation of a streaming variogram outcome.

as_array

as_array() -> np.ndarray

Return columns suitable for dataframe construction.

to_sparse

to_sparse() -> StreamingVariogramSparseResult

Convert to sparse representation by filtering non-zero bins.

StreamingVariogramSparseResult dataclass

StreamingVariogramSparseResult(indices: ndarray, centers: ndarray, gamma: ndarray, weights: ndarray, bin_edges: Optional[ndarray], bin_centers: ndarray, total_weight: float)

Sparse representation storing only populated bins.

to_coo

to_coo() -> sp.coo_matrix

Return a COO matrix with semivariances in a single column.

as_array

as_array() -> np.ndarray

Return stacked columns for dataframe construction.

chunk_indices

chunk_indices(n_rows: int, chunk_size: int) -> Iterator[Tuple[int, int]]

Iterate over (start, end) pairs for chunked processing.

memory_map_array

memory_map_array(path: Union[str, Path], shape: Sequence[int], *, dtype: dtype = np.float64, mode: str = 'r') -> np.memmap

Return a numpy.memmap for the provided path and shape.

streaming_variogram

streaming_variogram(coords: ndarray, values: ndarray, bin_edges: NumericArray, *, chunk_size: int = 2048, sparse: bool = False) -> Union[StreamingVariogramDenseResult, StreamingVariogramSparseResult]

Compute a variogram using chunked streaming blocks.

Parameters:

Name	Type	Description	Default
coords	ndarray	Coordinate matrix (n_samples, n_dims).	required
values	ndarray	Observation vector (n_samples,).	required
bin_edges	array - like	Monotonic increasing distance bin edges.	required
chunk_size	int	Number of points loaded into memory for each streaming block.	2048
sparse	bool	If True, return only populated bins.	False

streaming_variogram_memmap

streaming_variogram_memmap(coords_path: Union[str, Path], values_path: Union[str, Path], shape: Sequence[int], bin_edges: NumericArray, *, chunk_size: int = 2048, dtype: dtype = np.float64, mode: str = 'r', sparse: bool = False) -> Union[StreamingVariogramDenseResult, StreamingVariogramSparseResult]

Compute a streaming variogram backed by memory-mapped arrays.