s2spy ===== .. py:module:: s2spy .. autoapi-nested-parse:: 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 ----------- .. toctree:: :maxdepth: 1 /autoapi/s2spy/rgdr/index Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/s2spy/preprocess/index Classes ------- .. autoapisummary:: s2spy.RGDR Package Contents ---------------- .. py:class:: RGDR(target_intervals: Union[int, list[int]], lag: int, eps_km: float, alpha: float, min_area_km2: Optional[float] = None) Response Guided Dimensionality Reduction. .. py:attribute:: _lag .. py:attribute:: _dbscan_params .. py:attribute:: _target_intervals .. py:attribute:: _precursor_intervals .. py:attribute:: _corr_map :type: Union[None, xarray.DataArray] :value: None .. py:attribute:: _pval_map :type: Union[None, xarray.DataArray] :value: None .. py:attribute:: _cluster_map :type: Union[None, xarray.DataArray] :value: None .. py:attribute:: _area :value: None .. py:property:: target_intervals :type: list[int] Return target intervals. .. py:property:: precursor_intervals :type: list[int] Return precursor intervals. .. py:property:: cluster_map :type: xarray.DataArray Return cluster map. .. py:property:: pval_map :type: xarray.DataArray Return p-value map. .. py:property:: corr_map :type: xarray.DataArray Return correlation map. .. py:method:: get_correlation(precursor: xarray.DataArray, target: xarray.DataArray) -> tuple[xarray.DataArray, xarray.DataArray] Calculate the correlation and p-value between input precursor and target. :param precursor: Precursor field data with the dimensions 'latitude', 'longitude', and 'anchor_year' :param target: Timeseries data with only the dimension 'anchor_year' :returns: DataArrays containing the correlation and p-value. :rtype: (correlation, p_value) .. py:method:: get_clusters(precursor: xarray.DataArray, target: xarray.DataArray) -> xarray.DataArray Generate clusters for the precursor data. :param precursor: Precursor field data with the dimensions 'latitude', 'longitude', 'anchor_year', and 'i_interval' :param target: Target timeseries data with only the dimensions 'anchor_year' and 'i_interval' :returns: DataArray containing the clusters as masks. .. py:method:: preview_correlation(precursor: xarray.DataArray, target: xarray.DataArray, add_alpha_hatch: bool = True, ax1: Optional[matplotlib.pyplot.Axes] = None, ax2: Optional[matplotlib.pyplot.Axes] = None) -> list[matplotlib.collections.QuadMesh] 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. :param precursor: Precursor field data with the dimensions 'latitude', 'longitude', 'anchor_year', and 'i_interval' :param target: Target timeseries data with only the dimensions 'anchor_year' and 'i_interval' :param add_alpha_hatch: Adds a red hatching when the p-value is lower than the RGDR's 'alpha' value. :param ax1: a matplotlib axis handle to plot the correlation values into. If None, an axis handle will be created instead. :param 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. .. py:method:: preview_clusters(precursor: xarray.DataArray, target: xarray.DataArray, ax: Optional[matplotlib.pyplot.Axes] = None, **kwargs) -> matplotlib.collections.QuadMesh Preview clusters. Generates a figure showing the clusters resulting from the initiated RGDR class and input precursor field. :param precursor: Precursor field data with the dimensions 'latitude', 'longitude', 'anchor_year', and 'i_interval' :param target: Target timeseries data with only the dimensions 'anchor_year' and 'i_interval' :param ax: a matplotlib axis handle to plot the clusters into. If None, an axis handle will be created instead. :type ax: plt.Axes, optional :param \*\*kwargs: Keyword arguments that should be passed to QuadMesh. :returns: Matplotlib QuadMesh artist. .. py:method:: fit(precursor: xarray.DataArray, target: xarray.DataArray) 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'. :param precursor: Precursor field data with the dimensions 'latitude', 'longitude', 'anchor_year', and 'i_interval' :param 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. :rtype: xr.DataArray .. py:method:: transform(data: xarray.DataArray) -> xarray.DataArray 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. .. py:method:: fit_transform(precursor: xarray.DataArray, timeseries: xarray.DataArray) Fit RGDR clusters to precursor data, and applies RGDR on the input data. :param precursor: Precursor field data with the dimensions 'latitude', 'longitude', and 'anchor_year' :param 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. :rtype: xr.DataArray .. py:method:: __repr__() -> str Represent the RGDR transformer with strings.