CalibrationTools

This module contains utilities to help with setting up calibration experiments of the coupled model. These utilities are meant to be broadly useful and are not specific to one particular calibration experiment.

Other helpful resources

For calibration, other resources that you may find helpful are the documentation for EnsembleKalmanProcesses, ClimaCalibrate, ClimaAnalysis, and the ClimaCoupler calibration experiments.

Data loading

OutputVar

This section assumes you are familiar with ClimaAnalysis.OutputVar.

CalibrationTools provides a variety of data loaders from different artifacts in ClimaArtifacts for calibration. For example, the ERA5DataLoader is a data loader loading preprocessed ERA5 data. This data loader automatically applies preprocessing to make it convenient to use for calibration. See the documentation for ERA5DataLoader for details on the preprocessing steps applied.

You can retrieve a variable with get and get a set of all available preprocessed variables with available_vars.

julia> import ClimaCoupler: CalibrationTools
julia> data_loader = CalibrationTools.ERA5DataLoader()ERA5DataLoader: hfls, hfss, rlus, rsus
julia> CalibrationTools.available_vars(data_loader)Set{String} with 4 elements:
  "hfls"
  "rlus"
  "hfss"
  "rsus"
julia> var = get(data_loader, "rsus");

In the example, we retrieve a OutputVar with the short name rsus which represents the mean surface upward short-wave radiation flux.

Other data loaders

If you want a data loader for other data sources, then please open an issue for it!

I want to add a new variable to an existing data loader

To add a new variable, you must

Define a mapping between the ERA5 name and CliMA name,
Define a preprocess function for this variable.

To determine which variables are already available, refer to the artifact's documentation. For ERA5DataLoader we can load the variable representing mean evaporation rate or mer from the data source. We also want to give it the name er. For step 1, we add "mer" => "er" as a mapping for the data loader to recognize.

import ClimaCoupler: CalibrationTools
data_loader = CalibrationTools.ERA5DataLoader()
# ERA5_TO_CLIMA_NAMES define the existing pairings for the data loader
era5_to_clima_names = [CalibrationTools.ERA5_TO_CLIMA_NAMES..., "mer" => "er"]
data_loader = CalibrationTools.ERA5DataLoader(; era5_to_clima_names)

ERA5DataLoader: er, hfls, hfss, rlus, rsus

For the second step, we define a preprocessing function specific to the variable.

Preprocessing functions

See ClimaAnalysis documentation for available transformations on OutputVars.

In our example, no preprocessing is applied.

CalibrationTools.preprocess(::CalibrationTools.ERA5DataLoader, var, ::Val{:er}) = var

Now, you can use get to retrieve the OutputVar with the short name "mer"`.

data_loader = CalibrationTools.ERA5DataLoader(; era5_to_clima_names)
get(data_loader, "er")

CalibrationTools API

ClimaCoupler.CalibrationTools.CalibrateConfig — Type

struct CalibrateConfig{SPINUP <: Dates.Period, EXTEND <: Dates.Period}

A configuration struct for keeping track of multiple fields that are of interest to a user running calibration, or that are needed in multiple places (e.g., for ensemble members and generating observations).