### Install Polytope from PyPI with pip (Bash)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Algorithm/User_Guide/Getting_started.md

This command installs the stable version of the Polytope Python library from the Python Package Index (PyPI). It uses `pip` and requires Python 3 installed and accessible via `python3`. This is the recommended method for installing released versions of the library.

```bash
python3 -m pip install polytope-python
```

--------------------------------

### Install Polytope from Git with pip (Bash)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Algorithm/User_Guide/Getting_started.md

This command installs the Polytope Python library directly from the 'develop' branch of the official GitHub repository. It uses `pip` and requires Python 3 installed and accessible via `python3`. This method installs the latest development code rather than a stable release version.

```bash
python3 -m pip install git+ssh://git@github.com/ecmwf/polytope.git@develop
```

--------------------------------

### Install Polytope Package via Pip (Shell)

Source: https://github.com/ecmwf/polytope/blob/develop/CONTRIBUTING.rst

This command uses the pip package installer to download and install the `polytope-python` library from the Python Package Index (PyPI). It is a necessary prerequisite for developing with or using the polytope library in Python.

```sh
$ pip install polytope-python
```

--------------------------------

### Installing earthkit-data with Polytope Feature (Shell)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Installation.md

Installs the earthkit-data Python package using pip, including the 'polytope' extra dependency group which is necessary to interact with the Polytope service. This provides a minimal installation required for Polytope access. Requires Python 3.10+ and pip.

```Shell
python3 -m pip install earthkit-data[polytope]
```

--------------------------------

### Installing earthkit-data with All Features (Shell)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Installation.md

Installs the earthkit-data Python package using pip, including all available extra dependency groups. This provides the most comprehensive installation, supporting the widest range of data types and remote services offered by the library. Requires Python 3.10+ and pip.

```Shell
python3 -m pip install earthkit-data[all]
```

--------------------------------

### Creating Conda Environment for earthkit (Shell)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Installation.md

Provides a sequence of shell commands using the conda package manager to create a dedicated Python 3.10 environment named 'earthkit', activate it, install earthkit-data with the polytope feature, and install/register an ipykernel for use with Jupyter notebooks. This sets up an isolated and recommended environment for the installation. Requires Conda to be installed.

```Shell
envname=earthkit
conda create -n $envname -c conda-forge -y python=3.10
conda activate $envname

python3 -m pip install earthkit-data[polytope]

# To allow easy use with a jupyter notebook run the following
python3 -m pip install ipykernel
python3 -m ipykernel install --user --name=$envname
```

--------------------------------

### Installing earthkit-plots Library (Shell)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Installation.md

Installs the earthkit-plots Python package using pip, which is required to use any visualization features provided by the earthkit ecosystem. This is an optional installation separate from earthkit-data itself. Requires Python 3.10+ and pip.

```Shell
python3 -m pip install earthkit-plots
```

--------------------------------

### Loading XArray Dataset from GRIB File - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Algorithm/User_Guide/Example.md

This snippet loads a GRIB file named "winds.grib" into an XArray dataset using the cfgrib engine. It prepares the data source that will be used as the datacube for Polytope operations. Requires the xarray and cfgrib libraries.

```python
import xarray as xr

array = xr.open_dataset("winds.grib", engine="cfgrib")
```

--------------------------------

### Initializing Polytope Object with Options - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Algorithm/User_Guide/Example.md

This code initializes an instance of the Polytope class, passing the loaded XArray dataset as the datacube. It also includes an options dictionary to specify metadata for axes, such as declaring the 'longitude' axis as cyclic. Requires the polytope library.

```python
options = {"longitude": {"Cyclic": [0, 360.0]}}

from polytope.polytope import Polytope

p = Polytope(datacube=array, options=options)
```

--------------------------------

### Installing earthkit-data with Covjson Feature (Shell)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Installation.md

Installs the earthkit-data Python package using pip, including the 'covjsonkit' extra dependency group to enable functionality related to coverage JSON data. This is an optional feature not strictly required for basic Polytope access but useful for handling specific data formats. Requires Python 3.10+ and pip.

```Shell
python3 -m pip install earthkit-data[covjsonkit]
```

--------------------------------

### Fetching Trajectory Data with earthkit.data in Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_trajectory_example.ipynb

This snippet demonstrates how to construct a data request dictionary, including a specific 'trajectory' feature with defined points, inflation parameters, and axis names. It then uses `earthkit.data.from_source` to retrieve the dataset from the specified 'polytope' source and address.

