PredictionEnsemble Objects¶

One of the major features of climpred is our objects that are based upon the PredictionEnsemble class. We supply users with a HindcastEnsemble or PerfectModelEnsemble object. We encourage users to take advantage of these high-level objects, which wrap all of our core functions.

Briefly, we consider a HindcastEnsemble to be one that is initialized from some observational-like product (e.g., assimilated data, reanalysis products, or a model reconstruction). Thus, this object is built around comparing the initialized ensemble to various observational products. In contrast, a PerfectModelEnsemble is one that is initialized off of a model control simulation. These forecasting systems are not meant to be compared directly to real-world observations. Instead, they provide a contained model environment with which to theoretically study the limits of predictability. You can read more about the terminology used in climpred here.

Let’s create a demo object to explore some of the functionality and why they are much smoother to use than direct function calls.

# linting
%load_ext nb_black
%load_ext lab_black

%matplotlib inline
import matplotlib.pyplot as plt
import xarray as xr
import numpy as np

from climpred import HindcastEnsemble, PerfectModelEnsemble
from climpred.tutorial import load_dataset
import climpred

We can now pull in some sample data that is packaged with climpred. We’ll start out with a HindcastEnsemble demo, followed by a PerfectModelEnsemble case.

HindcastEnsemble¶

initialized = climpred.tutorial.load_dataset(
    "CESM-DP-SST"
)  # CESM-DPLE hindcast ensemble output.
obs = climpred.tutorial.load_dataset("ERSST")  # ERSST observations.

We need to add a units attribute to the hindcast ensemble so that climpred knows how to interpret the lead units.

initialized["lead"].attrs["units"] = "years"

Now we instantiate the HindcastEnsemble object and append all of our products to it.

Now we just use HindcastEnsemble.add_observations() to attach other objects. See the API here. Note that we strive to make our conventions follow those of xarray. For example, we don’t allow inplace operations. One has to run hindcast = hindcast.add_observations(...) to modify the object upon later calls rather than just hindcast.add_observations(...).

You can apply most standard xarray functions directly to our objects! climpred will loop through the objects and apply the function to all applicable xarray.Dataset within the object. If you reference a dimension that doesn’t exist for the given xarray.Dataset, it will ignore it. This is useful, since the initialized ensemble is expected to have dimension init, while other products have dimension time (see more here).

Let’s start by taking the ensemble mean of the initialized ensemble. Just using deterministic metrics here, so we don’t need the individual ensemble members. Note that above our initialized ensemble had a member dimension, and now it is reduced. Those xarray functions do not raise errors such as ValueError, KeyError, DimensionError, but show respective warnings, which can be filtered away with warnings.filterwarnings("ignore").

Visualizing PredictionEnsemble¶

PredictionEnsemble.plot() showings all datasets associated if only member, init and lead dimensions are present.

hindcast.plot()

<AxesSubplot:xlabel='validity time', ylabel='SST'>

_images/prediction-ensemble-object_28_1.png

We have a huge bias because the initialized data is already converted to an anomaly, but uninitialized and observations is not. We also have a trend in all of our products, so we could also detrend them as well.

Detrend¶

We can leverage xarray’s .map() function to apply/map a function to all variables in our datasets. We use climpred.stats.rm_poly() to remove the trend.

from climpred.stats import rm_poly

hindcast_detrended = hindcast.map(rm_poly, deg=2, dim="init_or_time")
hindcast_detrended.plot()

<AxesSubplot:xlabel='validity time', ylabel='SST'>

_images/prediction-ensemble-object_31_1.png

And it looks like everything got detrended by a quadratic fit! That wasn’t too hard.

climpred documentation

PredictionEnsemble Objects¶

HindcastEnsemble¶

climpred.HindcastEnsemble

climpred.HindcastEnsemble

climpred.HindcastEnsemble

Arithmetic Operations with PredictionEnsemble Objects¶

climpred.HindcastEnsemble

climpred.HindcastEnsemble

climpred.HindcastEnsemble

climpred.HindcastEnsemble

Visualizing PredictionEnsemble¶

Detrend¶

Verify¶

PerfectModelEnsemble¶

climpred.PerfectModelEnsemble

climpred.PerfectModelEnsemble