environmentaltools.temporal.dependencies

environmentaltools.temporal.dependencies(df: DataFrame, param: dict)[source]

Fit temporal dependency structure using Vector Autoregression (VAR) model.

Estimates multivariate temporal dependencies between environmental variables following Solari & van Gelder (2011) and Solari & Losada (2011) methodology.

Parameters:

  • df (pd.DataFrame) – Raw time series with datetime index containing all variables

  • param (dict) –

    Parameters for dependency analysis with nested structure:

    • TDdict

      Temporal dependency parameters:

      • varslist

        Names of variables to include in dependency analysis

      • methodstr

        Dependency method (‘VAR’ for Vector Autoregression)

      • orderint

        Order of the VAR model (lag length)

      • mvarstr, optional

        Main variable for event-based analysis

      • thresholdfloat, optional

        Threshold of main variable for event identification

      • eventsbool, optional

        If True, analyze only storm events. Default: False

      • not_save_errorbool, optional

        If True, exclude error time series from output. Default: False

      • file_namestr, optional

        Output file name for saving results

    • {var_name}dict (for each variable in vars)

      Marginal distribution parameters from fit_marginal_distribution

Returns:

Dictionary with fitted VAR model parameters including: - Autoregression coefficients - Model order and diagnostics - Variable transformations - Error statistics

Return type:

dict

Notes

The function:

  1. Transforms variables to uniform marginals using fitted CDFs

  2. Fits VAR model to transformed data

  3. Estimates temporal dependency structure

  4. Saves results to JSON file if file_name specified

For circular variables (e.g., directions), converts to radians before analysis.

References

Solari, S., & van Gelder, P. H. A. J. M. (2011). On the use of vector autoregressive (VAR) and regime switching VAR models for the simulation of sea and wind state parameters. Probabilistic Engineering Mechanics.

Solari, S., & Losada, M. A. (2011). A unified statistical model for hydrological variables including the selection of threshold for the peak over threshold method. Water Resources Research.

Lira-Loarca, A., et al. (2020). A global classification of coastal flood hazard climates. Scientific Reports.

Examples

>>> param = {
...     'TD': {
...         'vars': ['Hs', 'Tp', 'Dir'],
...         'method': 'VAR',
...         'order': 3,
...         'events': False,
...         'file_name': 'dependency_results'
...     },
...     'Hs': {...},  # from fit_marginal_distribution
...     'Tp': {...},  # from fit_marginal_distribution
...     'Dir': {...}  # from fit_marginal_distribution
... }
>>> df_dt = dependencies(df, param)