Download this notebook from github.
Command line interface
xclim provides the xclim command line executable to perform basic indicator computation easily without having to start up a full python environment. However, not all indicators listed in Climate Indicators are available through this tool.
Its use is simple. Type the following to see the usage message:
[1]:
!xclim --help
Usage: xclim [OPTIONS] INDICATOR1 [OPTIONS] ... [INDICATOR2 [OPTIONS] ... ]
...
Command line tool to compute indices on netCDF datasets. Indicators are
referred to by their (case-insensitive) identifier, as in
xclim.core.indicator.registry.
Options:
-i, --input TEXT Input files. Can be a netCDF path or a glob
pattern.
-o, --output TEXT Output filepath. A new file will be created
-v, --verbose Print details about context and progress.
-V, --version Prints xclim's version number and exits
--dask-nthreads INTEGER Start a dask.distributed Client with this many
threads and 1 worker. If not specified, the local
scheduler is used. If specified, '--dask-maxmem'
must also be given
--dask-maxmem TEXT Memory limit for the dask.distributed Client as a
human readable string (ex: 4GB). If specified, '--
dask-nthreads' must also be specified.
--chunks TEXT Chunks to use when opening the input dataset(s).
Given as <dim1>:num,<dim2:num>. Ex:
time:365,lat:168,lon:150.
--help Show this message and exit.
Commands:
indices List indicators.
info Give information about INDICATOR.
dataflags Run data flag checks for input variables.
release_notes Print history for publishing purposes.
To list all available indicators, use the “indices” subcommand:
[2]:
!xclim indices
Listing all available indicators for computation.:
anuclim.p10_meantempwarmestquarter
P10_MeanTempWarmestQuarter
(P10_MeanTempWarmestQuarter)
anuclim.p11_meantempcoldestquarter
P11_MeanTempColdestQuarter
(P11_MeanTempColdestQuarter)
anuclim.p12_annualprecip Annual Precipitation (P12_AnnualPrecip)
anuclim.p13_precipwettestperiod
P13_PrecipWettestPeriod
(P13_PrecipWettestPeriod)
anuclim.p14_precipdriestperiod P14_PrecipDriestPeriod
(P14_PrecipDriestPeriod)
anuclim.p15_precipseasonality P15_PrecipSeasonality
(P15_PrecipSeasonality)
anuclim.p16_precipwettestquarter
P16_PrecipWettestQuarter
(P16_PrecipWettestQuarter)
anuclim.p17_precipdriestquarter
P17_PrecipDriestQuarter
(P17_PrecipDriestQuarter)
anuclim.p18_precipwarmestquarter
P18_PrecipWarmestQuarter
(P18_PrecipWarmestQuarter)
anuclim.p19_precipcoldestquarter
P19_PrecipColdestQuarter
(P19_PrecipColdestQuarter)
anuclim.p1_annmeantemp Annual Mean Temperature (P1_AnnMeanTemp)
anuclim.p2_meandiurnalrange Mean Diurnal Range (P2_MeanDiurnalRange)
anuclim.p3_isothermality P3_Isothermality (P3_Isothermality)
anuclim.p4_tempseasonality P4_TempSeasonality (P4_TempSeasonality)
anuclim.p5_maxtempwarmestperiod
Max Temperature of Warmest Period
(P5_MaxTempWarmestPeriod)
anuclim.p6_mintempcoldestperiod
Min Temperature of Coldest Period
(P6_MinTempColdestPeriod)
anuclim.p7_tempannualrange Temperature Annual Range
(P7_TempAnnualRange)
anuclim.p8_meantempwettestquarter
P8_MeanTempWettestQuarter
(P8_MeanTempWettestQuarter)
anuclim.p9_meantempdriestquarter
P9_MeanTempDriestQuarter
(P9_MeanTempDriestQuarter)
base_flow_index Base flow index
biologically_effective_degree_days
Biologically effective degree days computed
with {method} formula (Summation of
min((max((Tmin + Tmax)/2 - {thresh_tasmin},
0) * k) + TR_adg, 9°C), for days between
{start_date} and {end_date}). (bedd)
blowing_snow Number of days where snowfall and wind
speeds are above respective thresholds.
({freq}_blowing_snow)
calm_days Number of days with surface wind speed below
threshold
cdd Maximum consecutive dry days (Precip <
{thresh})
cf.cdd Maximum consecutive dry days (Precip < 1mm)
(cdd)
cf.cddcoldtt Cooling Degree Days (Tmean > {threshold}C)
(cddcold{threshold})
cf.cfd Maximum number of consecutive frost days
(Tmin < 0 C) (cfd)
cf.csu Maximum number of consecutive summer days
(Tmax >25 C) (csu)
cf.ctmgett Maximum number of consequtive days with
Tmean >= {threshold}C (ctmge{threshold})
cf.ctmgttt Maximum number of consequtive days with
Tmean > {threshold}C (ctmgt{threshold})
cf.ctmlett Maximum number of consequtive days with
Tmean <= {threshold}C (ctmle{threshold})
cf.ctmlttt Maximum number of consequtive days with
Tmean < {threshold}C (ctmlt{threshold})
cf.ctngett Maximum number of consequtive days with Tmin
>= {threshold}C (ctnge{threshold})
cf.ctngttt Maximum number of consequtive days with Tmin
> {threshold}C (ctngt{threshold})
cf.ctnlett Maximum number of consequtive days with Tmin
<= {threshold}C (ctnle{threshold})
cf.ctnlttt Maximum number of consequtive days with Tmin
< {threshold}C (ctnlt{threshold})
cf.ctxgett Maximum number of consequtive days with Tmax
>= {threshold}C (ctxge{threshold})
cf.ctxgttt Maximum number of consequtive days with Tmax
> {threshold}C (ctxgt{threshold})
cf.ctxlett Maximum number of consequtive days with Tmax
<= {threshold}C (ctxle{threshold})
cf.ctxlttt Maximum number of consequtive days with Tmax
< {threshold}C (ctxlt{threshold})
cf.cwd Maximum consecutive wet days (Precip >= 1mm)
(cwd)
cf.ddgttt Degree Days (Tmean > {threshold}C)
(ddgt{threshold})
cf.ddlttt Degree Days (Tmean < {threshold}C)
(ddlt{threshold})
cf.dtr Mean Diurnal Temperature Range (dtr)
cf.etr Intra-period extreme temperature range (etr)
cf.fg Mean of daily mean wind strength (fg)
cf.fxx Maximum value of daily maximum wind gust
strength (fxx)
cf.gd4 Growing degree days (sum of Tmean > 4 C)
(gd4)
cf.gddgrowtt Annual Growing Degree Days (Tmean >
{threshold}C) (gddgrow{threshold})
cf.hd17 Heating degree days (sum of Tmean < 17 C)
(hd17)
cf.hddheattt Heating Degree Days (Tmean < {threshold}C)
(hddheat{threshold})
cf.maxdtr Maximum Diurnal Temperature Range (maxdtr)
cf.pp Mean of daily sea level pressure (pp)
cf.rh Mean of daily relative humidity (rh)
cf.sd Mean of daily snow depth (sd)
cf.sdii Average precipitation during Wet Days (SDII)
(sdii)
cf.ss Sunshine duration, sum (ss)
cf.tg Mean of daily mean temperature (tg)
cf.tmm Mean daily mean temperature (tmm)
cf.tmmax Maximum daily mean temperature (tmmax)
cf.tmmean Mean daily mean temperature (tmmean)
cf.tmmin Minimum daily mean temperature (tmmin)
cf.tmn Minimum daily mean temperature (tmn)
cf.tmx Maximum daily mean temperature (tmx)
cf.tn Mean of daily minimum temperature (tn)
cf.tnm Mean daily minimum temperature (tnm)
cf.tnmax Maximum daily minimum temperature (tnmax)
cf.tnmean Mean daily minimum temperature (tnmean)
cf.tnmin Minimum daily minimum temperature (tnmin)
cf.tnn Minimum daily minimum temperature (tnn)
cf.tnx Maximum daily minimum temperature (tnx)
cf.tx Mean of daily maximum temperature (tx)
cf.txm Mean daily maximum temperature (txm)
cf.txmax Maximum daily maximum temperature (txmax)
cf.txmean Mean daily maximum temperature (txmean)
cf.txmin Minimum daily maximum temperature (txmin)
cf.txn Minimum daily maximum temperature (txn)
cf.txx Maximum daily maximum temperature (txx)
cf.vdtr Mean day-to-day variation in Diurnal
Temperature Range (vdtr)
cold_and_dry_days Cold and dry days
cold_and_wet_days cold and wet days
cold_spell_days Number of days part of a cold spell
cold_spell_duration_index Number of days part of a percentile-defined
cold spell (csdi_{window})
cold_spell_frequency Number of cold spell events
consecutive_frost_days Maximum number of consecutive days with Tmin
< {thresh}
consecutive_frost_free_days Maximum number of consecutive days with Tmin
>= {thresh}
continuous_snow_cover_end End date of continuous snow cover
continuous_snow_cover_start Start date of continuous snow cover
cool_night_index cool night index
cooling_degree_days Cooling degree days (Tmean > {thresh})
corn_heat_units Corn heat units (Tmin > {thresh_tasmin} and
Tmax > {thresh_tasmax}). (chu)
cwd Maximum consecutive wet days (Precip >=
{thresh})
days_over_precip_doy_thresh Count of days with daily precipitation above
the given percentile [days].
days_over_precip_thresh Count of days with daily precipitation above
the given percentile [days].
days_with_snow Number of days with solid precipitation flux
between low and high thresholds.
dc Drought Code
degree_days_exceedance_date Day of year when cumulative degree days
exceed {sum_thresh}.
dlyfrzthw daily freezethaw cycles
doy_qmax Day of the year of the maximum over
{indexer} (q{indexer}_doy_qmax)
doy_qmin Day of the year of the minimum over
{indexer} (q{indexer}_doy_qmin)
dry_days Number of dry days (precip < {thresh})
dry_spell_frequency The {freq} number of dry periods of minimum
{window} days.
dry_spell_total_length The {freq} total number of days in dry
periods of minimum {window} days.
dtr Mean Diurnal Temperature Range
dtrmax Maximum Diurnal Temperature Range
dtrvar Mean Diurnal Temperature Range Variability
e_sat Saturation vapor pressure
effective_growing_degree_days Effective growing degree days computed with
{method} formula (Summation of max((Tmin +
Tmax)/2 - {thresh}, 0), for days between
between dynamically-determined start and end
dates). (egdd)
etr Intra-period Extreme Temperature Range
fire_season Fire season mask
first_day_above First day of year with temperature above
{thresh}
first_day_below First day of year with temperature below
{thresh}
first_snowfall Date of first snowfall
fit {dist} distribution parameters (params)
fraction_over_precip_doy_thresh
Fraction of precipitation over threshold
during wet days.
fraction_over_precip_thresh Fraction of precipitation over threshold
during wet days.
freezethaw_spell_frequency {freq} number of freeze-thaw spells.
freezethaw_spell_max_length {freq} maximal length of freeze-thaw spells.
freezethaw_spell_mean_length {freq} average length of freeze-thaw spells.
freezing_degree_days Freezing degree days (Tmean < {thresh})
freq_analysis N-year return period {mode} {indexer}
{window}-day flow
(q{window}{mode:r}{indexer})
freshet_start Day of year of spring freshet start
frost_days Number of frost days (Tmin < {thresh})
frost_free_season_end Day of year of frost free season end
frost_free_season_length Length of the frost free season
frost_free_season_start Day of year of frost free season start
frost_season_length Length of the frost season
fwi Drought Code, Duff Moisture Code, Fine Fuel
Moisture Code, Initial Spread Index, Buildup
Index, Fire Weather Index (dc, dmc, ffmc,
isi, bui, fwi)
growing_degree_days Growing degree days above {thresh}
growing_season_end Day of year of growing season end
growing_season_length ETCCDI Growing Season Length (Tmean >
{thresh})
growing_season_start Day of year of growing season start
heat_index heat index
heat_wave_frequency Number of heat wave events (Tmin >
{thresh_tasmin} and Tmax > {thresh_tasmax}
for >= {window} days)
heat_wave_index Number of days that are part of a heatwave
heat_wave_max_length Maximum length of heat wave events (Tmin >
{thresh_tasmin}and Tmax > {thresh_tasmax}
for >= {window} days)
heat_wave_total_length Total length of heat wave events (Tmin >
{thresh_tasmin} and Tmax > {thresh_tasmax}
for >= {window} days)
heating_degree_days Heating degree days (Tmean < {thresh})
high_precip_low_temp Count of days with high precipitation and
low temperatures.
hot_spell_frequency Number of hot spell events (Tmax >
{thresh_tasmax} for >= {window} days)
hot_spell_max_length Maximum length of hot spell events (Tmax >
{thresh_tasmax} for >= {window} days)
huglin_index Huglin heliothermal index (Summation of
((Tmin + Tmax)/2 - {thresh}) * Latitude-
based day-lengthcoefficient (`k`), for days
between {start_date} and {end_date}). (hi)
humidex humidex index
hurs Relative Humidity
hurs_fromdewpoint Relative Humidity (hurs)
huss Specific Humidity
icclim.bedd Biologically effective growing degree days
(Summation of min((max((Tmin + Tmax)/2 -
{thresh_tasmin}, 0)), 9°C), for days between
1 April and 30 September) (BEDD)
icclim.cd Cold and dry days (CD)
icclim.cdd Maximum number of consecutive dry days (RR<1
mm) (CDD)
icclim.cfd Maximum number of consecutive frost days
(TN<0°C) (CFD)
icclim.csdi Cold-spell duration index (CSDI)
icclim.csu Maximum number of consecutive summer day
(CSU)
icclim.cw cold and wet days (CW)
icclim.cwd Maximum number of consecutive wet days (RR≥1
mm) (CWD)
icclim.dtr Mean of diurnal temperature range (DTR)
icclim.etr Intra-period extreme temperature range (ETR)
icclim.fd Frost days (TN<0°C) (FD)
icclim.gd4 Growing degree days (sum of TG>4°C) (GD4)
icclim.gsl Growing season length (GSL)
icclim.hd17 Heating degree days (sum of17°C - TG) (HD17)
icclim.hi Huglin heliothermal index (Summation of
((Tmean + Tmax)/2 - {thresh}) * Latitude-
based day-length coefficient (`k`), for days
between 1 April and 31 October) (HI)
icclim.id Ice days (TX<0°C) (ID)
icclim.prcptot Precipitation sum over wet days (PRCPTOT)
icclim.r10mm Heavy precipitation days (precipitation≥10
mm) (R10mm)
icclim.r20mm Very heavy precipitation days
(precipitation≥20 mm) (R20mm)
icclim.r75p Count of days with daily precipitation above
the given percentile [days].
(days_over_precip_thresh)
icclim.r75ptot Precipitation fraction due to moderate wet
days (>75th percentile) (R75pTOT)
icclim.r95p Count of days with daily precipitation above
the given percentile [days].
(days_over_precip_thresh)
icclim.r95ptot Precipitation fraction due to very wet days
(>95th percentile) (R95pTOT)
icclim.r99p Count of days with daily precipitation above
the given percentile [days].
(days_over_precip_thresh)
icclim.r99ptot Precipitation fraction due to extremely wet
days (>99th percentile) (R99pTOT)
icclim.rr Precipitation sum (RR)
icclim.rr1 Wet days (RR≥1 mm) (RR1)
icclim.rx1day Highest 1-day precipitation amount (RX1day)
icclim.rx5day Highest 5-day precipitation amount (RX5day)
icclim.sd Mean of daily snow depth (SD)
icclim.sd1 Snow days (SD≥1 cm) (SD1)
icclim.sd50cm Snow days (SD≥50 cm) (SD50cm)
icclim.sd5cm Snow days (SD≥5 cm) (SD5cm)
icclim.sdii Average precipitation during wet days (SDII)
(sdii)
icclim.su Summer days (TX>25°C) (SU)
icclim.tg Mean daily mean temperature (tg_mean)
icclim.tg10p Days with TG<10th percentile of daily mean
temperature (cold days) (TG10p)
icclim.tg90p Days with TG>90th percentile of daily mean
temperature (warm days) (TG90p)
icclim.tgn Minimum daily mean temperature (tg_min)
icclim.tgx Maximum daily mean temperature (tg_max)
icclim.tn Mean daily minimum temperature (tn_mean)
icclim.tn10p Days with TN<10th percentile of daily
minimum temperature (cold nights) (TN10p)
icclim.tn90p Days with TN>90th percentile of daily
minimum temperature (warm nights) (TN90p)
icclim.tnn Minimum daily minimum temperature (tn_min)
icclim.tnx Maximum daily minimum temperature (tn_max)
icclim.tr Tropical nights (TN>20°C) (TR)
icclim.tx Mean daily maximum temperature (tx_mean)
icclim.tx10p Days with TX<10th percentile of daily
maximum temperature (cold day-times) (TX10p)
icclim.tx90p Days with TX>90th percentile of daily
maximum temperature (warm day-times) (TX90p)
icclim.txn Minimum daily maximum temperature (tx_min)
icclim.txx Maximum daily maximum temperature (tx_max)
icclim.vdtr Mean absolute day-to-day difference in DTR
(vDTR)
icclim.wd Warm and dry days (WD)
icclim.wsdi Warm-spell duration index (WSDI)
icclim.ww Warm and wet days (WW)
ice_days Number of ice days (Tmax < {thresh})
jetstream_metric_woollings Latitude of maximum smoothed zonal wind
speed, Maximum strength of smoothed zonal
wind speed (jetlat, jetstr)
last_snowfall Date of last snowfall
last_spring_frost Day of year of last spring frost
latitude_temperature_index Latitude-temperature index (lti)
liquid_precip_ratio Ratio of rainfall to total precipitation.
liquidprcptot Total liquid precipitation
max_n_day_precipitation_amount maximum {window}-day total precipitation
(rx{window}day)
max_pr_intensity Maximum precipitation intensity over
{window}h duration
maximum_consecutive_warm_days The maximum number of days with tasmax >
thresh per periods (summer days).
melt_and_precip_max The maximum snow melt plus precipitation
over a given number of days for each period.
[mass/area]. ({freq}_melt_and_precip_max)
potential_evapotranspiration Potential evapotranspiration (evspsblpot)
prcptot Total precipitation
prlp Liquid precipitation
prsn Solid precipitation
rain_frzgr Number of rain on frozen ground days
rb_flashiness_index Richards-Baker flashiness index (rbi)
rprctot The proportion of the total precipitation
accounted for by convective precipitation
for each period.
rx1day maximum 1-day total precipitation
sdii Average precipitation during wet days (SDII)
sea_ice_area Sea ice area
sea_ice_extent Sea ice extent
snd_max_doy Date when snow depth reaches its maximum
value. ({freq}_snd_max_doy)
snow_cover_duration Number of days with snow depth above
threshold
snow_depth Mean of daily snow depth
snow_melt_we_max The maximum snow melt over a given number of
days for each period. [mass/area].
({freq}_snow_melt_we_max)
snw_max Maximum daily snow amount ({freq}_snw_max)
snw_max_doy Day of year of maximum daily snow amount
({freq}_snw_max_doy)
solidprcptot Total solid precipitation
stats {freq} {op} of {indexer} daily flow
(q{indexer}{op:r})
tg Daily mean temperature
tg10p Number of days when Tmean < 10th percentile
tg90p Number of days when Tmean > 90th percentile
tg_days_above Number of days with Tavg > {thresh}
tg_days_below Number of days with Tavg < {thresh}
tg_max Maximum daily mean temperature
tg_mean Mean daily mean temperature
tg_min Minimum daily mean temperature
thawing_degree_days Thawing degree days (degree days above 0°C)
tn10p Number of days when Tmin < 10th percentile
tn90p Number of days when Tmin > 90th percentile
tn_days_above Number of days with Tmin > {thresh}
tn_days_below Number of days with Tmin < {thresh}
tn_max Maximum daily minimum temperature
tn_mean Mean daily minimum temperature
tn_min Minimum daily minimum temperature
tropical_nights Number of Tropical Nights (Tmin > {thresh})
tx10p Number of days when Tmax < 10th percentile
tx90p Number of days when Tmax > 90th percentile
tx_days_above Number of days with Tmax > {thresh}
tx_days_below Number of days with Tmax < {thresh}
tx_max Maximum daily maximum temperature
tx_mean Mean daily maximum temperature
tx_min Minimum daily maximum temperature
tx_tn_days_above Number of days with Tmax > {thresh_tasmax}
and Tmin > {thresh_tasmin}
warm_and_dry_days warm and dry days
warm_and_wet_days warm and wet days
warm_spell_duration_index Warm spell duration index.
water_budget Water budget
wet_prcptot Total precipitation
wetdays Number of wet days (precip >= {thresh})
wetdays_prop Proportion of wet days (precip >= {thresh})
wind_chill Wind chill index
wind_speed_from_vector Near-Surface Wind Speed, Near-Surface Wind
from Direction (sfcWind, sfcWindfromdir)
wind_vector_from_speed Near-Surface Eastward Wind, Near-Surface
Northward Wind (uas, vas)
windy_days Number of days with surface wind speed above
threshold
winter_storm Number of days per period identified as
winter storms. ({freq}_winter_storm)
For more information about a specific indicator, you can either use the info subcommand or directly access the --help message of the indicator. The former gives more information about the metadata while the latter only prints the usage. Note that the module name (atmos, land or seaIce) is mandatory.
[3]:
!xclim info liquidprcptot
Indicator liquidprcptot:
identifier : liquidprcptot
title : Accumulated liquid precipitation.
abstract : Resample the original daily mean precipitation flux
and accumulate over each period. If a daily temperature is provided, the
`phase` keyword can be used to sum precipitation of a given phase only. When
the temperature is under the provided threshold, precipitation is assumed to
be snow, and liquid rain otherwise. This indice is agnostic to the type of
daily temperature (tas, tasmax or tasmin) given.
keywords :
outputs (#1)
standard_name : lwe_thickness_of_liquid_precipitation_amount
long_name : Total liquid precipitation
units : mm
cell_methods : time: sum within days time: sum over days
description : Annual total liquid precipitation, estimated as
precipitation when temperature >= 0 degc
var_name : liquidprcptot
notes : Let :math:`PR_i` be the mean daily precipitation of day
:math:`i`, then for a period :math:`j` starting at day :math:`a` and
finishing on day :math:`b`:
.. math::
PR_{ij} = \sum_{i=a}^{b} PR_i
If tas and phase are given, the corresponding phase precipitation is
estimated before computing the accumulation, using one of
`snowfall_approximation` or `rain_approximation` with the `binary` method.
Options:
--pr VAR_NAME Mean daily precipitation flux. [default: pr]
--tas VAR_NAME Mean, maximum or minimum daily temperature. [default: tas]
--thresh TEXT Threshold of `tas` over which the precipication is assumed
to be liquid rain. [default: 0 degC]
--freq TEXT Resampling frequency. [default: YS]
--help Show this message and exit.
In the usage message, VAR_NAME indicates that the passed argument must match a variable in the input dataset.
[4]:
import warnings
import numpy as np
import pandas as pd
import xarray as xr
from pandas.plotting import register_matplotlib_converters
register_matplotlib_converters()
warnings.filterwarnings("ignore", "implicitly registered datetime converter")
%matplotlib inline
xr.set_options(display_style="html")
time = pd.date_range("2000-01-01", periods=366)
tasmin = xr.DataArray(
-5 * np.cos(2 * np.pi * time.dayofyear / 365) + 273.15,
dims=("time"),
coords={"time": time},
attrs={"units": "K"},
)
tasmax = xr.DataArray(
-5 * np.cos(2 * np.pi * time.dayofyear / 365) + 283.15,
dims=("time"),
coords={"time": time},
attrs={"units": "K"},
)
pr = xr.DataArray(
np.clip(10 * np.sin(18 * np.pi * time.dayofyear / 365), 0, None),
dims=("time"),
coords={"time": time},
attrs={"units": "mm/d"},
)
ds = xr.Dataset({"tasmin": tasmin, "tasmax": tasmax, "pr": pr})
ds.to_netcdf("example_data.nc")
Computing indicators
So let’s say we have the following toy dataset:
[5]:
import xarray as xr
ds = xr.open_dataset("example_data.nc")
display(ds)
<xarray.Dataset>
Dimensions: (time: 366)
Coordinates:
* time (time) datetime64[ns] 2000-01-01 2000-01-02 ... 2000-12-31
Data variables:
tasmin (time) float64 268.2 268.2 268.2 268.2 ... 268.2 268.2 268.1 268.2
tasmax (time) float64 278.2 278.2 278.2 278.2 ... 278.2 278.2 278.1 278.2
pr (time) float64 1.543 3.049 4.482 5.808 6.995 ... 0.0 0.0 0.0 1.543[6]:
import matplotlib.pyplot as plt
fig, (axT, axpr) = plt.subplots(1, 2, figsize=(10, 5))
ds.tasmin.plot(label="tasmin", ax=axT)
ds.tasmax.plot(label="tasmax", ax=axT)
ds.pr.plot(ax=axpr)
axT.legend()
[6]:
<matplotlib.legend.Legend at 0x7f15d1326520>
To compute an indicator, say the monthly solid precipitation accumulation, we simply call:
[7]:
!xclim -i example_data.nc -o out1.nc solidprcptot --pr pr --tas tasmin --freq MS
/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.33.2/lib/python3.8/site-packages/xclim/core/cfchecks.py:39: UserWarning: Variable does not have a `cell_methods` attribute.
_check_cell_methods(
/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.33.2/lib/python3.8/site-packages/xclim/core/cfchecks.py:43: UserWarning: Variable does not have a `standard_name` attribute.
check_valid(vardata, "standard_name", data["standard_name"])
/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.33.2/lib/python3.8/site-packages/xclim/indicators/atmos/_precip.py:61: UserWarning: Variable does not have a `standard_name` attribute.
cfchecks.check_valid(tas, "standard_name", "air_temperature")
[########################################] | 100% Completed | 0.1s
In this example, we decided to use tasmin for the tas variable. We didn’t need to provide the --pr parameter as our data has the same name.
Finally, more than one indicators can be computed to the output dataset by simply chaining the calls:
[8]:
!xclim -i example_data.nc -o out2.nc liquidprcptot --tas tasmin --freq MS tropical_nights --thresh "2 degC" --freq MS
/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.33.2/lib/python3.8/site-packages/xclim/core/cfchecks.py:39: UserWarning: Variable does not have a `cell_methods` attribute.
_check_cell_methods(
/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.33.2/lib/python3.8/site-packages/xclim/core/cfchecks.py:43: UserWarning: Variable does not have a `standard_name` attribute.
check_valid(vardata, "standard_name", data["standard_name"])
/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.33.2/lib/python3.8/site-packages/xclim/indicators/atmos/_precip.py:61: UserWarning: Variable does not have a `standard_name` attribute.
cfchecks.check_valid(tas, "standard_name", "air_temperature")
/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.33.2/lib/python3.8/site-packages/xclim/core/cfchecks.py:39: UserWarning: Variable does not have a `cell_methods` attribute.
_check_cell_methods(
/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.33.2/lib/python3.8/site-packages/xclim/core/cfchecks.py:43: UserWarning: Variable does not have a `standard_name` attribute.
check_valid(vardata, "standard_name", data["standard_name"])
[########################################] | 100% Completed | 0.1s
Let’s see the outputs:
[9]:
ds1 = xr.open_dataset("out1.nc")
ds2 = xr.open_dataset("out2.nc", decode_timedelta=False)
fig, (axPr, axTn) = plt.subplots(1, 2, figsize=(10, 5))
ds1.solidprcptot.plot(ax=axPr, label=ds1.solidprcptot.long_name)
ds2.liquidprcptot.plot(ax=axPr, label=ds2.liquidprcptot.long_name)
ds2.tropical_nights.plot(ax=axTn, marker="o")
axPr.legend()
[9]:
<matplotlib.legend.Legend at 0x7f15cf093f10>
[10]:
ds1.close()
[11]:
ds2.close()
Data Quality Checks
As of version 0.30.0, xclim now also provides a command-line utility for performing data quality control checks on existing NetCDF files.
These checks examine the values of data_variables for suspicious value patterns (e.g. values that repeat for many days) or erroneous values (e.g. humidity percentages outside of 0-100, minimum temperatures exceeding maximum temperatures, etc.). The checks (called “data flags”) are based on the ECAD ICCLIM quality control checks (https://www.ecad.eu/documents/atbd.pdf).
The full list of checks performed for each variable are listed in xclim/core/data/variables.yml.
[12]:
!xclim dataflags --help
Usage: xclim dataflags [OPTIONS] [VARIABLES]...
Run quality control checks on input data variables and flag for quality
control issues or suspicious values.
Options:
-r, --raise-flags Print an exception in the event that a variable is found
to have quality control issues.
-a, --append Return the netCDF dataset with the `ecad_qc_flag` array
appended as a data_var.
-d, --dims TEXT Dimensions upon which aggregation should be performed.
Default: "all". Ignored if no variable provided.
-f, --freq TEXT Resampling periods frequency used for aggregation.
Default: None. Ignored if no variable provided.
--help Show this message and exit.
When running the dataflags CLI checks, you must either set an output file (-o filename.nc) or set the checks to raise if there are any failed checks (-r).
By default, when setting an output file, the returned file will only contain the flag value (True if no flags were raised, False otherwise). To append the flag to a copy of the dataset, we use the -a option.
The default behaviour is to raise a flag if any element of the array resolves to True (ie: aggregated across all dimensions), but we can specify the level of aggregation by dimension with the -d or --dims option.
[13]:
# Create an output file with just the flag value and no aggregation (dims=None)
!xclim -i example_data.nc -o flag_output.nc dataflags -d none
# Need to wait until the file is written
!sleep 2s
[########################################] | 100% Completed | 2.1s
[14]:
import xarray as xr
ds1 = xr.open_dataset("flag_output.nc")
display(ds1.data_vars, ds1.ecad_qc_flag)
ds1.close()
Data variables:
ecad_qc_flag (time) bool ...
<xarray.DataArray 'ecad_qc_flag' (time: 366)>
array([ True, True, True, ..., True, True, True])
Coordinates:
* time (time) datetime64[ns] 2000-01-01 2000-01-02 ... 2000-12-31
Attributes:
comment: Adheres to ECAD quality control checks.
history: [2022-02-09 19:29:12] - xclim version: 0.33.2. - Performed the ...[15]:
# Create an output file with values appended to the original dataset.
!xclim -i example_data.nc -o flag_output_appended.nc dataflags -a
# Need to wait until the file is written
!sleep 2s
[########################################] | 100% Completed | 1.3s
[16]:
import xarray as xr
ds2 = xr.open_dataset("flag_output_appended.nc")
display(ds2.data_vars, ds2.ecad_qc_flag)
ds2.close()
Data variables:
tasmin (time) float64 ...
tasmax (time) float64 ...
pr (time) float64 ...
ecad_qc_flag bool ...
<xarray.DataArray 'ecad_qc_flag' ()>
array(True)
Attributes:
comment: Adheres to ECAD quality control checks.
history: [2022-02-09 19:29:27] - xclim version: 0.33.2. - Performed the ...[17]:
# Raise an error if any quality control checks fail. Passing example:
!xclim -i example_data.nc dataflags -r
Dataset passes quality control checks!
[18]:
import xarray as xr
# Create some bad data with minimum temperatures exceeding max temperatures
bad_ds = xr.open_dataset("example_data.nc")
# Swap entire variable arrays
bad_ds["tasmin"].values, bad_ds["tasmax"].values = (
bad_ds.tasmax.values,
bad_ds.tasmin.values,
)
bad_ds.to_netcdf("suspicious_data.nc")
bad_ds.close()
[19]:
# Raise an error if any quality control checks fail. Failing example:
!xclim -i suspicious_data.nc dataflags -r
Data quality flags indicate suspicious values. Flags raised are:
- Maximum temperature values found below minimum temperatures.
- Maximum temperature values found below minimum temperatures.
These checks can also be set to examine a specifc variable within a netcdf file, with more descriptive information for each check performed.
[20]:
!xclim -i example_data.nc -o flag_output_pr.nc dataflags pr
[########################################] | 100% Completed | 2.3s
[21]:
import xarray as xr
ds3 = xr.open_dataset("flag_output_pr.nc")
display(ds3.data_vars)
for dv in ds3.data_vars:
display(ds3[dv])
Data variables:
negative_accumulation_values bool ...
very_large_precipitation_events bool ...
values_eq_5_repeating_for_5_or_more_days bool ...
values_eq_1_repeating_for_10_or_more_days bool ...
<xarray.DataArray 'negative_accumulation_values' ()>
array(False)
Attributes:
description: Negative values found for pr.
units:
history: [2022-02-09 19:30:08] pr: negative_accumulation_values(pr) ...<xarray.DataArray 'very_large_precipitation_events' ()>
array(False)
Attributes:
description: Precipitation events in excess of 300 mm d-1 for pr.
units:
history: [2022-02-09 19:30:08] pr: very_large_precipitation_events(p...<xarray.DataArray 'values_eq_5_repeating_for_5_or_more_days' ()>
array(False)
Attributes:
description: Repetitive values at 5.0 for at least 5 days found for pr.
units:
history: [2022-02-09 19:30:08] pr: values_op_thresh_repeating_for_n_...<xarray.DataArray 'values_eq_1_repeating_for_10_or_more_days' ()>
array(False)
Attributes:
description: Repetitive values at 1.0 for at least 10 days found for pr.
units:
history: [2022-02-09 19:30:08] pr: values_op_thresh_repeating_for_n_...