zampy

Tool for downloading Land Surface Model (LSM) input data.

Named after Zam; the Avestan language term for the Zoroastrian concept of "earth".

Outline

zampy is designed to retrieve data for LSM model input. It can help you prepare the data within the following steps:

1. Download the data for the specified location(s) / geographical area.
2. Ingest data into unified (zampy) format.
3. Load the variables in a standardized way (standardized names & standardized units).
4. Convert the data to standard formats:
   • ALMA / PLUMBER2's ALMA formatted netCDF.
   • CMOR formatted netCDF.

(Note: items in italic will not be worked on for now/low priority, but we want to allow space for these in the future.)

Getting start

Installation

To install the latest release of zampy, do:

python3 -m pip install zampy

To install the in-development version from the GitHub repository, do:

python3 -m pip install git+https://github.com/EcoExtreML/zampy.git

Configuration

Zampy needs to be configured with a simple configuration file.

You need to create this file under your user home directory:

~/.config/zampy/zampy_config.yml

The configuration file should contain the working_directory, for instance:

working_directory: /path_to_a_working_directory/  #for example: /home/bart/Zampy

If you need access to data on CDS or ADS server, you should add your CDS or ADS credentials to zampy_config.yml:

cdsapi:
  url:  # for example https://cds.climate.copernicus.eu/api/v2
  key:  # for example 12345:xhashd-232jcsha-dsaj429-cdjajd29319
adsapi:
  url:  # for example https://ads.atmosphere.copernicus.eu/api/v2
  key:  # for example 12345:xhashd-232jcsha-dsaj429-cdjajd29319

About how to create CDS or ADS credentials, check the section below.

How to use zampy

We recommend our users to use zampy with recipes.

A "recipe" is a file with yml extension, it defines:

• data downloading
  • time extent.
  • spatial location / bounding box.
  • datasets to be downloaded
    • variables within datasets
• data conversion
  • convert to desired conventions
  • output frequency
  • output resolution

A sample recipe can be found in the documentation.

When you have your reciped created and saved on your disk, you can execute your recipe by running the following code in your shell:

zampy /path_to_recipe/sample_recipe.yml

We also provide python API for you to intereact with zampy. You can find the example notebooks for each supported dataset here.

Instructions for CDS/ADS datasets

To download the following datasets, users need access to CDS/ADS via cdsapi/adsapi:

• CDS
  • ERA5
  • ERA5 land
  • LAI
  • land cover
• ADS
  • CAMS EGG4 (e.g. co2)

To generate these API keys, you need to be a registered user on CDS via the registration page, or on ADS via the registration page.

Before submitting any request with zampy, please put your cdsapi/adsapi credentials in zampy_config.yml. Here is a short instruction about how to find your CDS/ADS API key. You can skip the steps related to .cdsapirc and simply add the key to zampy_config.yml.

Agree to the Terms of Use on CDS/ADS

When downloading a dataset for the first time, it is necessary to agree to the Terms of Use of every datasets that you intend to download. This can only be done via the CDS/ADS website. When you try to download these datasets, you will be prompted to go to the terms of use and accept them.

Acknowledgements

This package was developed by the Netherlands eScience Center. Development was supported by the Netherlands eScience Center under grant number NLESC.ASDI.2020.026.