Getting started¶
Install¶
pip install climval # NumPy, SciPy, pandas, xarray, dask, flox, cftime, PyYAML
pip install "climval[cloud]" # Zarr, fsspec, gcsfs, s3fs
pip install "climval[cloud,catalog]" # plus intake-esm catalogues
Other extras: netcdf (netCDF4, h5netcdf), units (pint, cf_xarray),
regions (regionmask), all. Conservative
regridding needs xESMF, which depends on the ESMF library and is best
installed with conda: conda install -c conda-forge xesmf.
climval needs Python 3.10 or newer.
A first comparison without data¶
climval.demo() compares two small synthetic fields that differ in every way
alignment has to handle: grid spacing, longitude convention, latitude order,
calendar and units. Its results are flagged as synthetic in every output.
A comparison of your own data¶
import climval
import xarray as xr
reference = xr.open_dataset("era5_t2m_monthly.nc", chunks={})
candidate = xr.open_dataset("tas_Amon_MPI-ESM1-2-LR_historical_r1i1p1f1_gn_185001-201412.nc", chunks={})
result = climval.compare(
reference,
candidate,
variable=("t2m", "tas"), # (reference name, candidate name)
region=climval.Box(lat=(35, 72), lon=(-10, 40)),
period=("1995", "2014"),
by="season",
)
compare puts both inputs on one grid (by default the one with the larger cells),
on common months and in the reference's units (see
Alignment), computes every metric in one dask pass
and returns a Comparison. Spatial means are
weighted by cell area and monthly steps by their length in days; with
by="season" a December counts in the following winter's DJF.
The result¶
result.summary() # printed table and the alignment steps
result.to_dataframe() # long table: sample, group, metric, value, units
result["rmse"] # one value: space_time sample, group "all"
result.value("pearson_r", sample="climatology", group="JJA")
result.field("time") # per-grid-point maps, one per group
result.reference # the aligned reference field
result.candidate # the aligned candidate field
result.provenance # inputs, steps, versions, as a dict
result.export("report.html") # or .json, .md
In Jupyter the result displays as a table.
Pass or fail¶
verdict = result.check({
"rmse": {"max": 2.0},
"mean_bias": {"abs_max": 1.0, "group": "*"},
"pearson_r": {"min": 0.95, "sample": "climatology"},
})
verdict.passed
print(verdict.summary())
The same limits, written in a configuration file, run from the command line
with climval check and from GitHub Actions; see
Thresholds and the CI gate.