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 append their initialized ensemble to these classes, as well as an arbitrary number of verification products (assimilations, reconstructions, observations), control runs, and uninitialized ensembles.


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

HindcastEnsemble(xobj) An object for climate prediction ensembles initialized by a data-like product.

Add and Retrieve Datasets

HindcastEnsemble.__init__(xobj) Create a HindcastEnsemble object by inputting output from a prediction ensemble in xarray format.
HindcastEnsemble.add_observations(xobj, name) Add a verification data with which to verify the initialized ensemble.
HindcastEnsemble.add_uninitialized(xobj) Add a companion uninitialized ensemble for comparison to verification data.
HindcastEnsemble.get_initialized() Returns the xarray dataset for the initialized ensemble.
HindcastEnsemble.get_observations([name]) Returns xarray Datasets of the observations/verification data.
HindcastEnsemble.get_uninitialized() Returns the xarray dataset for the uninitialized ensemble.

Analysis Functions

HindcastEnsemble.verify([name, reference, …]) Verifies the initialized ensemble against observations/verification data.


HindcastEnsemble.smooth([smooth_kws]) Smooth all entries of PredictionEnsemble in the same manner to be able to still calculate prediction skill afterwards.


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(xobj) An object for “perfect model” climate prediction ensembles.

Add and Retrieve Datasets

PerfectModelEnsemble.__init__(xobj) Create a PerfectModelEnsemble object by inputting output from the control run in xarray format.
PerfectModelEnsemble.add_control(xobj) Add the control run that initialized the climate prediction ensemble.
PerfectModelEnsemble.get_initialized() Returns the xarray dataset for the initialized ensemble.
PerfectModelEnsemble.get_control() Returns the control as an xarray dataset.
PerfectModelEnsemble.get_uninitialized() Returns the xarray dataset for the uninitialized ensemble.

Analysis Functions

PerfectModelEnsemble.bootstrap([metric, …]) Bootstrap ensemble simulations with replacement.
PerfectModelEnsemble.compute_metric([…]) Compares the initialized ensemble to the control run.
PerfectModelEnsemble.compute_persistence([…]) Compute a simple persistence forecast for the control run.
PerfectModelEnsemble.compute_uninitialized([…]) Compares the bootstrapped uninitialized run to the control run.

Generate Data

PerfectModelEnsemble.generate_uninitialized() Generate an uninitialized ensemble by bootstrapping the initialized prediction ensemble.

Direct Function Calls

A user can directly call functions in climpred. This requires entering more arguments, e.g. the initialized ensemble Dataset/xarray.core.dataarray.DataArray directly as well as a verification product. Our object HindcastEnsemble and PerfectModelEnsemble wrap most of these functions, making the analysis process much simpler. Once we have wrapped all of the functions in their entirety, we will likely depricate the ability to call them directly.


bootstrap_compute(hind, verif[, hist, …]) Bootstrap compute with replacement.
bootstrap_hindcast(hind, hist, verif[, …]) Bootstrap compute with replacement. Wrapper of
bootstrap_perfect_model(init_pm, control[, …]) Bootstrap compute with replacement. Wrapper of
bootstrap_uninit_pm_ensemble_from_control_cftime(…) Create a pseudo-ensemble from control run.
bootstrap_uninitialized_ensemble(hind, hist) 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 the variance-weighted mean period significance levels from re-sampled dataset.


compute_hindcast(hind, verif[, metric, …]) Verify hindcast predictions against verification data.
compute_perfect_model(init_pm, control[, …]) Compute a predictability skill score for a perfect-model framework simulation dataset.


compute_persistence(hind, verif[, metric, …]) Computes the skill of a persistence forecast from a simulation.
compute_uninitialized(hind, uninit, verif[, …]) Verify an uninitialized ensemble against verification data.


Metric(name, function, positive, …[, …]) Master class for all metrics.
_get_norm_factor(comparison) Get normalization factor for normalizing distance metrics.


Comparison(name, function, hindcast, …[, …]) Master class for all comparisons.


autocorr(ds[, lag, dim, return_p]) Calculate the lagged correlation of time series.
corr(x, y[, dim, lag, return_p]) Computes the Pearson product-moment coefficient of linear correlation.
decorrelation_time(da[, r, dim]) Calculate the decorrelaton time of a time series.
dpp(ds[, dim, m, chunk]) Calculates the Diagnostic Potential Predictability (dpp)
rm_poly(ds, order[, dim]) Returns xarray object with nth-order fit removed.
rm_trend(da[, dim]) Remove linear trend from time series.
varweighted_mean_period(da[, dim]) Calculate the variance weighted mean period of time series based on xrft.power_spectrum.


load_dataset([name, cache, cache_dir, …]) Load example data or a mask from an online repository.


load_hindcast([inits, members, preprocess, …]) Load multi-member, multi-initialization hindcast experiment into one xr.Dataset compatible with climpred.
rename_to_climpred_dims(xro) Rename existing dimension in xr.object xro to CLIMPRED_ENSEMBLE_DIMS from existing dimension names.
rename_SLM_to_climpred_dims(xro) Rename ensemble dimensions common to SubX or CESM output:
get_path([dir_base_experiment, member, …]) Get the path of a file for MPI-ESM standard output file names and directory.