Merge pull request #261 from ecmwf/develop

mathleur · web-flow · commit 0c02e4146a1a · 2024-11-15T15:23:26.000+01:00
update docs
diff --git a/docs/Service/Examples/timeseries_example.ipynb b/docs/Service/Examples/timeseries_example.ipynb
@@ -39,7 +39,7 @@
     "    \"feature\" : {\n",
     "        \"type\" : \"timeseries\",\n",
     "        \"points\": LOCATION,\n",
-    "        \"axis\": \"step\",\n",
+    "        \"axes\": \"step\",\n",
     "    },\n",
     "}\n",
     "\n",
diff --git a/docs/Service/Features/boundingbox.md b/docs/Service/Features/boundingbox.md
@@ -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"
 }
 ```
 
diff --git a/docs/Service/Features/trajectory.md b/docs/Service/Features/trajectory.md
@@ -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.
 
@@ -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",
@@ -89,7 +88,7 @@ request = {
     "feature" : {
         "type" : "trajectory",
         "points" : [[-1, -1], [0, 0], [-1, -1]],
-        "axes" : ['lat', 'lon']
+        "axes" : ['latitude', 'longitude']
 	},
 }
 ```
@@ -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.
+-->
diff --git a/docs/Service/Features/vertical_profile.md b/docs/Service/Features/vertical_profile.md
@@ -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",
@@ -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",
 }
 ```
 
diff --git a/docs/Service/Installation.md b/docs/Service/Installation.md
@@ -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]
diff --git a/docs/Service/Quick_Start.md b/docs/Service/Quick_Start.md
@@ -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">
