ecmwf / polytope-mars

High level interface to polytope for meteorological feature extraction using the MARS language

⚠️ This project is BETA and will be experimental for the foreseeable future. Interfaces and functionality are likely to change. DO NOT use this software in any project/software that is operational.

Polytope-mars

Concept • Installation • Example • Testing

Concept

Repository for high level API of polytope feature extraction such as vertical profile and time series.

Current features include:

• Time Series
• Vertical Profile
• Bounding Box
• Path
• WKT POLYGON shape
• Shape File
• Frame

Installation

pip install polytope-mars

Or clone the repo and install locally

git clone [email protected]:ecmwf/polytope-mars.git
cd polytope-mars

pip install -e .

Example

Create time series request: Create a request for a time series request using the time series feature, set options for use by polytope feature extraction. "grib" indicates the type of data in this case. NB: Assumes data is in a local FDB.

from polytope_mars.api import PolytopeMars

request = {
    "class": "od",
    "stream" : "enfo",
    "type" : "pf",
    "date" : "20231205",
    "time" : "00:00:00",
    "levtype" : "sfc",
    "expver" : "0001", 
    "domain" : "g",
    "param" : "228/49/164/165/166/167",
    "number" : "1/to/5",
    "step" : "0/1"
    "feature" : {
        "type" : "timeseries",
        "points" : [[51.5073219, 2.1]],
        "axis" : "step",
    },
}

result = PolytopeMars().extract(request)

If the user provides no arguments to PolytopeMars then a config is loaded from the default locations:

1. System-wide configuration in /etc/polytope_mars/config.json (and yaml)
2. User configuration in ~/.polytope_mars.json (and yaml)

The user can also pass in a config as a python dictionary to PolytopeMars for a custom config at runtime.

Result will be a coverageJSON file with the requested data if it is available, further manipulation of the coverage can be made using covjsonkit.

Config

An example config can be found here example_config.json. This can be edited to change any of the fields. The config is made up of three main components.

1. datacube: This option is used to set up what type of datacube is being used at the moment, currently only gribjump is supported.
2. options These are the options used by polytope for interpreting the data available.
3. coverageconfig These options are used by convjsonkit to parse the output of polytope into coverageJSON.