```python
import numpy as np

n = 10
lons = np.linspace(0, 5*360, n)
lats = np.linspace(-85, 85, n)
linspace = np.stack([lats, lons], axis=1)
pts = linspace.tolist()

import earthkit.data

request = {
    "class": "ai",
    "stream" : "oper",
    "type" : "fc",
    "date" : -1,
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0001", 
    "model": "aifs-single",
    "domain" : "g",
    "param" : "166/167/169",
    "step" : "0",
    "feature" :{
        "type" : "trajectory", 
        "points" : [[0,0],[10,10],[20,20], [30,30], [30, 50], [50, 10]],#pts, 
        "inflation" : 0.5, 
        "inflate" : "round",
        "axes" :["latitude", "longitude"], 
    },
}

ds = earthkit.data.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int')
```

--------------------------------

### Retrieving Weather Data for Countries using Polytope and earthkit-geo (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/country_example.ipynb

This snippet demonstrates how to retrieve weather data constrained by the geographical shapes of specified countries. It uses `earthkit.geo.cartography` to get the polygon coordinates for the countries and constructs a Polytope request dictionary including the geographic 'feature'. The data is then fetched from the 'ecmwf-mars' collection via the 'polytope.ecmwf.int' service using `earthkit.data.from_source`.

```python
import earthkit
import earthkit.plots
import earthkit.geo.cartography

countries = ["France", "Italy", "Spain"] # List of countries

shapes = earthkit.geo.cartography.country_polygons(countries, resolution=50e6)

request = { "class": "od", "stream" : "oper", "type" : "fc", "levtype" : "sfc",
    "date" : 0,
    "time" : 0,
    "expver" : 1,
    "param" : [ 167 ],
    "step": 0,
    "feature": {
        "type": "polygon",
        "shape": shapes,
    },
}

ds = earthkit.data.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int')
```

--------------------------------

### Defining Polytope API Configuration File (JSON)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Installation.md

Shows the required JSON structure for the ~/.polytopeapirc configuration file used by earthkit-data to authenticate with the Polytope service. It requires two key-value pairs: "user_email" for the ECMWF account email and "user_key" for the corresponding API key. This file enables automatic authentication.

```JSON
{
    "user_email" : "<user_email>",
    "user_key" : "<user_key>"
}
```

--------------------------------

### Requesting ECMWF Data with Bounding Box (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_boundingbox_example.ipynb

Defines a request dictionary for fetching ECMWF AI/IFS operational forecast data for specific parameters ('166/167/169') at step 0 and surface level, restricted to a geographic bounding box defined by two points. It then uses `earthkit.data.from_source` with the "polytope" and "ecmwf-mars" sources and the specified address to retrieve this data into a `FieldList` object.

```python
import earthkit.data

request = {
    "class": "ai",
    "stream" : "oper",
    "type" : "fc",
    "date" : -1,
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0001", 
    "model": "aifs-single",
    "domain" : "g",
    "param" : "166/167/169",
    "step" : "0",
    "feature" : {
        "type" : "boundingbox",
        "points" : [[53.55, 2.76], [50.66, 7.86]],
	},
}


ds = earthkit.data.from_source(
    "polytope",
    "ecmwf-mars",
    request,
    stream=False,
    address='polytope.ecmwf.int',
)
```

--------------------------------

### Converting earthkit-data to xarray - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Quick_Start.md

This snippet shows how to convert an `earthkit-data` Dataset object into an `xarray.Dataset`. This conversion is a common step to leverage the extensive capabilities of the xarray library for data analysis and manipulation within the scientific Python ecosystem.

```python
ds.to_xarray()
```

--------------------------------

### Executing Data Extraction Request - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Algorithm/User_Guide/Example.md

This snippet calls the retrieve method on the initialized Polytope object (p), passing the constructed Request object. This performs the actual extraction of data points from the datacube according to the request definition. The result is an IndexTree representing the hierarchical structure of the extracted data indices.

```python
result = p.retrieve(request)
```

--------------------------------

### Constructing Polytope Request Object - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Algorithm/User_Guide/Example.md

This code combines the previously defined Box and Select shapes into a single Request object. This object encapsulates the query defining which data points should be extracted from the datacube by the Polytope instance. Requires the polytope library.

```python
from polytope.polytope import Request

request = Request(box, step_point)
```

--------------------------------

### Visualizing Timeseries Data as a Line Chart with earthkit.plots

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_timeseries_example.ipynb

This snippet demonstrates how to use `earthkit.plots` to visualize the retrieved timeseries data. It initializes a `Chart` object, sets a title using the helper function, adds a line series using the dataset `ds`, and displays the chart, explicitly setting the renderer to 'png' for static output.

