API Reference#

This page provides an auto-generated summary of climpred’s API. For more details and examples, refer to the relevant chapters in the main part of the documentation.

High-Level Classes#

A primary feature of climpred is our prediction ensemble objects, HindcastEnsemble and PerfectModelEnsemble. Users can add their initialized ensemble to these classes, as well as verification products (assimilations, reconstructions, observations), control runs, and uninitialized ensembles.

PredictionEnsemble#

PredictionEnsemble is the base class for HindcastEnsemble and PerfectModelEnsemble. PredictionEnsemble cannot be called directly, but HindcastEnsemble and PerfectModelEnsemble inherit the common base functionality.

PredictionEnsemble(initialized)

The main object PredictionEnsemble.

PredictionEnsemble.__init__(initialized)

Create a PredictionEnsemble object.

Builtin#

PredictionEnsemble.__len__()

Return number of all variables PredictionEnsemble.

PredictionEnsemble.__iter__()

Iterate over underlying xarray.Dataset.

PredictionEnsemble.__delitem__(key)

Remove a variable from PredictionEnsemble.

PredictionEnsemble.__contains__(key)

Check variable in PredictionEnsemble.

PredictionEnsemble.__add__(other)

Add.

PredictionEnsemble.__sub__(other)

Sub.

PredictionEnsemble.__mul__(other)

Mul.

PredictionEnsemble.__truediv__(other)

Div.

PredictionEnsemble.__getitem__(varlist)

Allow subsetting variable(s) from

PredictionEnsemble.__getattr__(name)

Allow for xarray methods to be applied to our prediction objects.

Properties#

PredictionEnsemble.coords

Return coordinates of PredictionEnsemble.

PredictionEnsemble.nbytes

Bytes sizes of all PredictionEnsemble._datasets.

PredictionEnsemble.sizes

Return sizes of PredictionEnsemble.

PredictionEnsemble.dims

Return dimension of PredictionEnsemble.

PredictionEnsemble.chunks

Return chunks of PredictionEnsemble.

PredictionEnsemble.chunksizes

Return chunksizes of PredictionEnsemble.

PredictionEnsemble.data_vars

Return data variables of PredictionEnsemble.

PredictionEnsemble.equals(other)

Check if PredictionEnsemble is equal to other.

PredictionEnsemble.identical(other)

Check if PredictionEnsemble is identical to other.

HindcastEnsemble#

A HindcastEnsemble is a prediction ensemble that is initialized off of some form of observations (an assimilation, reanalysis, etc.). Thus, it is anticipated that forecasts are verified against observation-like products. Read more about the terminology here.

HindcastEnsemble(initialized)

An object for initialized prediction ensembles.

HindcastEnsemble.__init__(initialized)

Create HindcastEnsemble from initialized prediction ensemble output.

Add and Retrieve Datasets#

HindcastEnsemble.add_observations(obs)

Add verification data against which to verify the initialized ensemble.

HindcastEnsemble.add_uninitialized(uninit)

Add a companion uninitialized ensemble for comparison to verification data.

HindcastEnsemble.get_initialized()

Return the xarray.Dataset for the initialized ensemble.

HindcastEnsemble.get_observations()

Return the xarray.Dataset of the observations/verification data.

HindcastEnsemble.get_uninitialized()

Return the xarray.Dataset for the uninitialized ensemble.

Analysis Functions#

HindcastEnsemble.verify([metric, ...])

Verify the initialized ensemble against observations.

HindcastEnsemble.bootstrap([metric, ...])

Bootstrap with replacement according to Goddard et al. [2013].

Generate Data#

HindcastEnsemble.generate_uninitialized([...])

Generate uninitialized by resampling from initialized.

Pre-Processing#

HindcastEnsemble.smooth([smooth_kws, how])

Smooth in space and/or aggregate in time in PredictionEnsemble.

HindcastEnsemble.remove_bias([alignment, ...])

Remove bias from HindcastEnsemble.

HindcastEnsemble.remove_seasonality([...])

Remove seasonal cycle from PredictionEnsemble.

Visualization#

HindcastEnsemble.plot([variable, ax, ...])

Plot datasets from PredictionEnsemble.

HindcastEnsemble.plot_alignment([alignment, ...])

Plot initialized valid_time where matching verification time.

PerfectModelEnsemble#

A PerfectModelEnsemble is a prediction ensemble that is initialized off of a control simulation for a number of randomly chosen initialization dates. Thus, forecasts cannot be verified against real-world observations. Instead, they are compared to one another and to the original control run. Read more about the terminology here.

PerfectModelEnsemble(initialized)

An object for "perfect model" prediction ensembles.

