ecmwf-models


Nameecmwf-models JSON
Version 0.10.2 PyPI version JSON
download
home_pagehttps://github.com/TUW-GEO/ecmwf_models/
SummaryDownloading, reading and TS conversion of ECMWF reanalysis data
upload_time2024-11-06 14:01:10
maintainerNone
docs_urlNone
authorTU Wien
requires_python>=3.6
licensemit
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage
            ============
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"
}
        
Elapsed time: 1.19604s