```python
from earthkit.plots.interactive import Chart

TIME_FREQUENCY = "6h"
QUANTILES = [0, 0.1, 0.25, 0.5, 0.75, 0.9, 1]

chart = Chart()
chart.title(f"ECMWF ensemble meteogram at {location_to_string(LOCATION)}")
#chart.box(ds, time_frequency=TIME_FREQUENCY, quantiles=QUANTILES)
chart.line(ds, line_color='grey', time_frequency=TIME_FREQUENCY)
chart.show(renderer="png")  # Replace with chart.show() in an interactive session!
```

--------------------------------

### Converting earthkit.data Dataset to Xarray DataArray

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_timeseries_example.ipynb

This snippet shows a simple conversion of the data structure obtained from `earthkit.data` (a `Dataset`) into an Xarray `DataArray`. This allows for seamless integration with the broader Xarray ecosystem for data analysis and manipulation.

```python
da = ds.to_xarray()
print(da)
```

--------------------------------

### Visualizing Time-Series Data (Meteogram) - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Quick_Start.md

This snippet utilizes `earthkit-plots` to create a meteogram visualization from the retrieved time-series data (`ds`). It initializes a Chart object, sets a title, adds a box plot layer representing quantiles over time, adds a line layer for the mean, and renders the plot as a PNG image. Requires `earthkit-plots` and the dataset object.

```python
from earthkit.plots.interactive import Chart

TIME_FREQUENCY = "6h"
QUANTILES = [0, 0.1, 0.25, 0.5, 0.75, 0.9, 1]

chart = Chart()
chart.title(f"ECMWF ensemble meteogram")
chart.box(ds, time_frequency=TIME_FREQUENCY, quantiles=QUANTILES)
chart.line(ds,aggregation='mean', line_color='grey', time_frequency=TIME_FREQUENCY)
chart.show(renderer="png")  # Replace with chart.show() in an interactive session!
```

--------------------------------

### Retrieving Vertical Profile Data (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/vertical_profile_example.ipynb

This snippet retrieves a vertical profile of meteorological data using `earthkit.data` and the ECMWF Polytope service. It constructs a dictionary specifying the MARS request parameters, including date, time, levtype, experiment version, domain, parameters (`Temperature/Specific Humidity`), number, step, level list, and the specific point for the vertical profile. The `from_source` function initiates the data retrieval.

```python
import earthkit.data

request = {
    "class": "od",
    "stream": "enfo",
    "type": "pf",
    "date": -1,  # Note: date must be within the last two days 
    "time": "0000",
    "levtype": "pl",
    "expver": "0001",
    "domain": "g",
    "param": "203/133",
    "number": "1",
    "step": "0",
    "levelist": "1/to/1000",
    "feature": {
        "type": "verticalprofile",
        "points": [[38.9, -9.1]],
    },
}

ds = earthkit.data.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int')
```

--------------------------------

### Visualizing xarray Data with earthkit.plots (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_boundingbox_example.ipynb

Demonstrates how to visualize the `xarray` DataArray (`da`) using `earthkit.plots`. It initializes a `Map` plot centered on Europe, plots the data variable '2t' (2 metre temperature) as a point cloud, adds map elements like coastlines, borders, and gridlines, sets a dynamic title, and displays the plot.

```python
da = ds.to_xarray()
import earthkit.plots
chart = earthkit.plots.Map(domain="Europe")
chart.point_cloud(da['2t'], x="y", y="x")

chart.coastlines()
chart.borders()
chart.gridlines()

chart.title("{variable_name} (number={number})")

chart.legend()

chart.show()
```

--------------------------------

### Pretty Printing IndexTree Result - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Algorithm/User_Guide/Example.md

This snippet calls the pprint method on the IndexTree object obtained from the retrieval step. This method prints a formatted, human-readable representation of the IndexTree structure, showing the hierarchical organization of the extracted data indices.

```python
result.pprint()
```

--------------------------------

### Converting earthkit.data to xarray (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/country_example.ipynb

This simple snippet shows how to convert the data object obtained from earthkit.data into an xarray Dataset using the `.to_xarray()` method. This conversion makes it easier to work with the data using standard xarray functionalities and plotting libraries.

```python
xa = ds.to_xarray()
xa
```

--------------------------------

### Displaying Retrieved CovJSON Data - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Quick_Start.md

This snippet demonstrates how to view the raw CovJSON representation of the data retrieved by `earthkit-data`. Calling the internal `_json()` method on the dataset object (`ds`) prints the underlying data structure, which can be useful for inspection and debugging.

```python
ds._json()
```

--------------------------------

### Visualizing Weather Data using earthkit.plots (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/country_example.ipynb