PerfectModelEnsemble.__init__(initialized)

Create a PerfectModelEnsemble object.

Add and Retrieve Datasets#

PerfectModelEnsemble.add_control(control)

Add the control run that initialized the prediction ensemble.

PerfectModelEnsemble.get_initialized()

Return the xarray.Dataset for the initialized ensemble.

PerfectModelEnsemble.get_control()

Return the control as an xarray.Dataset.

PerfectModelEnsemble.get_uninitialized()

Return the xarray.Dataset for the uninitialized ensemble.

Analysis Functions#

PerfectModelEnsemble.verify([metric, ...])

Verify initialized predictions against a configuration of its members.

PerfectModelEnsemble.bootstrap([metric, ...])

Bootstrap with replacement according to Goddard et al. [2013].

Generate Data#

PerfectModelEnsemble.generate_uninitialized()

Generate an uninitialized ensemble by resampling from the control simulation.

Pre-Processing#

PerfectModelEnsemble.smooth([smooth_kws, how])

Smooth in space and/or aggregate in time in PredictionEnsemble.

PerfectModelEnsemble.remove_seasonality([...])

Remove seasonal cycle from PredictionEnsemble.

Visualization#

PerfectModelEnsemble.plot([variable, ax, ...])

Plot datasets from PredictionEnsemble.

Direct Function Calls#

While not encouraged anymore, a user can directly call functions in climpred. This requires entering more arguments, e.g. the initialized ensemble directly as well as a verification product. Our object HindcastEnsemble and PerfectModelEnsemble wrap most of these functions, making the analysis process much simpler.

Bootstrap#

bootstrap_uninit_pm_ensemble_from_control_cftime(...)

Create a pseudo-ensemble from control run.

bootstrap_uninitialized_ensemble(...)

Resample uninitialized hindcast from historical members.

dpp_threshold(control[, sig, iterations, dim])

Calc DPP significance levels from re-sampled dataset.

varweighted_mean_period_threshold(control[, ...])

Calc variance-weighted mean period significance levels from resampled dataset.

Prediction#

compute_perfect_model(initialized[, ...])

Compute a predictability skill score in a perfect-model framework.

Reference#

compute_persistence(initialized, verif[, ...])

Compute the skill of a persistence forecast from a simulation.

compute_persistence_from_first_lead(initialized)

Compute persistence skill based on first lead in initialized.

compute_uninitialized(initialized, uninit, verif)

Verify an uninitialized ensemble against verification data.

compute_climatology(initialized[, verif, ...])

Compute the skill of a climatology forecast.

Horizon#

horizon(cond)

