Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update features and installation #260

Merged
merged 1 commit into from
Nov 15, 2024
Merged

Update features and installation #260

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/Service/Features/boundingbox.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,36 +48,36 @@ For a bounding box, `type` must be `boundingbox`.

## Optional Fields

`axes` refers to the axes on which to generate the bounding box. As stated above the minimum default `axes` contains `lat` and `lon` meaning if `axes` is not included these values must be provided per point. By default the level is taken from the main body of the request.
`axes` refers to the axes on which to generate the bounding box. As stated above the minimum default `axes` contains `latitude` and `longitude` meaning if `axes` is not included these values must be provided per point. By default the level is taken from the main body of the request.

However `axes` can also be provided by the user and with a value for level. Such as here:

```python
"axes" : ["lat", "long", "level"]
"axes" : ["latitude", "longitude", "levelist"]
```

In this case the user must provide a `lat`, `lon` and `level`. `level` should not be included in the main body of the request in this case. An example can be seen here:
In this case the user must provide a `latitude`, `longitude` and `levelist`. `levelist` should not be included in the main body of the request in this case. An example can be seen here:


```python
request = {
"class" : "od",
"class": "od",
"stream" : "enfo",
"type" : "pf",
"date" : -1,
"time" : "0000",
"levtype" : "pl",
"expver" : "0001",
"domain" : "g",
"param" : "164/167/169",
"levtype" : "pl",
"param" : "203/133",
"number" : "1",
"step" : "0",
"feature" : {
"type" : "boundingbox",
"points" : [[-1, -1, 1000], [1, 1, 500]],
"axes" : ["lat", "lon", "level"],
"points" : [[-0.1, -0.1, 500], [0.1, 0.1, 1000]],
"axes" : ["latitude", "longitude", "levelist"]
},
"format" : "covjson",
"format" : "covjson"
}
```

Expand Down
42 changes: 21 additions & 21 deletions docs/Service/Features/trajectory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,32 +8,29 @@ An example trajectory requested via earthkit-data:
import earthkit.data

request = {
"class" : "od",
"class": "od",
"stream" : "enfo",
"type" : "pf",
"date" : -1, # Note: date must be within the last two days
"date" : -1,
"time" : "0000",
"levtype" : "sfc",
"expver" : "0001",
"domain" : "g",
"param" : "164/167/169",
"levtype" : "pl",
"param" : "164/166/167/169",
"number" : "1",
"step": "0",
"feature" : {
"type" : "trajectory",
"points" : [[-1, -1, 1000, 0], [0, 0, 1000, 12], [1, 1, 250, 24]],
"points" : [[-0.1, -0.1], [0, 0], [0.1, 0.1]],
"radius" : 0.1,
"axes" :["latitude", "longitude"],
},
"format" : "covjson",
}

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

This request will return a trajectory from yesterday's midnight forecast for the three requested parameters for the points:

* `lat: -1, lon: -1, pressure level: 1000, step: 0`
* `lat: 0, lon: 0, pressure level: 1000, step: 12`
* `lat: 1, lon: 1, pressure level: 250, step: 24`
This request will return a trajectory from yesterday's midnight forecast for the three requested parameters for the points along the path gives with a radius of 0.1.

The `trajectory` `feature` also contains another field called `radius`. This is the radius of the circle swept around the trajectory where points within this radius are returned to the user.

Expand All @@ -49,35 +46,37 @@ For a trajectory two fields are required within the `feature` dictionary

For a trajectory `type` must be `trajectory`.

The values in `points` can change depending on the `axes`. The default for `axes` is:
The values in `points` can change depending on the `axes`. `axes` can contain the following values:

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

In this default case, a nested list of at least two points with values for `lat`, `lon`, `level`, and `step` must be provided.
In this default case, a nested list of at least two points with values for `latitude` and `longitude` must be provided.

Another required field that is within the `feature` dictionary is `radius`. This refers to the radius of the circle swept around the trajectory along which points will be included.


## Optional Fields

`axes` refers to the axes on which to generate the trajectory. As stated above the minimum default `axes` contains `lat`, `lon`, `level`, and `step` meaning if `axes` is not included these values must be provided per point.
`axes` refers to the axes on which to generate the trajectory. As stated above the minimum default `axes` contains `latitude`, `longitude` meaning if `axes` is not included these values must be provided per point.

