Fitting API

pyCRO.fitting.RO_fitting(T, h, par_option_T, par_option_h, par_option_noise, method_fitting=None, dt=None, verbose=True)

Fit the Recharge Oscillator (RO) model parameters to T and h time series.

This function performs parameter fitting for the RO system, using the specified prescribed parameter options and noise characteristics. Fitting can be done via linear regression (LR) or maximum likelihood estimation (MLE), with optional handling for multiplicative or additive noise. It can automatically select a default fitting method based on parameter options.

Parameters:

• T (ndarray, shape (N,) or (N, 1)) – Time series of SST anomalies (1D array).

• h (ndarray, shape (N,) or (N, 1)) – Time series of thermocline anomalies (1D array).

• par_option_T (dict) –

  Prescribed options for SST equation parameters.

  Keys (R, F1, b_T, c_T, d_T):

  Each entry Xi ∈ {0, 1, 3, 5}:

  0 : parameter not included

  1 : seasonally constant

  3 : annual cycle

  5 : annual + semiannual cycle

• par_option_h (dict) –

  Prescribed options for thermocline equation parameters.

  Keys (F2, epsilon, b_h):

  Each entry Xi ∈ {0, 1, 3, 5}:

  0 : parameter not included

  1 : seasonally constant

  3 : annual cycle

  5 : annual + semiannual cycle

• par_option_noise (dict) –

  Configuration of stochastic noise forcing in the RO system.

  Keys:

  T{“white”, “red”}

  Noise type in SST equation.

  h{“white”, “red”}

  Noise type in thermocline equation (must be identical to T).

  T_type{“additive”, “multiplicative”, “multiplicative-H”}

  Noise formulation:

  additive : state-independent forcing

  multiplicative : state-dependent forcing

  multiplicative-H : Heaviside-modulated multiplicative forcing

  Notes:

  • T and h must be identical.

  • Independent SST and thermocline noise structures are not supported.

• method_fitting (str, optional) –

  Parameter estimation method:

  LR-F : Linear regression (forward difference)

  LR-C : Linear regression (central difference)

  LR-F-MAC : LR-F with moment-adjusted correction for SST noise

  MLE : Maximum likelihood estimation

  If None, the method is selected automatically based on model configuration.

• dt (float, optional (default = 1.0)) – Time step of input time series in months.

• verbose (bool, optional (default=True)) – If True, prints fitting information and progress.

Returns:

Dictionary of fitted CRO parameters: Keys include: ‘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’.

Return type:

dict

Notes

• Automatically removes mean from input time series.

• Applies Ito-to-Stratonovich correction for multiplicative noise.

• Negligible seasonal amplitudes are rounded to zero.

• Ensures consistent noise settings for T and h equations.

• Prints a summary of the fitting process if verbose is True.

Examples

>>> par_option_T = {'mean': 1, 'seasonal': 3, 'semi_annual': 0, ...}
>>> par_option_h = {'mean': 1, 'seasonal': 3, 'semi_annual': 0, ...}
>>> par_option_noise = {'T': 'red', 'h': 'red', 'T_type': 'multiplicative'}
>>> fitted_params = RO_fitting(T, h, par_option_T, par_option_h, par_option_noise)
>>> print(fitted_params['sigma_T'])

pyCRO.fit_LR.fit_LR(T, h, par_option_T, par_option_h, par_option_noise, dt, tend_option, fitting_option_B, fitting_option_red)

Estimates Recharge Oscillator (RO) parameters with linear regression (LR) given ENSO SST (T) and thermocline depth (h) anomaly time series.

Parameters:

• T (array_like) – Time series of SST anomalies (1D).

• h (array_like) – Time series of thermocline depth anomalies (1D).

• par_option_T (array_like) –

  Seasonal fitting options for the T-equation terms. Values must be one of:

  • 0 : constant zero

  • 1 : constant non-zero

  • 3 : annual variation

  • 5 : annual + semi-annual variation

• par_option_h (array_like) – Seasonal fitting options for the h-equation terms (same coding as above).

• par_option_noise (array_like of length 3) –

  Noise fitting options [n_T, n_h, n_g]:

  • n_T : 0 = red, 1 = white

  • n_h : 0 = red, 1 = white

  • n_g0 = multiplicative (full),

    1 = multiplicative (Heaviside), 2 = additive

• dt (float) – Time step (in months).

• tend_option ({"F", "C"}) –

  Option for numerical derivative:

  • ”F” : forward difference

  • ”C” : centered difference

• fitting_option_B ({"MAC", "LR"}) –

  Method for estimating multiplicative noise amplitude B:

  • ”MAC” : Moment Approximation Calibration

  • ”LR” : Linear regression