Calculate the predictability horizon based on a condition `cond.

Statistics#

decorrelation_time(da[, iterations, dim])

Calculate the decorrelaton time of a time series.

dpp(ds[, dim, m, chunk])

Calculate the Diagnostic Potential Predictability (DPP).

varweighted_mean_period(da[, dim])

Calculate the variance weighted mean period of time series.

rm_poly(ds[, dim, deg])

Remove degree polynomial of degree deg along dimension dim.

rm_trend(ds[, dim])

Remove degree polynomial along dimension dim

Tutorial#

load_dataset([name, cache, cache_dir, ...])

Load example data or a mask from an online repository.

Preprocessing#

load_hindcast([inits, members, preprocess, ...])

Concat multi-member, multi-initialization hindcast experiment.

rename_to_climpred_dims(xro)

Rename existing dimension to CLIMPRED_ENSEMBLE_DIMS.

rename_SLM_to_climpred_dims(xro)

Rename ensemble dimensions common to SubX or CESM output.

set_integer_time_axis(xro[, offset, time_dim])

Set time axis to integers starting from offset.

get_path([dir_base_experiment, member, ...])

Get the path of a file for MPI-ESM standard output file names and directory.

Smoothing#

temporal_smoothing(ds[, tsmooth_kws, how, ...])

Apply temporal smoothing by creating rolling smooth-timestep means.

spatial_smoothing_xesmf(ds[, d_lon_lat_kws, ...])

Quick regridding function.

Visualization#

plot_bootstrapped_skill_over_leadyear(...[, ...])

Plot Ensemble Prediction skill as in Li et al. 2016 Fig.3a-c.

plot_ensemble_perfect_model(pm[, variable, ...])

Plot datasets from PerfectModelEnsemble.

plot_lead_timeseries_hindcast(he[, ...])

Plot datasets from HindcastEnsemble.

Metrics#

For a thorough look at our metrics library, please see the metrics page.

Metric(name, function, positive, ...[, ...])

Master class for all metrics.

Metric.__init__(name, function, positive, ...)

Metric initialization.

Metric.__repr__()

Show metadata of metric class.

_get_norm_factor(comparison)

Get normalization factor for normalizing distance metrics.

_pearson_r(forecast, verif[, dim])

Pearson product-moment correlation coefficient.

_pearson_r_p_value(forecast, verif[, dim])

Probability that forecast and verification data are linearly uncorrelated.

_effective_sample_size(forecast, verif[, dim])

Effective sample size for temporally correlated data.

_pearson_r_eff_p_value(forecast, verif[, dim])

pearson_r_p_value accounting for autocorrelation.

_spearman_r(forecast, verif[, dim])

Spearman's rank correlation coefficient.

_spearman_r_p_value(forecast, verif[, dim])

Probability that forecast and verification data are monotonically uncorrelated.

_spearman_r_eff_p_value(forecast, verif[, dim])

_spearman_r_p_value accounting for autocorrelation.

_mse(forecast, verif[, dim])

Mean Sqaure Error (MSE).

_rmse(forecast, verif[, dim])

Root Mean Sqaure Error (RMSE).

_mae(forecast, verif[, dim])

Mean Absolute Error (MAE).

_median_absolute_error(forecast, verif[, dim])

Median Absolute Error.

_nmse(forecast, verif[, dim])

Compte Normalized MSE (NMSE), also known as Normalized Ensemble Variance (NEV).

_nmae(forecast, verif[, dim])

Compute Normalized Mean Absolute Error (NMAE).

_nrmse(forecast, verif[, dim])

Compute Normalized Root Mean Square Error (NRMSE).

_msess(forecast, verif[, dim])

Mean Squared Error Skill Score (MSESS).

_mape(forecast, verif[, dim])

Mean Absolute Percentage Error (MAPE).

_smape(forecast, verif[, dim])

Symmetric Mean Absolute Percentage Error (sMAPE).

_uacc(forecast, verif[, dim])

Bushuk's unbiased Anomaly Correlation Coefficient (uACC).

_std_ratio(forecast, verif[, dim])

Ratio of standard deviations of the forecast over the verification data.

_conditional_bias(forecast, verif[, dim])

Conditional bias between forecast and verification data.

_unconditional_bias(forecast, verif[, dim])

Unconditional additive bias.

_bias_slope(forecast, verif[, dim])

Bias slope between verification data and forecast standard deviations.

_msess_murphy(forecast, verif[, dim])

Murphy's Mean Square Error Skill Score (MSESS).

_crps(forecast, verif[, dim])

Continuous Ranked Probability Score (CRPS).

_crpss(forecast, verif[, dim])

Continuous Ranked Probability Skill Score.

_crpss_es(forecast, verif[, dim])

Continuous Ranked Probability Skill Score Ensemble Spread.

_brier_score(forecast, verif[, dim])

Brier Score for binary events.

_threshold_brier_score(forecast, verif[, dim])

Brier score of an ensemble for exceeding given thresholds.

_rps(forecast, verif[, dim])

Ranked Probability Score.

_discrimination(forecast, verif[, dim])

Discrimination.

_reliability(forecast, verif[, dim])

Reliability.

_rank_histogram(forecast, verif[, dim])

Rank histogram or Talagrand diagram.

_contingency(forecast, verif[, score, dim])

Contingency table.

_roc(forecast, verif[, dim])

Receiver Operating Characteristic.

_spread(forecast, verif[, dim])

Ensemble spread taking the standard deviation over the member dimension.

_mul_bias(forecast, verif[, dim])

Multiplicative bias.

_less(forecast, verif[, dim])

Logarithmic Ensemble Spread Score.

Comparisons#

For a thorough look at our metrics library, please see the comparisons page.

Comparison(name, function, hindcast, ...[, ...])

Master class for all comparisons.

Comparison.__init__(name, function, ...[, ...])

Comparison initialization See Comparisons.

Comparison.__repr__()

Show metadata of comparison class.

_e2o(initialized, verif, metric)

Compare the ensemble mean forecast to the verification data.

_m2o(initialized, verif, metric)

Compare each ensemble member individually to the verification data.

_m2m(initialized, metric[, verif])

Compare all members to all others in turn while leaving out verification member.

_m2e(initialized[, metric, verif])

Compare all members to ensemble mean while leaving out the verif in ensemble mean.

_m2c(initialized, metric[, verif])

Compare all other member forecasts to a single member verification.

_e2c(initialized[, metric, verif])

Compare ensemble mean forecast to single member verification.

Config#

Set options analogous to xarray.

set_options(**kwargs)

Set options for climpred in a controlled context.