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.
resample_skill_exclude_resample_dim_from_dim(...)
resample_skill_loop(self, iterations, ...)
resample_skill_resample_before(self, ...)
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.

Utils

convert_init_lead_to_valid_time_lead(skill)	Convert data(init,lead) to data(valid_time,lead) visualizing predict barrier.
convert_valid_time_lead_to_init_lead(skill)	Convert data(valid_time,lead) to data(init,lead).

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.