However `axes` can also be provided by the user and with less values. The minimum values of `axes` are:
However `axes` can also be provided by the user and with more values:

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

In this case only `lat` and `lon` must be provided in the requested points but a level and time axis must be provided in the main body of the request. These values will be propagated for each set of `lat`, `lon` points. For example in the following request:
In this case a point must contain a value for each axis.
<!---
In this case only `latitude` and `longitude` must be provided in the requested points but a level and time axis must be provided in the main body of the request. These values will be propagated for each set of `latitude`, `longitude` points. For example in the following request:

```python
request = {
"class" : "od",
"stream" : "enfo",
"type" : "pf",
"date" : yesterday,
"date" : -1,
"time" : "0000",
"expver" : "0001",
"domain" : "g",
Expand All @@ -89,7 +88,7 @@ request = {
"feature" : {
"type" : "trajectory",
"points" : [[-1, -1], [0, 0], [-1, -1]],
"axes" : ['lat', 'lon']
"axes" : ['latitude', 'longitude']
},
}
```
Expand All @@ -105,4 +104,5 @@ The following points would be returned:

The user does not have to give `step` as the time axis. In the case of a climate dataset `datetime` can also be used.

Combinations such as `"axis" : ['lat', 'step']` will return an error if `step` is included as an `axis` and also in the main body of the request. An error that the request is overspecified will also be thrown.
Combinations such as `"axis" : ['lat', 'step']` will return an error if `step` is included as an `axis` and also in the main body of the request. An error that the request is overspecified will also be thrown.
-->
18 changes: 9 additions & 9 deletions docs/Service/Features/vertical_profile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ request = {
"levtype" : "pl",
"expver" : "0001",
"domain" : "g",
"param" : "164/167/169",
"number" : "1/to/50",
"param" : "203/133",
"number" : "1",
"step" : "0",
"feature" : {
"type" : "verticalprofile",
Expand Down Expand Up @@ -84,18 +84,18 @@ request = {
"type" : "pf",
"date" : -1,
"time" : "0000",
"levtype" : "sfc",
"levtype" : "pl",
"expver" : "0001",
"domain" : "g",
"param" : "164/167/169",
"number" : "1/to/50",
"param" : "203/133",
"number" : "1",
"step" : "0",
"levelist" : "0/to/1000",
"feature" : {
"type" : "timeseries",
"points": [[-9.10, 38.78]],
"axes": "levelist",
"type" : "verticalprofile",
"points": [[38.9, -9.1]],
"axes" : "levelist",
},
"format": "covjson",
}
```

Expand Down
4 changes: 4 additions & 0 deletions docs/Service/Installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ To use covjson functionality also run:

python3 -m pip install earthkit-data[covjsonkit]

To use any of the visualisations, also install earthkit-plots:

python3 -m pip install earthkit-plots

Installing like this gives you a **minimal** package which can talk to Polytope. If you want to use more data types or remote services you need to install other optional features of earthkit-data, or just install all of them:

python3 -m pip install earthkit-data[all]
Expand Down
21 changes: 8 additions & 13 deletions docs/Service/Quick_Start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,21 +51,16 @@ ds.to_xarray()
The following visualisation does not use the latest version of earthkit-plots. To replicate it you need to install the https://github.com/ecmwf/earthkit-plots/tree/feature/ams-meteograms branch

```python
import ipywidgets as widgets
import earthkit.plots
import earthkit.data

TIME_FREQUENCY = "6H"
from earthkit.plots.interactive import Chart

def f():
data = ds
chart = earthkit.plots.Chart()
chart.box(data, time_frequency=TIME_FREQUENCY)
chart.line(data, time_frequency=TIME_FREQUENCY, aggregation="mean", line_color="purple")
chart.show()
TIME_FREQUENCY = "6h"
QUANTILES = [0, 0.1, 0.25, 0.5, 0.75, 0.9, 1]

out = widgets.interactive_output(f, {})
display(out)
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!
```

<div style="text-align:center">
Expand Down
Loading