Spatiotemporal module

Spatiotemporal Analysis Module

This module provides tools for analyzing spatiotemporal environmental data, with a focus on Bayesian Maximum Entropy (BME) methods for optimal estimation and uncertainty quantification.

Main Components

BME Estimation

  • Optimal spatiotemporal prediction combining prior knowledge with data

  • Integration of hard (exact) and soft (probabilistic) observations

  • Local neighborhood-based estimation with adaptive data selection

  • Cross-validation for model performance assessment

Spatiotemporal Covariance

  • Empirical covariance calculation from spatiotemporal data

  • Theoretical covariance models (exponential, non-separable)

  • Directional (anisotropic) covariance analysis

  • Automated covariance model parameter fitting

Threshold-Based Indicators

  • Fractional area exceeding threshold (raeh)

  • Mean exceedance values (mew, wmew)

  • Mean difference exceedance (medw, wmdw)

  • Area-weighted indicators (aean)

  • Single-point moment extraction (one_point)

Multi-Criteria Decision Analysis

  • TOPSIS method for spatial prioritization

  • Multiple weighting schemes

  • Visualization and mapping tools

Raster Analysis

  • Spatiotemporal binary matrix generation

  • Input validation and preprocessing

  • NetCDF output generation

Examples

BME estimation workflow:
>>> import numpy as np
>>> from environmentaltools.spatiotemporal import (
...     compute_spatiotemporal_covariance,
...     fit_covariance_model,
...     compute_bme_moments
... )
>>>
>>> # Compute empirical covariance
>>> empcov, pairs, dists, distt = compute_spatiotemporal_covariance(
...     dfh, dfs, slag=np.linspace(0, 100, 20), tlag=np.linspace(0, 30, 10)
... )
>>>
>>> # Fit theoretical model
>>> import scipy.optimize as opt
>>> result = opt.minimize(
...     fit_covariance_model,
...     x0=[1.0, 20.0, 5.0, 0.1],
...     args=(empcov, [dists, distt], 'exponentialST')
... )
>>>
>>> # Compute BME moments
>>> moments = compute_bme_moments(
...     dfk, dfh, dfs, 'exponentialST', result.x,
...     nmax=[50, 100], dmax=[100, 30, 3], order=[1, 1],
...     options=[100, 3, 0.95], path='./cache', name='bme_run'
... )

This module provides comprehensive tools for spatiotemporal analysis of environmental data, with specialized functions for:

  • Bayesian Maximum Entropy (BME) estimation and uncertainty quantification

  • Spatiotemporal covariance modeling and fitting

  • Threshold-based indicators for risk and impact assessment

  • Multi-criteria decision analysis for spatial prioritization

  • Raster analysis for binary matrix generation and preprocessing

Bayesian Maximum Entropy

The BME framework provides optimal spatiotemporal estimation by combining prior knowledge with observational data (both exact and probabilistic). It’s particularly useful for environmental applications where data uncertainty must be quantified.

BME Estimation Functions

Core functions for performing BME spatiotemporal estimation.

compute_bme_moments(dfk, dfh, dfs, covmodel, ...)

Compute Bayesian Maximum Entropy moments for spatiotemporal estimation.

estimate_local_mean_bme(ck, ch, cs, zh, ms, ...)

Estimate local mean for Bayesian Maximum Entropy.

perform_cross_validation(dfh, dfs, zh, ...)

Perform k-fold cross-validation for BME model evaluation.

Support Functions

calculate_moments(zh, zs, vs, nhs, BsIFh, ...)

Calculate moments of the BME posterior probability density function.

integrate_moment_vector(ms, vs, ks, As, Bs, ...)

Compute moment integrals using the trapezoidal rule.

apply_data_smoothing(dfh, dfs, dfk, nmax, ...)

Apply spatial smoothing to hard and soft data.

Spatiotemporal Covariance

Functions for computing empirical covariances and fitting theoretical spatiotemporal covariance models (exponential, non-separable, directional).

compute_spatiotemporal_covariance(dfh, dfs, ...)

Compute empirical spatiotemporal covariance.

fit_covariance_model(param, empcovst, dist, name)

Compute sum of squared errors between theoretical and empirical covariance.

Advanced Covariance Functions

compute_directional_covariance(dfh, dfs, ...)

Compute spatiotemporal covariance for multiple directional bins.

calculate_theoretical_covariance(name, D, param)

Compute theoretical spatiotemporal covariance from parametric models.

Utility Functions

Helper functions for data preparation, neighborhood selection, and coordinate transformations.

select_neighbours(c0, c, z, nmax, dmax)

Select neighboring data points for local BME estimation.

estimate_bme_regression(c, z, order, k)

Compute parameter estimates for linear regression with covariance weighting.

create_design_matrix(c, order)

Create design matrix for polynomial regression.

smooth_data(ck, chs, zhs, v, nmax, dmax)

Apply spatial smoothing to data using exponential distance weighting.

create_spatiotemporal_matrix(dfh, dfs)

Create spatiotemporal data matrix.

coordinates_to_distance(pi, *args)

Compute distances between coordinate points.

coordinates_to_distance_angle(pi)

Compute distances and angles between spatial coordinate points.

find_pairs_by_distance(pi, plag, plagtol, *args)

Find pairs of points separated by specified distance intervals.

Threshold-Based Indicators

Functions for computing spatial indicators based on threshold exceedances. These indicators are useful for flood risk assessment, pollution exposure analysis, and environmental impact studies.

