========================================== xclim: Climate indices computations |logo|

|license| |build| |pypi| |conda| |coveralls| |codefactor| |zenodo| |black| |docs| |gitter|

xclim is a library of functions to compute climate indices from observations or model simulations. It is built using xarray_ and can benefit from the parallelization handling provided by dask_. Its objective is to make it as simple as possible for users to compute indices from large climate datasets and for scientists to write new indices with very little boilerplate.

For example, the following would compute monthly mean temperature from daily mean temperature:

.. code-block:: python

import xclim import xarray as xr ds = xr.open_dataset(filename) tg = xclim.ICCLIM.TG(ds.tas, freq='YS')

For applications where meta-data and missing values are important to get right, xclim provides a class for each index that validates inputs, checks for missing values, converts units and assigns metadata attributes to the output. This also provides a mechanism for users to customize the indices to their own specifications and preferences.

xclim currently provides over 50 indices related to mean, minimum and maximum daily temperature, daily precipitation, streamflow and sea ice concentration.

.. _xarray: http://xarray.pydata.org/ .. _dask: https://dask.org/

Documentation

The official documentation is at https://xclim.readthedocs.io/

Contributing

xclim is in active development and it's being used in production by climate services specialists. If you're interested in participating to the development, want to suggest features, new indices or report bugs, please leave us a message on the issue tracker <https://github.com/Ouranosinc/xclim/issues>_. There is also a chat room on gitter (|gitter|).

Credits

This work is made possible thanks to the contribution of the Canadian Center for Climate Services.

This package was created with Cookiecutter_ and the audreyr/cookiecutter-pypackage_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter .. _audreyr/cookiecutter-pypackage: https://github.com/audreyr/cookiecutter-pypackage

.. |pypi| image:: https://img.shields.io/pypi/v/xclim.svg :target: https://pypi-hypernode.com/pypi/xclim :alt: Python Package Index Build

.. |conda| image:: https://img.shields.io/conda/vn/conda-forge/xclim.svg :target: https://anaconda.org/conda-forge/xclim :alt: Conda-forge Build Version

.. |gitter| image:: https://badges.gitter.im/Ouranosinc/xclim.svg :target: https://gitter.im/Ouranosinc/xclim?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge :alt: Gitter Chat

.. |build| image:: https://img.shields.io/travis/Ouranosinc/xclim.svg :target: https://travis-ci.org/Ouranosinc/xclim :alt: Build Status

.. |coveralls| image:: https://coveralls.io/repos/github/Ouranosinc/xclim/badge.svg :target: https://coveralls.io/github/Ouranosinc/xclim :alt: Coveralls

.. |codefactor| image:: https://www.codefactor.io/repository/github/ouranosinc/xclim/badge :target: https://www.codefactor.io/repository/github/ouranosinc/xclim :alt: CodeFactor

.. |docs| image:: https://readthedocs.org/projects/xclim/badge :target: https://xclim.readthedocs.io/en/latest :alt: Documentation Status

.. |zenodo| image:: https://zenodo.org/badge/142608764.svg :target: https://zenodo.org/badge/latestdoi/142608764 :alt: DOI

.. |license| image:: https://img.shields.io/github/license/Ouranosinc/xclim.svg :target: https://github.com/Ouranosinc/xclim/blob/master/LICENSE :alt: License

.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/python/black :alt: Python Black

.. |logo| image:: https://github.com/Ouranosinc/xclim/blob/master/_static/_images/xclim-logo-small.png :target: https://github.com/Ouranosinc/xclim/blob/master/_static/_images/xclim-logo-small.png :alt: xclim

======= History

0.13.x (2020-01-10)

• Documentation improvements: list of indicators, RTD theme, notebook example.
• Added sea_ice_extent and sea_ice_area indicators.
• Reverted #311, removing the _rolling util function. Added optimal keywords to rolling() calls.
• Fixed ensembles.create_ensemble errors for builds against xarray master branch.
• Reformatted code to make better use of Python3.6 conventions (f-strings and object signatures).
• Fixed randomly failing tests of checks.missing_any.
• Improvement of ensemble.ensemble_percentile and ensemble.create_ensemble.

0.12.x-beta (2019-11-18)

• Added a distance function computing the geodesic distance to a point.
• Added a tolerance argument to subset_gridpoint raising an error if distance to closest point is larger than tolerance.
• Created land module for standardized access to streamflow indices.
• Enhancement to utils.Indicator to have more dynamic attributes using callables.
• Added indices heat_wave_total_length and tas / tg to average tasmin and tasmax into tas.
• Fixed a bug with typed call signatures that caused downstream failures on library import.
• Added a _rolling util function to fix memory issues on large dask datasets.
• Added the subset_shape function to subset utilities for clipping region-masked datasets via polygons.
• Fixed a bug where certain dependencies caused ReadTheDocs builds to fail.
• Added many statically typed function signatures for better function documentation.
• Improved DeprecationWarnings and UserWarnings ensemble for xclim subsetting functions.
• Dropped support for Python3.5.