This snippet demonstrates how to visualize the temperature data from the xarray dataset (`xa['2t']`). It creates a map centered on the specified countries using `earthkit.plots.Map`, plots the temperature data as a point cloud, and adds geographical features like coastlines, borders, and gridlines for context.

```python
chart = earthkit.plots.Map(domain=countries)
chart.point_cloud(xa['2t'], x="y", y="x")
chart.coastlines()
chart.borders()
chart.gridlines()
chart.legend()
chart.show()
```

--------------------------------

### Requesting Box-Inflated Trajectory Data with earthkit.data (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Features/trajectory.md

This Python snippet provides another example of an earthkit-data request dictionary for fetching trajectory data via the 'polytope' service. It shows how to define the 'inflation' field as a list for per-axis inflation and specifies the 'inflate' shape as 'box', resulting in a box swept along the trajectory instead of the default circle/sphere. Dependencies: `earthkit.data` library (implied context). Parameters: `request` dictionary similar to the basic example, but with `inflation` as a list `[0.1, 0.2]` and the addition of `"inflate": 'box'` within the `feature` dictionary.

```python
request = {
    "class": "od",
    "stream" : "enfo",
    "type" : "pf",
    "date" : -1,
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0001", 
    "domain" : "g",
    "param" : "164/166/167",
    "number" : "1",
    "step": "0",
    "feature" : {
        "type" : "trajectory",
        "points" : [[-0.1, -0.1], [0, 0], [0.1, 0.1]],
        "inflation" : [0.1, 0.2],
        "inflate" : 'box',
        "axes" :["latitude", "longitude"],
	},
}
```

--------------------------------

### Converting Dataset to Xarray (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/vertical_profile_example.ipynb

This snippet converts the retrieved `earthkit.data` dataset (`ds`) into an Xarray DataArray (`da`) using the `to_xarray()` method. It then prints the resulting DataArray to the console, showing its structure and content. This conversion is useful for integrating the data with the broader Xarray ecosystem for further analysis and manipulation.

```python
da = ds.to_xarray()
print(da)
```

--------------------------------

### Valid Polytope-MARS Request (Range via Feature) (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Design_doc.md

Presents another valid example of a Polytope-MARS request dictionary, illustrating how a dimension like `step` can be defined using the `range` dictionary *within* the `feature` object instead of the top-level `step` key. This structure is valid as long as the top-level `step` key is *not* also present in the request. The `range` specifies the start and end values for the implicit `step` axis.

```Python
request = {
    "class": "od",
    "stream" : "enfo",
    "type" : "pf",
    "date" : "20241006",
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0079", 
    "domain" : "g",
    "param" : "164/167/169",
    "number" : "1/to/50",
    "feature" : {
        "type" : "timeseries",
        "points": [[-9.10, 38.78]],
        "axis": "step",
        "range" : {
            "start" : 0,
            "end" : 360,
        }
    },
}
```

--------------------------------

### Visualizing Vertical Profile Data (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/vertical_profile_example.ipynb

This snippet visualizes the retrieved vertical profile data as a line chart using `earthkit.plots.interactive`. It creates a `Chart` object, adds a line plot using the retrieved dataset, sets the y-axis titles to "hPa", and shows the chart, specifically rendering it as a PNG image for broad compatibility as noted in the surrounding text. Users can remove `renderer="png"` for interactive plots.

```python
from earthkit.plots.interactive import Chart

chart = Chart()
chart.line(ds, y="z")
chart.fig.update_layout(yaxis1={"title": "hPa"})
chart.fig.update_layout(yaxis2={"title": "hPa"})
chart.show(renderer="png")  # Replace with chart.show() in an interactive session!
```

--------------------------------

### Converting earthkit.data Dataset to xarray in Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_trajectory_example.ipynb

This snippet shows how to easily convert an `earthkit.data` Dataset object (`ds`), obtained from fetching data, into an `xarray` DataArray (`da`). This conversion allows leveraging xarray's capabilities for data manipulation and analysis.

```python
da = ds.to_xarray()
da
```

--------------------------------

### Formatting Location Coordinates in Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_timeseries_example.ipynb

This Python function converts a latitude and longitude coordinate pair into a human-readable string format. It includes the degree symbol and cardinal directions (N/S/E/W) for clarity.

```python
def location_to_string(location):
    """
    Converts latitude and longitude to a string representation with degrees
    and N/S/E/W.
    """
    (lat, lon) = location[0]
    lat_dir = "N" if lat >= 0 else "S"
    lon_dir = "E" if lon >= 0 else "W"
    return f"{abs(lat):.2f}°{lat_dir}, {abs(lon):.2f}°{lon_dir}"
```

--------------------------------

