Data API

pyCRO.data.ROdata_calc(sst_a: DataArray, h_a: DataArray, sst_regions=None, h_regions=None) → Dataset

Compute Recharge Oscillator SST and thermocline/heat-content indices.

Parameters:

• sst_a (xr.DataArray) – Sea surface temperature with dimensions (time, lat, lon).

• h_a (xr.DataArray) – Thermocline depth, heat content, SSH, or another recharge proxy with dimensions (time, lat, lon).

• sst_regions (list of str or dict, optional) –

  SST regions to compute.

  • None (default): compute all predefined SST regions.

  • list of str: predefined region names (e.g., ["Nino34", "Nino3"]).

  • dict: mapping from output names to custom region definitions.

• h_regions (list of str or dict, optional) –

  Thermocline/heat-content regions to compute.

  • None (default): compute all predefined thermocline regions.

  • list of str: predefined region names.

  • dict: mapping from output names to custom region definitions.

Returns:

Dataset containing the requested SST and thermocline indices.

Return type:

xr.Dataset

Examples

Compute all predefined SST and thermocline indices:

ds = ROdata_calc(sst, h)

Compute only the Niño-3.4 SST index:

ds = ROdata_calc(sst, h, sst_regions=["Nino34"])

Compute selected thermocline indices:

ds = ROdata_calc(sst, h, h_regions=["Hw", "He"])

Define a custom SST region:

ds = ROdata_calc(
    sst,
    h,
    sst_regions={
        "CP": {
            "latS": -5,
            "latN": 5,
            "lonW": 170,
            "lonE": 220,
        }
    },
)

pyCRO.data.ROdata_load(name: str)

Load precomputed CRO dataset time series.

This function provides access to built-in ENSO-related datasets used in the CRO (Coupled Recharge Oscillator) framework, including ORAS5 reanalysis, CMIP6 historical simulations, and CESM1 LENS.

Parameters:

name (str) –

Name of the dataset to load.

Supported options:

• ”CESM1_LENS”

  CESM1 Large Ensemble Niño3.4 and thermocline time series.

• ”CMIP6”

  Preprocessed CMIP6 historical ENSO time series (multi-model mean or ensemble form).

• ”ORAS5”

  ORAS5 ocean reanalysis ENSO time series.

Returns:

Absolute file path to the requested NetCDF dataset.

Return type:

str

Raises:

ValueError – If data_name is not one of the supported options.

Notes

• Data are stored inside the pyCRO.data package directory.

• Files are in NetCDF format and should be opened using xarray.open_dataset.

• This function does not load the dataset into memory, only returns the path.

Examples

Load CESM1 LENS data:

>>> ds = pyCRO.ROdata_load("CESM1_LENS")

Load ORAS5 reanalysis:

>>> ds = pyCRO.ROdata_load("ORAS5")

pyCRO.data.area_average_regions(x, regions)

Compute cosine-weighted regional averages.

Parameters:

• x (xr.DataArray) – Input field.

• regions (list of str or dict) –

  Regions to average.

  • list of str

    Predefined region names.

  • dict

    Mapping from output variable names to region definitions.

Returns:

Dataset containing one variable per region.

Return type:

xr.Dataset

pyCRO.data.par_load(data_name: str, ro_name: str)

Load precomputed CRO parameters from CRO_parlib_v0.0.mat.

This function extracts parameter sets for different RO model configurations and datasets (e.g., CMIP6 historical runs, ORAS5, etc.).

See details at precomputed Library

Parameters:

• data_name (str) –

  Dataset identifier. Supported options include:

  • ”ORAS5”

  • ”CMIP6-historical-1” … “CMIP6-historical-48”

  • ”CMIP6-historical-all” (returns all realizations)

• ro_name (str) –

  Recharge Oscillator model configuration. Supported options:

  • ”Linear-White-Additive”

  • ”Seasonal-Linear-White-Additive”

  • ”Nonlinear-White-Additive”

  • ”Seasonal-Nonlinear-White-Additive”

  • ”Linear-White-Multiplicative”

  • ”Seasonal-Linear-White-Multiplicative”

  • ”Nonlinear-White-Multiplicative”

  • ”Seasonal-Nonlinear-White-Multiplicative”

Returns:

If data_name != “CMIP6-historical-all”:

Returns a dictionary containing CRO parameters:

• R, F1, F2, epsilon, b_T, c_T, d_T, b_h

• sigma_T, sigma_h, B

• m_T, m_h, n_T, n_h, n_g

Each value is a list (to support scalar or ensemble formats).

If data_name == “CMIP6-historical-all”:

Returns a list of parameter dictionaries, one per CMIP6 realization.

Return type:

dict or list of dict

Raises:

ValueError – If ro_name is not recognized or data_name is invalid.

Notes

• The parameter library is stored in MATLAB file format (.mat).

• Internally, parameters are indexed as:

  (RO configuration index, dataset index).

• This function automatically handles scalar, vector, and empty entries from MATLAB cell arrays.

Examples

>>> par = par_load("ORAS5", "Linear-White-Additive")
>>> par["R"]

>>> pars = par_load("CMIP6-historical-all", "Nonlinear-White-Additive")
>>> len(pars)