update template in doc api (#465)

* update template in doc api * typo
vergauwenthomas · Jul 16, 2024 · 37e3ee8 · 37e3ee8
1 parent d31e358
commit 37e3ee8
Show file tree

Hide file tree

Showing 7 changed files with 140 additions and 274 deletions.
diff --git a/docs/MetObs_documentation_flat.rst b/docs/MetObs_documentation_flat.rst
@@ -14,6 +14,7 @@ the MetObs toolkit to be used by a user and developer.
   Obstype <reference/obstype>
   Analysis <reference/analysis>
   Modeldata <reference/modeldata>
+  Template <reference/template>
 
 ********************************************
 Modules for MetObs toolkit Developers

diff --git a/docs/notebook_references/template_doc.ipynb b/docs/notebook_references/template_doc.ipynb
@@ -172,7 +172,7 @@
     "tags": []
    },
    "source": [
-    "### Single-statio-format\n",
+    "### Single-station-format\n",
     "The same as a long format but without a column indicating the station names. Be aware that the toolkit interprets it as observations coming from one station."
    ]
   },

diff --git a/docs/reference/analysis.rst b/docs/reference/analysis.rst
@@ -16,7 +16,7 @@ Constructor
 .. autosummary::
    :toctree: api/
 
-   metobs_toolkit.analysis.Analysis
+   analysis.Analysis
 
 .. note::
    It is most common to construct the Analysis directly from a Dataset using `metobs_toolkit.Dataset.get_analysis()` method.
@@ -27,14 +27,14 @@ General methods and attributes
 .. autosummary::
    :toctree: api/
 
-   metobs_toolkit.analysis.Analysis.subset_period
-   metobs_toolkit.analysis.Analysis.apply_filter
-   metobs_toolkit.analysis.Analysis.aggregate_df
-   metobs_toolkit.analysis.Analysis.get_anual_statistics
-   metobs_toolkit.analysis.Analysis.get_diurnal_statistics
-   metobs_toolkit.analysis.Analysis.get_diurnal_statistics_with_reference
-   metobs_toolkit.analysis.Analysis.get_aggregated_cycle_statistics
-   metobs_toolkit.analysis.Analysis.get_lc_correlation_matrices
+   analysis.Analysis.subset_period
+   analysis.Analysis.apply_filter
+   analysis.Analysis.aggregate_df
+   analysis.Analysis.get_anual_statistics
+   analysis.Analysis.get_diurnal_statistics
+   analysis.Analysis.get_diurnal_statistics_with_reference
+   analysis.Analysis.get_aggregated_cycle_statistics
+   analysis.Analysis.get_lc_correlation_matrices
 
 
 
@@ -44,5 +44,5 @@ Plotting methods
 .. autosummary::
    :toctree: api/
 
-   metobs_toolkit.analysis.Analysis.plot_correlation_heatmap
-   metobs_toolkit.analysis.Analysis.plot_correlation_variation
+   analysis.Analysis.plot_correlation_heatmap
+   analysis.Analysis.plot_correlation_variation
diff --git a/docs/reference/obstype.rst b/docs/reference/obstype.rst
@@ -128,5 +128,5 @@ These functions are used by the :ref:`ModelObstype_Vectorfield api` to convert c
 .. autosummary::
    :toctree: api/
 
-   metobs_toolkit.obstype_modeldata.compute_amplitude
-   metobs_toolkit.obstype_modeldata.compute_angle
+   obstype_modeldata.compute_amplitude
+   obstype_modeldata.compute_angle
diff --git a/docs/reference/template.rst b/docs/reference/template.rst
@@ -0,0 +1,52 @@
+.. _Template api:
+
+============
+Template
+============
+
+The template class holds the information on how to interpret raw datafiles.
+This is done by mapping to standards defined in the toolkit. See the :ref:`Mapping to the toolkit`_ section.
+
+
+.. note::
+   In practice, a user does not need to interact with the `Template()` class. A
+   `Template()` instance is constructed from a templatefile (json). The user
+   must create this templatefile, and the `Template()` is constructed from it.
+
+The `Template` is stored as an attribute of a `Dataset`, and it can be reached as such.
+
+
+.. code-block:: python
+
+   import metobs_toolkit
+   your_dataset = metobs_toolkit.Dataset()
+   your_dataset.update_settings(
+    input_data_file=" ... ",
+    input_metadata_file=" ... ",
+    template_file=" ... ", # path to your template file (json)
+    )
+    # Importing the data will construct the Template
+    your_dataset.import_data_from_file()
+    # The Template is stored in each Dataset
+    your_dataset.template
+
+.. currentmodule:: metobs_toolkit
+
+Constructing a templatefile
+-----------------------------
+
+.. autosummary::
+   :toctree: api/
+
+   build_template_prompt
+
+
+
+Common methods
+--------------------
+
+.. autosummary::
+   :toctree: api/
+
+   template.Template.get_info
+   template.Template.show
diff --git a/metobs_toolkit/template.py b/metobs_toolkit/template.py
@@ -116,8 +116,9 @@ def __init__(self):
         self.filepath = None
 
     def show(self):
-        """
-        Prints out an overview of Template.
+        """Prints out an overview of Template.
+
+        Alias of Template.get_info().
 
         Returns
         -------
@@ -135,6 +136,45 @@ def get_info(self):
         -------
         None.
 
+        Examples
+        --------
+        .. code-block:: python
+
+            >>> import metobs_toolkit
+            >>>
+            >>> #Create your Dataset
+            >>> dataset = metobs_toolkit.Dataset() #empty Dataset
+            >>>
+            >>> #Add observations to the Dataset
+            >>> dataset.update_settings(
+            ...                         input_data_file=metobs_toolkit.demo_datafile,
+            ...                         input_metadata_file=metobs_toolkit.demo_metadatafile,
+            ...                         template_file=metobs_toolkit.demo_template,
+            ...                         )
+            >>> dataset.import_data_from_file()
+            >>>
+            >>> # Print out details
+            >>> dataset.template.get_info()
+            ------ Data obstypes map ---------
+             * temp            <---> Temperatuur
+                 (raw data in Celsius)
+                 (description: 2mT passive)
+            <BLANKLINE>
+             * humidity        <---> Vochtigheid
+                 (raw data in %)
+                 (description: 2m relative humidity passive)
+            <BLANKLINE>
+             * wind_speed      <---> Windsnelheid
+                 (raw data in km/h)
+                 (description: Average 2m  10-min windspeed)
+            <BLANKLINE>
+             * wind_direction  <---> Windrichting
+                 (raw data in ° from north (CW))
+                 (description: Average 2m  10-min windspeed)
+            <BLANKLINE>
+            <BLANKLINE>
+            ...
+
         """
 
         key_len = 15