============
ecmwf_models
============
|ci| |cov| |pip| |doc|
.. |ci| image:: https://github.com/TUW-GEO/ecmwf_models/actions/workflows/ci.yml/badge.svg?branch=master
:target: https://github.com/TUW-GEO/ecmwf_models/actions
.. |cov| image:: https://coveralls.io/repos/TUW-GEO/ecmwf_models/badge.png?branch=master
:target: https://coveralls.io/r/TUW-GEO/ecmwf_models?branch=master
.. |pip| image:: https://badge.fury.io/py/ecmwf-models.svg
:target: https://badge.fury.io/py/ecmwf-models
.. |doc| image:: https://readthedocs.org/projects/ecmwf-models/badge/?version=latest
:target: https://ecmwf-models.readthedocs.io/en/latest/
Readers and converters for ECMWF reanalysis (`ERA5 <https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels>`_
and `ERA5-Land <https://cds.climate.copernicus.eu/datasets/reanalysis-era5-land>`_) data.
Written in Python.
Works great in combination with `pytesmo <https://github.com/TUW-GEO/pytesmo>`_.
Installation
============
Install required C-libraries via conda. For installation we recommend
`Miniconda <http://conda.pydata.org/miniconda.html>`_:
.. code::
conda install -c conda-forge pygrib netcdf4 pyresample pykdtree
Afterwards the following command will install all remaining python dependencies
as well as the ``ecmwf_models`` package itself.
.. code::
pip install ecmwf_models
Quickstart
==========
Download image data from CDS (`set up API <https://cds.climate.copernicus.eu/how-to-api>`_ first) using the ``era5 download`` and ``era5land download``
console command (see ``era5 download --help`` for all options) ...
.. code-block:: shell
era5land download /tmp/era5/img -s 2024-04-01 -e 2024-04-05 -v swvl1,swvl2 --h_steps 0,12
... and convert them to time series (ideally for a longer period). Check ``era5 reshuffle --help``
.. code-block:: shell
era5land reshuffle /tmp/era5/img /tmp/era5/ts -s 2024-04-01 -e 2024-04-05 --land_points True
Finally, in python, read the time series data for a location as a pandas
DataFrame.
.. code-block:: python
>> from ecmwf_models.interface import ERATs
>> ds = ERATs('/tmp/era5/ts')
>> ds.read(18, 48) # (lon, lat)
swvl1 swvl2
2024-04-01 00:00:00 0.318054 0.329590
2024-04-01 12:00:00 0.310715 0.325958
2024-04-02 00:00:00 0.360229 0.323502
... ... ...
2024-04-04 12:00:00 0.343353 0.348755
2024-04-05 00:00:00 0.350266 0.346558
2024-04-05 12:00:00 0.343994 0.344498
More programs are available to keep an exisiting image and time series record
up-to-date. Type ``era5 --help`` and ``era5land --help`` to see all available
programs.
CDS API Setup
=============
In order to download data from CDS, this package uses the CDS API
(https://pypi.org/project/cdsapi/). You can either pass your credentials
directly on the command line (which might be unsafe) or set up a
.cdsapirc file in your home directory (recommended).
Please see the description at https://cds.climate.copernicus.eu/how-to-api.
Supported Products
==================
At the moment this package supports
- **ERA5**
- **ERA5-Land**
reanalysis data in **grib** and **netcdf** format (download, reading, time
series creation) with a default spatial sampling of 0.25 degrees (ERA5),
and 0.1 degrees (ERA5-Land).
It should be easy to extend the package to support other ECMWF reanalysis
products. This will be done as need arises.
Docker image
============
We provide a docker image for this package. This contains all
pre-installed dependencies and can simply be pulled via
.. code-block:: shell
$ docker pull ghcr.io/tuw-geo/ecmwf_models:latest
Alternatively, to build the image locally using the provided Dockerfile, call
from the package root
.. code-block:: shell
$ docker buildx build -t ecmwf_models:latest . 2>&1 | tee docker_build.log
Afterwards, you can execute the ``era5`` and ``era5land`` commands directly in
the container (after mounting some volumes to write data to).
The easiest way to set the API credentials in this case is via the
``CDSAPI_KEY`` container variable or the ``--cds_token`` option as below.
.. code-block:: shell
$ docker run -v /data/era5/img:/container/path ecmwf_models:latest bash -c \
'era5land update_img /container/path --cds_token xxxx-xxx-xxx-xx-xxxx'
You can use this together with a task scheduler to regularly pull new data.
Citation
========
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.593533.svg
:target: https://doi.org/10.5281/zenodo.593533
If you use the software in a publication then please cite it using the Zenodo DOI.
Be aware that this badge links to the latest package version.
Contribute
==========
We are happy if you want to contribute. Please raise an issue explaining what
is missing or if you find a bug.
Please take a look at the `developers guide <https://github.com/TUW-GEO/ecmwf_models/blob/master/CONTRIBUTING.rst>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/TUW-GEO/ecmwf_models/",
"name": "ecmwf-models",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "TU Wien",
"author_email": "support@qa4sm.eu",
"download_url": "https://files.pythonhosted.org/packages/f3/51/cd92a7c93ac65996c180b4a2141be6527daf5ac6b9959b16f362b666bd73/ecmwf_models-0.10.2.tar.gz",
"platform": "any",
"description": "============\r\necmwf_models\r\n============\r\n\r\n|ci| |cov| |pip| |doc|\r\n\r\n.. |ci| image:: https://github.com/TUW-GEO/ecmwf_models/actions/workflows/ci.yml/badge.svg?branch=master\r\n :target: https://github.com/TUW-GEO/ecmwf_models/actions\r\n\r\n.. |cov| image:: https://coveralls.io/repos/TUW-GEO/ecmwf_models/badge.png?branch=master\r\n :target: https://coveralls.io/r/TUW-GEO/ecmwf_models?branch=master\r\n\r\n.. |pip| image:: https://badge.fury.io/py/ecmwf-models.svg\r\n :target: https://badge.fury.io/py/ecmwf-models\r\n\r\n.. |doc| image:: https://readthedocs.org/projects/ecmwf-models/badge/?version=latest\r\n :target: https://ecmwf-models.readthedocs.io/en/latest/\r\n\r\n\r\nReaders and converters for ECMWF reanalysis (`ERA5 <https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels>`_\r\nand `ERA5-Land <https://cds.climate.copernicus.eu/datasets/reanalysis-era5-land>`_) data.\r\nWritten in Python.\r\n\r\nWorks great in combination with `pytesmo <https://github.com/TUW-GEO/pytesmo>`_.\r\n\r\n\r\nInstallation\r\n============\r\n\r\nInstall required C-libraries via conda. For installation we recommend\r\n`Miniconda <http://conda.pydata.org/miniconda.html>`_:\r\n\r\n.. code::\r\n\r\n conda install -c conda-forge pygrib netcdf4 pyresample pykdtree\r\n\r\nAfterwards the following command will install all remaining python dependencies\r\nas well as the ``ecmwf_models`` package itself.\r\n\r\n.. code::\r\n\r\n pip install ecmwf_models\r\n\r\nQuickstart\r\n==========\r\n\r\nDownload image data from CDS (`set up API <https://cds.climate.copernicus.eu/how-to-api>`_ first) using the ``era5 download`` and ``era5land download``\r\nconsole command (see ``era5 download --help`` for all options) ...\r\n\r\n.. code-block:: shell\r\n\r\n era5land download /tmp/era5/img -s 2024-04-01 -e 2024-04-05 -v swvl1,swvl2 --h_steps 0,12\r\n\r\n... and convert them to time series (ideally for a longer period). Check ``era5 reshuffle --help``\r\n\r\n.. code-block:: shell\r\n\r\n era5land reshuffle /tmp/era5/img /tmp/era5/ts -s 2024-04-01 -e 2024-04-05 --land_points True\r\n\r\nFinally, in python, read the time series data for a location as a pandas\r\nDataFrame.\r\n\r\n.. code-block:: python\r\n\r\n >> from ecmwf_models.interface import ERATs\r\n >> ds = ERATs('/tmp/era5/ts')\r\n >> ds.read(18, 48) # (lon, lat)\r\n\r\n swvl1 swvl2\r\n 2024-04-01 00:00:00 0.318054 0.329590\r\n 2024-04-01 12:00:00 0.310715 0.325958\r\n 2024-04-02 00:00:00 0.360229 0.323502\r\n ... ... ...\r\n 2024-04-04 12:00:00 0.343353 0.348755\r\n 2024-04-05 00:00:00 0.350266 0.346558\r\n 2024-04-05 12:00:00 0.343994 0.344498\r\n\r\nMore programs are available to keep an exisiting image and time series record\r\nup-to-date. Type ``era5 --help`` and ``era5land --help`` to see all available\r\nprograms.\r\n\r\nCDS API Setup\r\n=============\r\n\r\nIn order to download data from CDS, this package uses the CDS API\r\n(https://pypi.org/project/cdsapi/). You can either pass your credentials\r\ndirectly on the command line (which might be unsafe) or set up a\r\n.cdsapirc file in your home directory (recommended).\r\nPlease see the description at https://cds.climate.copernicus.eu/how-to-api.\r\n\r\nSupported Products\r\n==================\r\n\r\nAt the moment this package supports\r\n\r\n- **ERA5**\r\n- **ERA5-Land**\r\n\r\nreanalysis data in **grib** and **netcdf** format (download, reading, time\r\nseries creation) with a default spatial sampling of 0.25 degrees (ERA5),\r\nand 0.1 degrees (ERA5-Land).\r\nIt should be easy to extend the package to support other ECMWF reanalysis\r\nproducts. This will be done as need arises.\r\n\r\nDocker image\r\n============\r\n\r\nWe provide a docker image for this package. This contains all\r\npre-installed dependencies and can simply be pulled via\r\n\r\n.. code-block:: shell\r\n\r\n $ docker pull ghcr.io/tuw-geo/ecmwf_models:latest\r\n\r\nAlternatively, to build the image locally using the provided Dockerfile, call\r\nfrom the package root\r\n\r\n.. code-block:: shell\r\n\r\n $ docker buildx build -t ecmwf_models:latest . 2>&1 | tee docker_build.log\r\n\r\nAfterwards, you can execute the ``era5`` and ``era5land`` commands directly in\r\nthe container (after mounting some volumes to write data to).\r\nThe easiest way to set the API credentials in this case is via the\r\n``CDSAPI_KEY`` container variable or the ``--cds_token`` option as below.\r\n\r\n.. code-block:: shell\r\n\r\n $ docker run -v /data/era5/img:/container/path ecmwf_models:latest bash -c \\\r\n 'era5land update_img /container/path --cds_token xxxx-xxx-xxx-xx-xxxx'\r\n\r\nYou can use this together with a task scheduler to regularly pull new data.\r\n\r\nCitation\r\n========\r\n\r\n.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.593533.svg\r\n :target: https://doi.org/10.5281/zenodo.593533\r\n\r\nIf you use the software in a publication then please cite it using the Zenodo DOI.\r\nBe aware that this badge links to the latest package version.\r\n\r\nContribute\r\n==========\r\n\r\nWe are happy if you want to contribute. Please raise an issue explaining what\r\nis missing or if you find a bug.\r\nPlease take a look at the `developers guide <https://github.com/TUW-GEO/ecmwf_models/blob/master/CONTRIBUTING.rst>`_.\r\n",
"bugtrack_url": null,
"license": "mit",
"summary": "Downloading, reading and TS conversion of ECMWF reanalysis data",
"version": "0.10.2",
"project_urls": {
"Documentation": "https://ecmwf-models.readthedocs.io/en/latest/",
"Homepage": "https://github.com/TUW-GEO/ecmwf_models/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2530ae7309fdebba79b190811815684d179281d272207313a29af390a33d9d1a",
"md5": "65f9b2f75d71adeaeff63a6805735681",
"sha256": "f02d9a3919ce921cc945aa9bafed44903b24d5cce832ecb9a3e15bc3d3ec66ae"
},
"downloads": -1,
"filename": "ecmwf_models-0.10.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "65f9b2f75d71adeaeff63a6805735681",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 208001,
"upload_time": "2024-11-06T14:01:09",
"upload_time_iso_8601": "2024-11-06T14:01:09.067049Z",
"url": "https://files.pythonhosted.org/packages/25/30/ae7309fdebba79b190811815684d179281d272207313a29af390a33d9d1a/ecmwf_models-0.10.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f351cd92a7c93ac65996c180b4a2141be6527daf5ac6b9959b16f362b666bd73",
"md5": "d06da685b53704297a3f6e07a98a76ea",
"sha256": "97d814d97940d40ea93fa88047d121f3c1e4124f31c6b373a76d22089b06721b"
},
"downloads": -1,
"filename": "ecmwf_models-0.10.2.tar.gz",
"has_sig": false,
"md5_digest": "d06da685b53704297a3f6e07a98a76ea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 989969,
"upload_time": "2024-11-06T14:01:10",
"upload_time_iso_8601": "2024-11-06T14:01:10.355306Z",
"url": "https://files.pythonhosted.org/packages/f3/51/cd92a7c93ac65996c180b4a2141be6527daf5ac6b9959b16f362b666bd73/ecmwf_models-0.10.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-06 14:01:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TUW-GEO",
"github_project": "ecmwf_models",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "ecmwf-models"
}
JSON
