API Reference

API Reference#

Obs#

class cfr.v2026.obs.Obs(df: DataFrame)#

Observation database for proxy records.

Manages a collection of proxy observations stored in a DataFrame, providing methods for setup, proxy system modeling, plotting, and conversion to xarray.

Parameters:

df (pd.DataFrame) – DataFrame with columns: pid, lat, lon, time, value, psm_name, R, type.

plotly(**kws)#

Plot the database on an interactive map utilizing Plotly

class cfr.v2026.obs.ProxyRecord(data: Series)#

A single proxy record extracted from the observation database.

Parameters:

data (pd.Series) – A row from the Obs DataFrame containing proxy metadata and values.

Prior#

class cfr.v2026.prior.PriorMember(ds)#

A single prior member from which ensemble samples can be generated.

Parameters:

ds (xr.Dataset or xr.DataArray) – Climate model output dataset to serve as a prior member.

gen_samples_Gaussian(local_sigma: dict, global_sigma: dict, nens: int = 100, seed: int = 0)#

Generate samples following Gaussian

Parameters:

  • sigma (dict) – Dictionary with standard deviation (sigma) for each variable.

  • nens (int) – Number of ensemble members to generate.

  • seed (int) – Seed for reproducibility.

gen_samples_bootstrap(nens: int = 30, clim_yrs: int = 50, seed: int = 0, dim='time')#

Generate samples from the prior pool

Args:

class cfr.v2026.prior.Prior(members)#

Prior ensemble constructed from one or more PriorMember instances.

Concatenates ensemble samples from prior members and provides methods for regridding, annualization, inflation, and state vector extraction.

Parameters:

members (PriorMember or list of PriorMember) – One or more prior members whose samples form the ensemble.

PSM#

class cfr.v2026.psm.IdenticalTS(record: ProxyRecord = None)#

Identity PSM for surface temperature (TS/tas).

Returns the climate model surface temperature directly as the pseudo-observation (no transformation applied).

Parameters:

record (ProxyRecord, optional) – The proxy record associated with this PSM.

class cfr.v2026.psm.IdenticalSST(record: ProxyRecord = None)#

Identity PSM for sea surface temperature (SST).

Returns the climate model SST directly as the pseudo-observation.

Parameters:

record (ProxyRecord, optional) – The proxy record associated with this PSM.

class cfr.v2026.psm.IdenticalSSS(record: ProxyRecord = None)#

Identity PSM for sea surface salinity (SSS).

Returns the climate model SSS directly as the pseudo-observation.

Parameters:

record (ProxyRecord, optional) – The proxy record associated with this PSM.

class cfr.v2026.psm.IdenticalSSTSSS(record: ProxyRecord = None)#

Identity PSM for combined SST + SSS.

Returns the sum of SST and SSS from the climate model as the pseudo-observation.

Parameters:

record (ProxyRecord, optional) – The proxy record associated with this PSM.

class cfr.v2026.psm.TEX86(record: ProxyRecord = None)#

PSM for TEX86 paleothermometry.

Converts SST to TEX86 values using the BAYWATCH forward model.

Parameters:

record (ProxyRecord, optional) – The proxy record associated with this PSM.

class cfr.v2026.psm.UK37(record: ProxyRecord = None)#

PSM for UK’37 paleothermometry.

Converts SST to UK’37 values using the BAYWATCH forward model.

Parameters:

record (ProxyRecord, optional) – The proxy record associated with this PSM.

class cfr.v2026.psm.MgCa(record: ProxyRecord = None)#

PSM for Mg/Ca paleothermometry.

Converts SST and SSS to Mg/Ca ratios using the BAYMAG forward model.

Parameters:

record (ProxyRecord, optional) – The proxy record associated with this PSM.

class cfr.v2026.psm.d18Oc(record: ProxyRecord = None)#

PSM for foraminiferal d18O of calcite.

Converts SST, SSS, and d18Osw to d18Oc using the BAYFOX forward model.

Parameters:

record (ProxyRecord, optional) – The proxy record associated with this PSM.

DA#

class cfr.v2026.enkf.Solver(prior=None, obs=None, prior_target=None)#

High-level data assimilation solver.

Orchestrates the full DA workflow: proxy system modeling, localization, ensemble update, and validation against truth.

Parameters:

  • prior (Prior) – The prior ensemble.

  • obs (Obs) – The observation database.

  • prior_target (Prior, optional) – Target prior for EnOI mode.

prep(recon_period=None, recon_season=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], localize=True, loc_method='gaspari_cohn', loc_radius=2500, dist_vsf=1, startover=False, get_clim_kws={}, **fwd_kws)#

Prepare Y=H(X) and the localization matrix for DA

Parameters:

dist_vsf (float, list of float) – the vertical scaling factor of the distance

class cfr.v2026.enkf.solver.EnSRF(X=None, Y=None, y=None, R=None, L=None, Lobs=None)#

Ensemble Square Root Filter (EnSRF) with localization.

Implements the deterministic EnSRF update following Whitaker & Hamill (2002), with Gaspari-Cohn covariance localization.

Parameters:

  • X (ndarray (n, N)) – Ensemble of prior state vectors.

  • Y (ndarray (m, N)) – Ensemble of forward estimates, Y = H(X).

  • y (ndarray (m, 1)) – Observation vector.

  • R (ndarray (m, m)) – Observation error covariance matrix.

  • L (ndarray (n, m), optional) – Localization matrix for state-observation covariance.

  • Lobs (ndarray (m, m), optional) – Localization matrix for observation-observation covariance.

plot_T(cmap='viridis')#

Check the T matrix

update(debug=False)#

Perform an EnSRF update with localization.

class cfr.v2026.enkf.solver.EnSRF_DASH(X=None, Y=None, y=None, R=None, L=None, Lobs=None)#

EnSRF variant following the DASH formulation.

Uses an alternative square root update for ensemble perturbations based on matrix square root of the analysis covariance.

Parameters:

  • X (ndarray (n, N)) – Ensemble of prior state vectors.

  • Y (ndarray (m, N)) – Ensemble of forward estimates, Y = H(X).

  • y (ndarray (m, 1)) – Observation vector.

  • R (ndarray (m, m)) – Observation error covariance matrix.

  • L (ndarray (n, m), optional) – Localization matrix for state-observation covariance.

  • Lobs (ndarray (m, m), optional) – Localization matrix for observation-observation covariance.

update(debug=False)#

Perform an EnSRF update with localization.

class cfr.v2026.enkf.solver.EnOI(X_target=None, X=None, Y=None, y=None, R=None, L=None)#

Ensemble Optimal Interpolation (EnOI).

Updates a target state using a static ensemble for covariance estimation, rather than updating the ensemble itself.

Parameters:

  • X_target (ndarray (n, 1)) – Target state vector to be updated (e.g., monthly prior).

  • X (ndarray (n, N)) – Static ensemble of prior state vectors for covariance estimation.

  • Y (ndarray (m, N)) – Ensemble of forward estimates, Y = H(X).

  • y (ndarray (m, 1)) – Observation vector.

  • R (ndarray (m, m)) – Observation error covariance matrix.

  • L (ndarray (n, m), optional) – Localization matrix.

update(debug=False)#

Perform an EnOI update with localization.

Contents