Key Indicators:

  • RAEH - Ratio of Area Exceeding thresHold: Fraction of spatial domain exceeding threshold

  • MEW - Mean Exceedance over Whole domain: Mean exceedance normalized by total area

  • MEDW - Mean Excess Difference over Whole domain: Mean excess above threshold over total area

  • WMEW - Weighted Mean Exceedance over exceedance area: Conditional mean given exceedance

  • WMDW - Weighted Mean excess Difference: Conditional mean excess given exceedance

  • AEAN - Area Exceeding to Area Non-exceeding: Ratio of exceedance to non-exceedance areas

Basic Indicators

fractional_exceedance_area(data[, thresholds])

Compute fractional area exceeding threshold values.

mean_exceedance_over_total_area(data[, ...])

Compute mean value of exceedances normalized by total area.

mean_excess_over_total_area(data[, thresholds])

Compute mean excess (difference from threshold) normalized by total area.

mean_exceedance_over_exceedance_area(data[, ...])

Compute mean value of exceedances normalized by exceedance area only.

mean_excess_over_exceedance_area(data[, ...])

Compute mean excess (difference from threshold) over exceedance area only.

exceedance_to_nonexceedance_ratio(data[, ...])

Compute ratio of exceedance area to non-exceedance area.

Spatiotemporal Extent Indicators

mean_presence_boundary(data_cube[, threshold])

Calculate spatial boundary where temporal mean exceeds a presence threshold.

maximum_influence_extent(data_cube[, percentile])

Calculate maximum spatial extent under extreme conditions.

threshold_exceedance_frequency(data_cube, ...)

Calculate frequency of threshold exceedance for each spatial cell.

permanently_affected_zone(data_cube, threshold)

Calculate permanently affected zones based on threshold exceedance persistence.

mean_representative_value(data_cube[, ...])

Calculate representative mean value for each spatial cell.

Extreme Value and Risk Indicators

return_period_extreme_value(data_series, ...)

Fit Generalized Extreme Value distribution and calculate return period value.

environmental_risk(data_cube, threshold[, size])

Calculate environmental risk as frequency of extreme values combined with polarization.

functional_area_loss(data_cube, threshold, ...)

Calculate functional area loss between two time points.

critical_boundary_retreat(data_cube, ...)

Calculate critical boundary retreat between two time points.

Spatial Dynamics Indicators

spatial_change_rate(data_cube[, dx, dy])

Calculate mean spatial change rate for each cell over time.

directional_influence(data_cube[, dx, dy])

Calculate mean direction of spatial gradient for each cell.

environmental_convergence(data_cube[, size])

Calculate environmental convergence as reduction of neighborhood differences over time.

Neighborhood Analysis

neighbourhood_mean(data_cube[, size])

Calculate neighborhood mean value for each cell.

neighbourhood_gradient_influence(data_cube)

Calculate gradient magnitude between each cell and its neighborhood.

neighbourhood_polarization(data_cube[, size])

Calculate polarization as local standard deviation.

local_persistence(data_cube[, size])

Calculate local persistence as proportion of time cell exceeds its neighborhood.

Multivariate Analysis

multivariate_neighbourhood_synergy(cube_list)

Calculate neighborhood synergy between multiple variables.

spatiotemporal_coupling(cube_x, cube_y)

Calculate spatiotemporal coupling between two variables.

multivariate_threshold_exceedance(cube_list, ...)

Calculate frequency of simultaneous threshold exceedance for multiple variables.

directional_coevolution(cube_x, cube_y)

Calculate directional coevolution between two variables.

multivariate_persistence(cube_list, thresholds)

Calculate multivariate persistence as proportion of time with simultaneous conditions.

Multi-Criteria Decision Analysis

TOPSIS (Technique for Order of Preference by Similarity to Ideal Solution) method for spatial prioritization. Useful for site selection, restoration planning, and resource allocation based on multiple environmental criteria.

Features:

  • Multiple weighting schemes (equal, entropy, analytical hierarchy process)

  • Comprehensive visualization (ranking maps, isolines, bar charts)

  • Sensitivity analysis across weighting methods

  • Statistical summaries and publication-ready outputs

run_topsis_mcda(combined_df, weighting_name, ...)

Execute TOPSIS multi-criteria decision analysis on the combined suitability scores.

create_weights_visualization(weight_results, ...)

Create visualization comparing different weighting schemes.

create_topsis_maps(topsis_results, output_dir)

Create spatial maps of TOPSIS scores for different weighting methods.

Raster Analysis

Functions for processing spatiotemporal raster data, including configuration management, binary matrix generation for threshold exceedances, input validation, and NetCDF output creation.

Capabilities:

  • Configuration file validation and loading

  • Temporal difference analysis for change detection

  • Input validation and preprocessing

  • Post-treatment data preparation and refinement

  • Binary matrix generation for threshold analysis

  • Temporal aggregation (annual, seasonal)

  • NetCDF format output with metadata

largest_region_from_field(batches)

Selects the largest region from a continuous field and returns its contour.

preprocess(ds)

Expand the dataset by adding a 'simulation' dimension using the 'simulation' attribute.

check_inputs(info)

Validate and prepare input configuration for marine spatial analysis processing.

compute_contours(continuous_stack, info)

Compute the largest connected contour for each time slice in a 3D raster stack.

analysis([info])

Execute the complete spatiotemporal raster analysis workflow.

obtain_geometry(contour, info)

Convert a contour represented by pixel indices to a real-world geometry.

save_layer(records, info)

Save a set of geometry records as a spatial layer (GeoPackage or Shapefile).

save_contours(contours, info)

Save extracted contour geometries to disk as a spatial layer (GeoPackage or Shapefile).

save_arrays_to_netcdf(arrays, info)

Save a list of arrays (per percentile) to a NetCDF file with spatial coordinates and metadata.

load_results(results_path)

Load indicator analysis results from a results directory (JSON + NPZ format).