### Visualizing Data on Map using Earthkit Plots Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_polygon_example.ipynb

This snippet uses `earthkit.plots` to create a map visualization of the data stored in the `xarray.DataArray` (`da`). It configures the map domain to "Portugal", adds the '2t' variable (likely 2-meter temperature) as a point cloud, overlays geographical features like coastlines, borders, and gridlines, sets a dynamic title based on variable attributes, and displays a legend before showing the final chart.

```python
da = ds.to_xarray()
import earthkit.plots
chart = earthkit.plots.Map(domain="Portugal")
chart.point_cloud(da['2t'], x="y", y="x")

chart.coastlines()
chart.borders()
chart.gridlines()

chart.title("{variable_name} (number={number})")

chart.legend()

chart.show()
```

--------------------------------

### Requesting ECMWF MARS Data via Polytope - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Quick_Start.md

This snippet defines a dictionary containing the parameters for a MARS data request, specifically targeting a time-series from the ensemble forecast stream ('enfo') via the Polytope service. It then uses `earthkit.data.from_source` to execute this request, specifying 'polytope' as the service, 'ecmwf-mars' as the dataset, and providing the Polytope server address. The `stream=False` parameter ensures the call waits for all data to be retrieved.

```python
import earthkit.data

request = {
    "class": "od",
    "stream" : "enfo",
    "type" : "pf",
    "date" : -1,  # Note: date must be within the last two days
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0001", 
    "domain" : "g",
    "param" : "164/167/169",
    "number" : "1/to/50",
    "feature" : {
        "type" : "timeseries",
        "points": [[-9.10, 38.78]],
        "axes": "step",
        "range" : {
            "start" : 0,
            "end" : 360,
        }
    },
    "format": "covjson",
}

ds = earthkit.data.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int')
```

--------------------------------

### Retrieving Vertical Profile Data with earthkit-data

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_vertical_profile_example.ipynb

This snippet defines a MARS-like request dictionary to fetch a vertical profile of temperature (param 130) from the ECMWF Open Data (aifs-single model) at a specified geographical point. It then uses `earthkit.data.from_source` with the 'polytope' source to retrieve the data based on this request.

Dependencies: `earthkit.data`

Key Parameters:
- `request`: A dictionary specifying the data parameters and the 'verticalprofile' feature.
- `stream`: Set to `False` to avoid streaming.
- `address`: Specifies the polytope server address.

Output: An `earthkit.data.dataset.Dataset` object containing the retrieved data.

```python
import earthkit.data

request = {
    "class": "ai",
    "stream" : "oper",
    "type" : "fc",
    "date" : -1,
    "time" : "0000",
    "levtype" : "pl",
    "expver" : "0001", 
    "model": "aifs-single",
    "domain" : "g",
    "param" : "130",
    "step" : "0",
    "levelist" : "0/to/1000",
    "feature": {
        "type": "verticalprofile",
        "points": [[38.9, -9.1]],
    },
}

ds = earthkit.data.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int')
```

--------------------------------

### Converting earthkit.data FieldList to xarray (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_boundingbox_example.ipynb

Takes the `FieldList` object (`ds`) obtained from the previous data request and converts it into an `xarray` DataArray object (`da`). This conversion makes the data compatible with the `xarray` ecosystem for further analysis or visualization, providing a structured, multi-dimensional array format.

```python
da = ds.to_xarray()
da
```

--------------------------------

### Visualizing Data on a Map with earthkit.plots in Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_trajectory_example.ipynb

This snippet demonstrates how to use the `earthkit.plots` library to visualize meteorological data from an xarray DataArray (`da`) on a map. It configures the map to display the data as a point cloud, adds geographical context like coastlines and borders, includes a title and legend, and displays the final plot.

```python
import earthkit.plots

chart = earthkit.plots.Map()
chart.point_cloud(da['2t'], x="y", y="x")
chart.coastlines()
chart.borders()
chart.title("{variable_name}")
chart.legend()
chart.show()
```

--------------------------------

### Fetching Data using Polytope and Earthkit-Geo (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_country_example.ipynb

Imports necessary `earthkit` modules. Defines a list of countries and uses `earthkit.geo.cartography` to get their polygon shapes. Constructs a dictionary for a data request compatible with the Polytope source in `earthkit`, specifying parameters like class, stream, type, date, time, model, parameters, step, and a polygon feature based on the country shapes. Fetches the data using `earthkit.data.from_source` with the "polytope" source, "ecmwf-mars" collection, the defined request, and specifies the endpoint. This requires `earthkit`, `earthkit.geo`, and access to the specified Polytope endpoint. The output is an `earthkit.data` dataset object.

