Merge pull request #225 from ecmwf/feature/update_docs

Split the docs into algorithm and Service, add initial docs to service
ecmwf · Oct 30, 2024 · 0f833c7 · 0f833c7
2 parents 817a8e4 + 2494a93
commit 0f833c7
Show file tree

Hide file tree

Showing 36 changed files with 10,158 additions and 20 deletions.
diff --git a/docs/Developer_Guide/API.md → docs/Algorithm/Developer_Guide/API.md b/docs/Developer_Guide/API.md → docs/Algorithm/Developer_Guide/API.md
diff --git a/docs/Developer_Guide/Axis_types.md → docs/Algorithm/Developer_Guide/Axis_types.md b/docs/Developer_Guide/Axis_types.md → docs/Algorithm/Developer_Guide/Axis_types.md
diff --git a/docs/Developer_Guide/Datacube.md → docs/Algorithm/Developer_Guide/Datacube.md b/docs/Developer_Guide/Datacube.md → docs/Algorithm/Developer_Guide/Datacube.md
diff --git a/docs/Developer_Guide/Overview.md → docs/Algorithm/Developer_Guide/Overview.md b/docs/Developer_Guide/Overview.md → docs/Algorithm/Developer_Guide/Overview.md
diff --git a/docs/Developer_Guide/Slicer.md → docs/Algorithm/Developer_Guide/Slicer.md b/docs/Developer_Guide/Slicer.md → docs/Algorithm/Developer_Guide/Slicer.md
diff --git a/...eveloper_Guide/images/Polytope_APIs_3.png → ...eveloper_Guide/images/Polytope_APIs_3.png b/...eveloper_Guide/images/Polytope_APIs_3.png → ...eveloper_Guide/images/Polytope_APIs_3.png
diff --git a/...er_Guide/images/polytope_components_5.png → ...er_Guide/images/polytope_components_5.png b/...er_Guide/images/polytope_components_5.png → ...er_Guide/images/polytope_components_5.png
diff --git a/...eveloper_Guide/images/slicing_process.png → ...eveloper_Guide/images/slicing_process.png b/...eveloper_Guide/images/slicing_process.png → ...eveloper_Guide/images/slicing_process.png
diff --git a/docs/Developer_Guide/shapes.md → docs/Algorithm/Developer_Guide/shapes.md b/docs/Developer_Guide/shapes.md → docs/Algorithm/Developer_Guide/shapes.md
diff --git a/docs/Overview/Overview.md → docs/Algorithm/Overview/Overview.md b/docs/Overview/Overview.md → docs/Algorithm/Overview/Overview.md
diff --git a/docs/Overview/Polytope_at_ECMWF.md → docs/Algorithm/Overview/Polytope_at_ECMWF.md b/docs/Overview/Polytope_at_ECMWF.md → docs/Algorithm/Overview/Polytope_at_ECMWF.md
diff --git a/...erview/images_overview/ecmwf_datacube.png → ...erview/images_overview/ecmwf_datacube.png b/...erview/images_overview/ecmwf_datacube.png → ...erview/images_overview/ecmwf_datacube.png
diff --git a/...erview/images_overview/ecmwf_polytope.png → ...erview/images_overview/ecmwf_polytope.png b/...erview/images_overview/ecmwf_polytope.png → ...erview/images_overview/ecmwf_polytope.png
diff --git a/docs/Algorithm/User_Guide/Building_Features.md b/docs/Algorithm/User_Guide/Building_Features.md
@@ -0,0 +1,41 @@
+# Building Features
+
+The Polytope software implements a set of base shapes that might be of interest to users. These are detailed [here](../Developer_Guide/shapes.md).
+
+For many applications however, these shapes are not directly of interest and should rather be used as building blocks for more complex and domain-specific "features", such as timeseries or country areas.
+
+The main requirement when building such features in Polytope is that the feature should be defined on all dimensions of the provided datacube.
+This implies that, when defining lower-dimensional shapes in higher-dimensional datacubes, the remaining axes still need to be specified within the Polytope request (most likely as *Select* shapes). 
+
+For example, for a given datacube with dimensions "level", "step", "latitude" and "longitude", we could query the following shapes:
+
+- a timeseries of a point which would be defined as
+
+        Request(
+            Point(["latitude", "longitude"], [[p1_lat, p1_lon]]), 
+            Span("step", start_step, end_step), 
+            Select("level", [level1])
+            )
+
+
+- a specific country area which would be defined as 
+
+        Request(
+            Polygon(["latitude", "longitude"], country_points), 
+            Select("step", [step1]),
+            Select("level", [level1])
+            )
+
+- a flight path which would be defined as 
+
+        Request(
+            Path(
+                ["latitude", "longitude", "level", "step"],
+                Box(
+                    ["latitude", "longitude", "level", "step"],
+                    [0, 0, 0, 0],
+                    [lat_padding, lon_padding, level_padding, step_padding]
+                ),
+                flight_points
+                )
+            )
diff --git a/docs/User_Guide/Example.md → docs/Algorithm/User_Guide/Example.md b/docs/User_Guide/Example.md → docs/Algorithm/User_Guide/Example.md
diff --git a/docs/User_Guide/Getting_started.md → docs/Algorithm/User_Guide/Getting_started.md b/docs/User_Guide/Getting_started.md → docs/Algorithm/User_Guide/Getting_started.md
diff --git a/docs/User_Guide/Overview.md → docs/Algorithm/User_Guide/Overview.md b/docs/User_Guide/Overview.md → docs/Algorithm/User_Guide/Overview.md
@@ -15,6 +15,8 @@ For a quick guide of how to install and use Polytope, refer to the links below:
 
 - <a href="../Example">Example</a> 
 
+- <a href="../Building_Features">Building Features</a> 
+
 !!!note 
     <!-- For more information about Polytopes' APIs, refer to the [API page](../Developer_Guide/API.md).  -->
     An exhaustive list of all shapes that can currently be requested using Polytope can be found [here](../Developer_Guide/shapes.md).

diff --git a/...ser_Guide/images_users/shipping_route.png → ...ser_Guide/images_users/shipping_route.png b/...ser_Guide/images_users/shipping_route.png → ...ser_Guide/images_users/shipping_route.png