s2spy

s2spy: integrating expert knowledge and ai to boost S2S forecasting.

This package is a high-level python package integrating expert knowledge and artificial intelligence to boost (sub) seasonal forecasting.

Subpackages

Submodules

Package Contents

Classes

RGDR

Response Guided Dimensionality Reduction.
class s2spy.RGDR(target_intervals: int | list[int], lag: int, eps_km: float, alpha: float, min_area_km2: float | None = None)[source]

Response Guided Dimensionality Reduction.

property target_intervals: list[int]

Return target intervals.

property precursor_intervals: list[int]

Return precursor intervals.

property cluster_map: xarray.DataArray

Return cluster map.

property pval_map: xarray.DataArray

Return p-value map.

property corr_map: xarray.DataArray

Return correlation map.

get_correlation(precursor: xarray.DataArray, target: xarray.DataArray) → tuple[xarray.DataArray, xarray.DataArray][source]

Calculate the correlation and p-value between input precursor and target.

Parameters:

  • precursor – Precursor field data with the dimensions ‘latitude’, ‘longitude’, and ‘anchor_year’

  • target – Timeseries data with only the dimension ‘anchor_year’

Returns:

DataArrays containing the correlation and p-value.

Return type:

(correlation, p_value)

get_clusters(precursor: xarray.DataArray, target: xarray.DataArray) → xarray.DataArray[source]

Generate clusters for the precursor data.

Parameters:

  • precursor – Precursor field data with the dimensions ‘latitude’, ‘longitude’, ‘anchor_year’, and ‘i_interval’

  • target – Target timeseries data with only the dimensions ‘anchor_year’ and ‘i_interval’

Returns:

DataArray containing the clusters as masks.

preview_correlation(precursor: xarray.DataArray, target: xarray.DataArray, add_alpha_hatch: bool = True, ax1: matplotlib.pyplot.Axes | None = None, ax2: matplotlib.pyplot.Axes | None = None) → list[matplotlib.collections.QuadMesh][source]

Preview correlation and p-value results with given inputs.

Generate a figure showing the correlation and p-value results with the initiated RGDR class and input precursor field.

Parameters:

  • precursor – Precursor field data with the dimensions ‘latitude’, ‘longitude’, ‘anchor_year’, and ‘i_interval’

  • target – Target timeseries data with only the dimensions ‘anchor_year’ and ‘i_interval’

  • add_alpha_hatch – Adds a red hatching when the p-value is lower than the RGDR’s ‘alpha’ value.

  • ax1 – a matplotlib axis handle to plot the correlation values into. If None, an axis handle will be created instead.

  • ax2 – a matplotlib axis handle to plot the p-values into. If None, an axis handle will be created instead.

Returns:

List of matplotlib QuadMesh artists.

preview_clusters(precursor: xarray.DataArray, target: xarray.DataArray, ax: matplotlib.pyplot.Axes | None = None, **kwargs) → matplotlib.collections.QuadMesh[source]

Preview clusters.

Generates a figure showing the clusters resulting from the initiated RGDR class and input precursor field.

Parameters:

  • precursor – Precursor field data with the dimensions ‘latitude’, ‘longitude’, ‘anchor_year’, and ‘i_interval’

  • target – Target timeseries data with only the dimensions ‘anchor_year’ and ‘i_interval’

  • ax (plt.Axes, optional) – a matplotlib axis handle to plot the clusters into. If None, an axis handle will be created instead.

  • **kwargs – Keyword arguments that should be passed to QuadMesh.

Returns:

Matplotlib QuadMesh artist.

fit(precursor: xarray.DataArray, target: xarray.DataArray)[source]

Fit RGDR clusters to precursor data.

Performs DBSCAN clustering on a prepared DataArray, and then groups the data by their determined clusters, using an weighted mean. The weight is based on the area of each grid cell.

Density-Based Spatial Clustering of Applications with Noise (DBSCAN) clusters gridcells together which are of the same sign and in proximity to each other using DBSCAN.

Clusters labelled with a positive value represent a positive correlation with the target timeseries, the clusters labelled with a negative value represent a negative correlation. All locations not in a cluster are grouped together under the label ‘0’.

Parameters:

  • precursor – Precursor field data with the dimensions ‘latitude’, ‘longitude’, ‘anchor_year’, and ‘i_interval’

  • target – Target timeseries data with only the dimensions ‘anchor_year’ and ‘i_interval’, which will be correlated with the precursor field.

Returns:

The precursor data, with the latitute and longitude dimensions

reduced to clusters.

Return type:

xr.DataArray

transform(data: xarray.DataArray) → xarray.DataArray[source]

Apply RGDR on the input data, based on the previous fit.

Transform will use the clusters previously generated when RGDR was fit, and use these clusters to reduce the latitude and longitude dimensions of the input data.

fit_transform(precursor: xarray.DataArray, timeseries: xarray.DataArray)[source]

Fit RGDR clusters to precursor data, and applies RGDR on the input data.

Parameters:

  • precursor – Precursor field data with the dimensions ‘latitude’, ‘longitude’, and ‘anchor_year’

  • timeseries – Timeseries data with only the dimension ‘anchor_year’, which will be correlated with the precursor field.

Returns:

The precursor data, with the latitute and longitude dimensions

reduced to clusters.

Return type:

xr.DataArray

__repr__() → str[source]

Represent the RGDR transformer with strings.