Basic Usage

Health checks and metadata attributes

Indicator instances from the CF layer are found in modules bearing the name of the computational realm in which its input variables are found: xclim.atmos, xclim.land and xclim.seaIce. These objects from the CF layer run sanity checks on the input variables and set output’s metadata according to CF-convention when they apply. Some of the checks involve:

Identifying periods where missing data significantly impacts the calculation and omits calculations for those periods. Those are called “missing methods” and are detailed in section Health checks.
Appending process history and maintaining the historical provenance of file metadata.
Writing Climate and Forecast Convention compliant metadata based on the variables and indices calculated.

Those modules are best used for producing NetCDF that will be shared with users. See Climate Indicators for a list of available indicators.

If we run the growing_degree_days indicator over a non daily dataset, we’ll be warned that the input data is not daily. That is, running xclim.atmos.growing_degree_days(ds.air, thresh='10.0 degC', freq='MS') will fail with a ValidationError:

[5]:

ds6h = xr.tutorial.open_dataset("air_temperature")
gdd = xclim.atmos.growing_degree_days(ds6h.air, thresh="10.0 degC", freq="MS")

---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
ValueError: time series is not recognized as daily. You can quiet this error by setting `data_validation` to 'warn' or 'log', in `xclim.set_options`.

The above exception was the direct cause of the following exception:

ValidationError                           Traceback (most recent call last)
/tmp/ipykernel_716/3753143723.py in <module>
      1 ds6h = xr.tutorial.open_dataset("air_temperature")
----> 2 gdd = xclim.atmos.growing_degree_days(ds6h.air, thresh="10.0 degC", freq="MS")

~/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/indicator.py in __call__(self, *args, **kwds)
    798
    799         # Pre-computation validation checks on DataArray arguments
--> 800         self._bind_call(self.datacheck, **das)
    801         self._bind_call(self.cfcheck, **das)
    802

~/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/indicator.py in _bind_call(self, func, **das)
    932         else:
    933             # Call the func using bound arguments
--> 934             return func(*ba.args, **ba.kwargs)
    935
    936     @classmethod

~/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/indicator.py in datacheck(**das)
   1295         for key, da in das.items():
   1296             if "time" in da.coords and da.time.ndim == 1 and len(da.time) > 3:
-> 1297                 datachecks.check_daily(da)
   1298
   1299

<boltons.funcutils.FunctionBuilder-146> in check_daily(var)

~/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/options.py in run_check(*args, **kwargs)
    114     @wraps(func)
    115     def run_check(*args, **kwargs):
--> 116         return _run_check(func, DATA_VALIDATION, *args, **kwargs)
    117
    118     return run_check

~/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/options.py in _run_check(func, option, *args, **kwargs)
    106         func(*args, **kwargs)
    107     except ValidationError as err:
--> 108         raise_warn_or_log(err, OPTIONS[option], stacklevel=4)
    109
    110

~/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/utils.py in raise_warn_or_log(err, mode, msg, stacklevel)
    384         warnings.warn(msg, stacklevel=stacklevel + 1)
    385     else:  # mode == "raise"
--> 386         raise err from ValueError(msg)
    387
    388

~/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/options.py in _run_check(func, option, *args, **kwargs)
    104     """Run function and customize exception handling based on option."""
    105     try:
--> 106         func(*args, **kwargs)
    107     except ValidationError as err:
    108         raise_warn_or_log(err, OPTIONS[option], stacklevel=4)

~/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/datachecks.py in check_daily(var)
     54     if xr.infer_freq(var.time) != "D":
     55         raise ValidationError(
---> 56             "time series is not recognized as daily. You can quiet this error by setting `data_validation` to 'warn' or 'log', in `xclim.set_options`."
     57         )

ValidationError: time series is not recognized as daily. You can quiet this error by setting `data_validation` to 'warn' or 'log', in `xclim.set_options`.

Resampling to a daily frequency and running the same indicator succeeds, but we still get warnings from the CF metadata checks.

[6]:

daily_ds = ds6h.resample(time="D").mean(keep_attrs=True)
gdd = xclim.atmos.growing_degree_days(daily_ds.air, thresh="10.0 degC", freq="YS")

/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/cfchecks.py:40: UserWarning: Variable does not have a `cell_methods` attribute.
  getattr(vardata, "cell_methods", None), data["cell_methods"]
/home/docs/checkouts/readthedocs.org/user_builds/xclim/envs/v0.31.0/lib/python3.7/site-packages/xclim/core/cfchecks.py:43: UserWarning: Variable does not have a `standard_name` attribute.
  check_valid(vardata, "standard_name", data["standard_name"])

To suppress the CF validation warnings in the following, we will set xclim to send them to the log, instead of raising a warning or an error.

The missing method which determines if a period should be considered missing or not can be controlled through the check_missing option, globally or contextually. The main missing methods also have options that can be modified.

[7]:

with xclim.set_options(
    check_missing="pct",
    missing_options={"pct": dict(tolerance=0.1)},
    cf_compliance="log",
):
    # Change the missing method to "percent", instead of the default "any"
    # Set the tolerance to 10%, periods with more than 10% of missing data
    #     in the input will be masked in the ouput.
    gdd = xclim.atmos.growing_degree_days(daily_ds.air, thresh="10.0 degC", freq="MS")

Finally, xclim also allows to call indicators using datasets and variable names.

[8]:

with xclim.set_options(cf_compliance="log"):
    gdd = xclim.atmos.growing_degree_days(
        tas="air", thresh="10.0 degC", freq="MS", ds=daily_ds
    )

    # variable names default to xclim names, so we can even do this:
    renamed_daily_ds = daily_ds.rename(air="tas")
    gdd = xclim.atmos.growing_degree_days(
        thresh="10.0 degC", freq="MS", ds=renamed_daily_ds
    )

Graphics

[9]:

import matplotlib.pyplot

%matplotlib inline

# Summary statistics histogram
gdd.plot()

[9]:

(array([15532.,  2079.,  1861.,  1935.,  2137.,  2416.,  2675.,  2202.,
          931.,    32.]),
 array([  0.     ,  66.32573, 132.65146, 198.9772 , 265.30292, 331.62866,
        397.9544 , 464.28012, 530.60583, 596.9316 , 663.2573 ],
       dtype=float32),
 <BarContainer object of 10 artists>)

[10]:

# Show time series at a given geographical coordinate
gdd.isel(lon=20, lat=10).plot()

[10]:

[<matplotlib.lines.Line2D at 0x7ff70c0abe90>]

[11]:

# Show spatial pattern at a specific time period
gdd.sel(time="2013-07").plot()

[11]:

<matplotlib.collections.QuadMesh at 0x7ff70bec0150>

For more examples, see the directions suggested by xarray’s plotting documentation

To save the data as a new NetCDF, use to_netcdf.

[12]:

gdd.to_netcdf("monthly_growing_degree_days_data.nc")

It’s possible to save Dataset objects to other file formats. For more information see: xarray’s documentation

Basic Usage

Climate indicator computations

Health checks and metadata attributes

Graphics