```python
import earthkit
import earthkit.plots
import earthkit.geo.cartography

countries = ["France", "Italy", "Spain"] # List of countries

shapes = earthkit.geo.cartography.country_polygons(countries, resolution=50e6)

request = {     
    "class": "ai",
    "stream" : "oper",
    "type" : "fc",
    "date" : -1,
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0001", 
    "model": "aifs-single",
    "domain" : "g",
    "param" : "166/167/169",
    "step" : "0",
    "feature": {
        "type": "polygon",
        "shape": shapes,
    },
}

ds = earthkit.data.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int')
```

--------------------------------

### Converting earthkit-data Dataset to Xarray

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_vertical_profile_example.ipynb

This snippet shows how to convert the `earthkit.data.dataset.Dataset` object, which holds the vertical profile data, into an Xarray DataArray. This conversion is useful for further data analysis and manipulation using the Xarray library. The resulting DataArray is then printed to the console.

Dependencies: `earthkit.data`, `xarray` (implicitly required by `to_xarray` method).

Input: An `earthkit.data.dataset.Dataset` object (`ds`).

Output: An Xarray DataArray printed to standard output.

```python
da = ds.to_xarray()
print(da)
```

--------------------------------

### Converting Earthkit Dataset to Xarray DataArray Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_polygon_example.ipynb

This snippet converts an `earthkit.data` dataset object (`ds`) into an `xarray.DataArray` (`da`). This is a common step to leverage the data manipulation and analysis capabilities of the `xarray` library. The original dataset `ds` is expected to contain the meteorological data retrieved in the previous step.

```python
da = ds.to_xarray()
da
```

--------------------------------

### Defining Data Request Shapes (Box, Select) - Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Algorithm/User_Guide/Example.md

This snippet defines geometric shapes used to specify the region of interest within the datacube. A Box shape is created for latitude and longitude to define a 2D rectangle, and a Select shape is used to pick a specific time step (0). Requires the numpy and polytope.shapes libraries.

```python
import numpy as np
from polytope.shapes import Box, Select

box = Box(["latitude", "longitude"], [0, 0], [1, 1])
step_point = Select("step", [np.timedelta64(0, "s")])
```

--------------------------------

### Retrieving Timeseries Data from ECMWF MARS using earthkit.data

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_timeseries_example.ipynb

This snippet demonstrates how to define a MARS request dictionary for a weather timeseries at a specific location and use `earthkit.data.from_source` with the 'polytope' source to retrieve the data from the ECMWF archive. It sets parameters like class, stream, type, date, time, levtype, model, and defines the 'feature' for timeseries extraction.

```python
import earthkit.data

LOCATION = [[-9.11, 38.79]]

request = {
    "class": "ai",
    "stream" : "oper",
    "type" : "fc",
    "date" : -1,
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0001", 
    "model": "aifs-single",
    "domain" : "g",
    "param" : "166/167/169", 
    "feature" : {
        "type" : "timeseries",
        "points": [[-9.10, 38.78], [1.10, 2.78]],
        "axes": "step",
        "range": {"start": 0, "end": 360}
    },
}

ds = earthkit.data.from_source(
    "polytope",
    "ecmwf-mars",
    request,
    stream=False,
    address='polytope.ecmwf.int',
)
```

--------------------------------

### Visualizing Vertical Profile with earthkit-plots

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_vertical_profile_example.ipynb

This snippet demonstrates how to plot the retrieved vertical profile data using `earthkit.plots.interactive.Chart`. It creates a line plot using the dataset `ds` with 'level' on the y-axis and updates the y-axis titles for clarity. The plot is then displayed as a PNG image.

Dependencies: `earthkit.plots`

Key Parameters:
- `ds`: The `earthkit.data.dataset.Dataset` containing the profile data.
- `y`: Specifies the variable to use for the y-axis ('level').
- `renderer`: Controls the output format ('png' for static image).

Output: A static PNG image of the vertical profile plot.

```python
from earthkit.plots.interactive import Chart

chart = Chart()
chart.line(ds, y="level")
chart.fig.update_layout(yaxis1={"title": "hPa"})
chart.fig.update_layout(yaxis2={"title": "hPa"})
chart.show(renderer="png")  # Replace with chart.show() in an interactive session!
```

--------------------------------

### Creating a PathSegment shape (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Algorithm/Developer_Guide/shapes.md

Demonstrates creating a PathSegment shape, defined by sweeping another shape along a straight line segment. It requires the axes along which to sweep, the shape to be swept, and the start and end points of the segment as input. The swept shape's axes must match the PathSegment's axes.