0.11.x-beta (2019-10-17)

• Added type hinting to call signatures of many functions for more explicit type-checking.
• Added Kmeans clustering ensemble reduction algorithms.
• Added utilities for converting between wind velocity (sfcWind) and wind components (uas, vas) arrays.
• Added type hinting to call signatures of many functions for more explicit type-checking.
• Now supporting explicit builds for Windows OS via Travis CI.
• Fix failing test with Python 3.7.
• Fixed bug in subset.subset_bbox that could add unwanted coordinates/dims to some variables when applied to an entire dataset.
• Reformatted packaging configuration to pure Py3 wheel that ignore tests and test data.
• Now officially supporting Python3.8!
• Enhancement to precip_accumulation() to allow estimated amounts solid (or liquid) phase precipitation.
• Bugfix for frequency analysis choking on time series with NaNs only.

0.10.x-beta (2019-06-18)

• Added indices to ICCLIM module.
• Added indices days_over_precip_thresh and fraction_over_precip_thresh.
• Migrated to a major.minor.patch-release semantic versioning system.
• Removed attributes in netCDF output from Indicators that are not in the CF-convention.
• Added fit indicator to fit the parameters of a distribution to a series.
• Added utilities with ensemble, run length, and subset algorithms to the documentation.
• Source code development standards now implement Python Black formatting.
• Pre-commit is now used to launch code formatting inspections for local development.
• Documentation now includes more detailed usage and an example workflow notebook.
• Development build configurations are now available via both Anaconda and pip install methods.
• Modified create_ensembles() to allow creation of ensemble dataset without a time dimension as well as from xr.Datasets.
• Modified create ensembles() to pad input data with nans when time dimensions are unequal.
• Updated subset_gridpoint() and subset_bbox() to use .sel method if 'lon' and 'lat' dims are present.
• Added Azure Pipelines to automatically build xclim in Microsoft Windows environments. -- REMOVED
• Now employing PEP8 + Black compatible autoformatting.
• Added Windows and macOS images to Travis CI build ensemble.
• Added variable thresholds for tasmax and tasmin in daily_freezethaw_events.
• Updated subset.py to use date formatted strings ("%Y", "%Y%m" etc.) in temporal subsetting.
• Clean-up of day-of-year resampling. Precipitation percentile threshold will work without a doy index.
• Addressed deprecations for xarray 0.13.0.
• Added a decorator function that verifies validity and reformats subset calls using start_date or end_date signatures.
• Fixed a bug where 'lon' or 'lon_bounds' would return false values if either signatures were set to 0.

0.10-beta (2019-06-06)

• Dropped support for Python 2.
• Added support for period of the year subsetting in checks.missing_any.
• Now allow for passing positive longitude values when subsetting data with negative longitudes.
• Improved runlength calculations for small grid size arrays via ufunc_1dim flag.

0.9-beta (2019-05-13)

This is a significant jump in the release. Many modifications have been made and will be added to the documentation in the coming days. Among the many changes:

• New indices have been added with documentation and call examples.
• Run_length based operations have been optimized.
• Support for CF non-standard calendars.
• Automated/improved unit conversion and management via pint library.
• Added ensemble utilities for creation and analysis of muti-model climate ensembles.
• Added subsetting utilities for spatio-temporal subsets of xarray data objects.
• Added streamflow indicators.
• Refactoring of the code : separation of indices.py into a directory with sub-files (simple, threshold and multivariate); ensembles and subset utilities separated into distinct modules (pulled from utils.py).
• Indicators are now split into packages named by realms. import xclim.atmos to load indicators related to atmospheric variables.

0.8-beta (2019-02-11)

This was a staging release and is functionally identical to 0.7-beta.

0.7-beta (2019-02-05)

Major Changes:

• Support for resampling of data structured using non-standard CF-Time calendars.
• Added several ICCLIM and other indicators.
• Dropped support for Python 3.4.
• Now under Apache v2.0 license.
• Stable PyPI-based dependencies.
• Dask optimizations for better memory management.
• Introduced class-based indicator calculations with data integrity verification and CF-Compliant-like metadata writing functionality.

Class-based indicators are new methods that allow index calculation with error-checking and provide on-the-fly metadata checks for CF-Compliant (and CF-compliant-like) data that are passed to them. When written to NetCDF, outputs of these indicators will append appropriate metadata based on the indicator, threshold values, moving window length, and time period / resampling frequency examined.

0.6-alpha (2018-10-03)

• File attributes checks.
• Added daily downsampler function.
• Better documentation on ICCLIM indices.

0.5-alpha (2018-09-26)

• Added total precipitation indicator.

0.4-alpha (2018-09-14)

• Fully PEP8 compliant and available under MIT License.

0.3-alpha (2018-09-4)

• Added icclim module.
• Reworked documentation, docs theme.

0.2-alpha (2018-08-27)

• Added first indices.

0.1.0-dev (2018-08-23)

• First release on PyPI.