• fitting_option_red ({"LR", "AR1", "ARn"}) –

  Method for fitting red noise memory:

  • ”LR” : regression of residual derivative

  • ”AR1” : lag-1 autocorrelation

  • ”ARn” : regression using autocorrelation decay

Returns:

final_par –

Stacked parameter array including:

• Deterministic T-equation parameters (seasonalized)

• Deterministic h-equation parameters (seasonalized)

• Noise parameters:

  [sigma_T, sigma_h, B, m_T, m_h, n_T, n_h, n_g]

Return type:

ndarray, shape (N, 5)

Notes

• Seasonal terms are expanded into constant, annual, and semi-annual components depending on the fitting options.

• Noise fitting can handle white/red and additive/multiplicative cases.

• If multiplicative noise is selected and fitting_option_B=”MAC”, the MAC method overwrites sigma_T and B.

pyCRO.fit_MLE.fit_MLE(T, h, par_option_T, par_option_h, par_option_noise, dt)

Estimate recharge oscillator (RO) parameters using Maximum Likelihood Estimation (MLE)

Parameters:

• T (array_like) – Time series of SST anomalies (1D).

• h (array_like) – Time series of thermocline depth anomalies (1D).

• par_option_T (array_like) – Switches for which SST-related parameters to include (0=off, 1=on, 3=annual, 5=annual+semiannual).

• par_option_h (array_like) – Switches for which h-related parameters to include (same coding).

• par_option_noise (array_like of length 3) –

  Noise structure options [n_T, n_h, n_g]: - n_T : noise option for T-equation - n_h : noise option for h-equation - n_g : type of multiplicative noise term

  • 0 = linear multiplicative (B*T)

  • 1 = Heaviside multiplicative (B*H(T)*T)

  • 2 = additive (B=0)

• dt (float) – Time step (months).

Returns:

par – Final estimated parameter set including deterministic RO parameters, seasonal amplitudes/phases, and red noise variances.

Return type:

ndarray

Notes

• Implements iterative forward filtering and backward smoothing to estimate hidden noise states.

• This function may take a long time to converge (default 10 iterations, could be increased for accuracy).

pyCRO.fit_MAC.fit_MAC(T, h, par)

Estimate the Recharge Oscillator (RO) model multiplicative noise parameters using Moment Analytical Constraint (MAC), specifically the SST noise amplitude (sigma_T) and multiplicative coefficient (B).

MAC is a constraint-based estimation method that exploits analytical relationships between model parameters and the higher-order statistical moments of the system. In particular, it uses moment equations derived from the RO stochastic dynamics to relate third- and fourth-order moments of SST (T) and thermocline (h) to the unknown noise parameters.

Unlike purely statistical or correlation-based methods, MAC is derived from exact or approximate analytical moment constraints of the governing stochastic differential equations. It provides a physically consistent estimation of noise parameters by enforcing agreement between observed and theoretical moment structures.

In the CRO/RO implementation, MAC is applied after deterministic parameters are estimated (typically via linear regression), and assumes all non-noise parameters are known.

Parameters:

• T (ndarray, shape (N,) or (N, 1)) – SST anomaly time series.

• h (ndarray, shape (N,) or (N, 1)) – Thermocline depth anomaly time series.

• par (ndarray) –

  RO parameter matrix with previously estimated deterministic parameters.

  Expected structure:

  • par[0,0] : R

  • par[1,0] : F1

  • par[2,0] : b_T

  • par[3,0] : c_T

  • par[4,0] : d_T

  • par[5,0] : epsilon

  • par[6,0] : F2

  • par[8,0] : sigma_T (updated by MAC)

  • par[10,0] : B (updated by MAC)

  • par[15,0] : n_g (noise structure flag)

Returns:

par_out –

Updated parameter matrix with MAC-estimated noise parameters.

• sigma_T : SST noise amplitude

• B : multiplicative noise coefficient

Return type:

ndarray

Notes

Moment Analytical Constraint (MAC):

• MAC is a moment-based analytical constraint method.

• It is NOT a correlation-based or regression-based estimator.

• It enforces consistency between empirical moments and analytically derived moment equations from the RO system.

Specifically: - Uses third- and fourth-order moments of T and h - Matches empirical moments to theoretical RO moment expressions - Solves resulting constraint equations for sigma_T and B

Methodology:

• Deterministic parameters are assumed known (from LR fitting)

• Empirical moments of T and h are computed

• Analytical moment constraints are solved for noise parameters

Noise regimes:

n_g = 0 : linear multiplicative noise n_g = 1 : Heaviside-modulated multiplicative noise

Examples

>>> par_updated = fit_MAC(T, h, par)
>>> sigma_T = par_updated[8, 0]
>>> B = par_updated[10, 0]