```python
box = Box(["latitude", "longitude"], [5, 5], [10, 15])
PathSegment(["latitude", "longitude"], box, [0, 0], [3, 7])
```

--------------------------------

### Retrieving Polytope Data with Polygon Filter using Earthkit Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/OpenData/od_polygon_example.ipynb

This snippet demonstrates how to use `earthkit.data` to request data from the "polytope" source, specifically filtering the request by a complex polygon shape defined by a list of latitude/longitude pairs. It sets various MARS parameters like `class`, `stream`, `type`, `date`, `time`, `levtype`, `expver`, `model`, `domain`, and `param`. The `stream=False` argument prevents immediate streaming.

```python
import earthkit.data

request = {
    "class": "ai",
    "stream" : "oper",
    "type" : "fc",
    "date" : -1,
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0001", 
    "model": "aifs-single",
    "domain" : "g",
    "param" : "166/167/169",
    "step" : "0",
    "feature": {
        "type": "polygon",
        "shape": [[41.870881288,-8.8791360], [41.694339317422646, -8.824238614026456], [40.171924585721314, -8.902386975546364], [38.75694209400925, -9.493088042617785], [38.42424252381525, -9.171674240710018], [38.49907333213173, -8.676525850529856], [37.057269459205145, -8.971873318897366], [37.162874354643776, -7.406745406502978], [38.19776118392036, -6.931663452624974], [38.4280922170291, -7.321584397020473], [39.011852875635526, -6.9787177479519755], [39.66227871551288, -7.5393956904523804], [39.66568774825791, -7.03915852435145], [40.0019453234905, -6.883203763416162], [40.20373392742229, -7.035724907677206], [40.350463990828985, -6.8135246275213035], [41.030499770212515, -6.905947651233703], [41.593647729084154, -6.22847017956974], [41.67712153119277, -6.544984134823352], [41.949682257268876, -6.567927092516641], [41.96960294343674, -7.1747800681640115], [41.88337981339092, -7.196871678410446], [41.81334515396762,-8.156666519264604], [42.14242723772878, -8.205142297350534], [41.870881288,-8.8791360]],
    },
}

ds = earthkit.data.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int')
```

--------------------------------

### Valid Polytope-MARS Request (Step via Top-Level) (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Design_doc.md

Provides a complete example of a valid Polytope-MARS request dictionary structure. It includes standard MARS request parameters like `class`, `stream`, `date`, `time`, and uses the traditional top-level `step` key to define the requested forecast steps. It also includes a `feature` dictionary specifying a timeseries at a point, which is valid because the `step` dimension is not also defined using `range` within the `feature`.

```Python
request = {
    "class": "od",
    "stream" : "enfo",
    "type" : "pf",
    "date" : "20241006",
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0079", 
    "domain" : "g",
    "param" : "164/167/169",
    "number" : "1/to/50",
    "step": "0/to/360",
    "feature" : {
        "type" : "timeseries",
        "points": [[-9.10, 38.78]],
        "axis": "step",
    },
}
```

--------------------------------

### Requesting Vertical Profile with Range - earthkit-data Python

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Features/vertical_profile.md

Demonstrates structuring a request dictionary for fetching a vertical profile using earthkit-data from the 'polytope' source and 'ecmwf-mars' dataset. It specifies the vertical profile type and geographical points within the 'feature' dictionary, defining the vertical axis ('levelist') and range ('start' to 'end') within the 'feature' object. The request dictionary includes standard MARS parameters and is passed to the earthkit.data.from_source function.

```Python
import earthkit.data

request = {
    "class": "od",
    "stream" : "enfo",
    "type" : "pf",
    "date" : -1,  # Note: date must be within the last two days 
    "time" : "0000",
    "levtype" : "pl",
    "expver" : "0001", 
    "domain" : "g",
    "param" : "203/133",
    "number" : "1",
    "step" : "0",
    "feature" : {
        "type" : "verticalprofile",
        "points": [[-9.10, 38.78]],
        "axes": "levelist",
        "range" : {
            "start" : 0,
            "end" : 1000,
        }
    },
    "format": "covjson",
}

ds = earthkit.data.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int')
```

--------------------------------

### Defining Vertical Range with Interval - Python Request

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Features/vertical_profile.md

Provides a fragment of a request dictionary's 'feature' object, specifically focusing on the 'range' definition for a vertical profile. It shows how to include the optional 'interval' key within the 'range' dictionary to specify that data should be returned for every nth level within the defined 'start' and 'end' levels on the 'levelist' axis, if those levels exist in the dataset.

```Python
    "axes": "levelist",
    "range" : {
        "start" : 0,
        "end" : 1000,
        "interval" : 2,
    }
```

--------------------------------

### Requesting Vertical Profile with Range Geometry (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Design_doc.md

Shows an alternative Python dictionary format for a vertical profile request. Instead of a top-level `levelist`, it uses a `range` object within the `feature` geometry to specify the levels (`feature: {"type": "verticalprofile", "points": [[38.9, -9.1]], "range": {"start": 1, "end": 1000}}`), which is equivalent to the previous snippet's `levelist`. Requires `levtype` to be non-sfc.

```python
request = {
    "class": "od",
    "stream": "enfo",
    "type": "pf",
    "date": "20240925",
    "time": "0000",
    "levtype": "pl",
    "expver": "0079",
    "domain": "g",
    "param": "203/133",
    "number": "1",
    "step": "0",
    "levelist": "1/to/1000",
    "feature": {
        "type": "verticalprofile",
        "points": [[38.9, -9.1]],
        "range" : {
            "start" : 1,
            "end" : 1000
        }
    },
}
```

--------------------------------

### Fetching Bounding Box Data with Earthkit Data

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/boundingbox_example.ipynb

Defines a dictionary representing a MARS request including a 'boundingbox' feature with specific latitude/longitude points. It then uses `earthkit.data.from_source` to retrieve the data from the 'polytope' source, connecting to a specified address. Requires the earthkit.data library. Inputs: request dictionary, source name, address. Output: an earthkit.data dataset object.

```python
import earthkit.data

request = {
    "class": "od",
    "stream" : "enfo",
    "type" : "pf",
    "date" : -1,  # Note: date must be within the last two days
    "time" : "0000",
    "levtype" : "sfc",
    "expver" : "0001", 
    "domain" : "g",
    "param" : "164/166/167/169",
    "number" : "1",
    "step": "0",
    "feature" : {
        "type" : "boundingbox",
        "points" : [[53.55, 2.76], [50.66, 7.86]],
	},
}

ds = earthkit.data.from_source("polytope", "ecmwf-mars", request, stream=False, address='polytope.ecmwf.int')
```

--------------------------------

### Visualizing Data with earthkit.plots (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/polygon_example.ipynb

This snippet visualizes the retrieved data using `earthkit.plots`. It first initializes a map centered on Portugal, then plots the '2t' variable (2-meter temperature) from the xarray DataArray (`da`) as a point cloud, using 'x' and 'y' as coordinate variable names. It adds geographical context by drawing coastlines, borders, and gridlines, sets a dynamic plot title, adds a legend, and finally displays the generated map.

```python
da = ds.to_xarray()
import earthkit.plots
chart = earthkit.plots.Map(domain="Portugal")
chart.point_cloud(da['2t'], x="y", y="x")

chart.coastlines()
chart.borders()
chart.gridlines()

chart.title("{variable_name} (number={number})")

chart.legend()

chart.show()

```

--------------------------------

### Visualizing Xarray Data with Earthkit Plots

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/boundingbox_example.ipynb

Takes an xarray DataArray (obtained from an earthkit.data dataset) and visualizes it using earthkit.plots. It creates a map centered on Europe, plots the '2t' variable as points, adds geographical context like coastlines and borders, sets a dynamic title, includes a legend, and displays the resulting map. Requires earthkit.data (for the first line) and earthkit.plots. Inputs: earthkit.data dataset (`ds`). Output: A displayed map visualization.

```python
da = ds.to_xarray()
import earthkit.plots
chart = earthkit.plots.Map(domain="Europe")
chart.point_cloud(da['2t'], x="y", y="x")

chart.coastlines()
chart.borders()
chart.gridlines()

chart.title("{variable_name} (number={number})")

chart.legend()

chart.show()
```

--------------------------------

### Defining Trajectory Axes Options (Python)

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Features/trajectory.md

This Python snippet shows an example list of potential strings that can be used as values for the `axes` field within the `feature` dictionary of a trajectory request. It indicates the dimensions along which the trajectory points can be defined, including latitude, longitude, levelist, and step.

```python
"axes" : ["latitude", "longitude", "levelist", "step"]
```

--------------------------------

### Converting Earthkit Dataset to Xarray

Source: https://github.com/ecmwf/polytope/blob/develop/docs/Service/Examples/boundingbox_example.ipynb

Converts the obtained earthkit.data dataset object into an xarray DataArray using the `to_xarray()` method. This step is often necessary to utilize xarray's capabilities or to prepare the data for visualization libraries like earthkit.plots that accept xarray objects. Requires an earthkit.data dataset object. Inputs: earthkit.data dataset. Output: an xarray DataArray.

```python
da = ds.to_xarray()
da
```