add Gee dataset classes and modeldata in the documentation

docs/MetObs_documentation_flat.rst

@@ -13,7 +13,7 @@ the MetObs toolkit to be used by a user and developer.
   Station <reference/station>
   Obstype <reference/obstype>
   Analysis <reference/analysis>
-  Modeldata <reference/modeldata>
+  Gee modeldata <reference/geemodeldata>
   Template <reference/template>
   Special functions <reference/special_functions>
 

docs/intro.rst

@@ -123,19 +123,28 @@ The Analysis methods are based on aggregating the observations to get insight in
 
 
 
-Modeldata()
--------------
-The :ref:`Modeldata <Modeldata api>` holds time-series of data from a source other than observations (i.g. a model). The time-series are taken at the same coordinates as the stations and the
-names of the stations are used as well.
+GEE Modeldata classes
+----------------------
 
-This class is used for comparing other sources to observations and for filling in missing observations and gaps in the observations.
+Two classes are designed to interact with a GEE (Google Earth Engine) dataset:
+
+* `GeeStaticModelData`: This class handles GEE Datasets that do not have a time dimension (static). This class is used to extract GEE dataset values at the location of the station (or buffers arround them).
+* `GeeDynamicModelData`: This class handles GEE Dataset that have a time dimension. This class is used to extract timeseries of GEE dataset values at the stations locations.
+
+Both classes can hold metadata (=Coordinates of the stations), and the ´GeeDynamicModelData` class can hold timeseries data.
+These classes are used for extracting extra metadata (landcover, altitude, soil properties, ...) and for comparing
+observations with modelled data (plotting, filling gaps, ...).
+
+There are default modeldata classes prepared, and they are stored in the `Dataset.gee_datasets`.
 
 
 .. code-block:: python
 
-   ERA5_timeseries = your_dataset.get_modeldata(modelname='ERA5_hourly',
-                                                obstype='temp')
+   ERA5_timeseries = your_dataset.get_modeldata(
+                                       Model=your_datast.gee_datasets['ERA5-land'],
+                                        obstype='temp')
 
+See the API documentiontion :ref:`Geemodeldata <Geemodeldata api>` for more details.
 
 The toolkit makes use of the Google Earth Engine (GEE), to extract these time-series. To use the GEE API, follow these steps on :ref:`Using Google Earth Engine<Using_gee>`.
 

docs/reference/geemodeldata.rst

@@ -0,0 +1,58 @@
+.. _Geemodeldata api:
+
+===============
+GEE Modeldata
+===============
+
+The Gee (Google Earth Engine) Modeldata is the bridge between the Metobs-toolkit
+and the GEE services. There are two classes:
+
+ * `GeeStaticModelData`: This class handles GEE Datasets that do not have a time dimension (static). This class is used to extract GEE dataset values at the location of the station (or buffers arround them).
+ * `GeeDynamicModelData`: This class handles GEE Dataset that have a time dimension. This class is used to extract timeseries of GEE dataset values at the stations locations.
+
+Both classes can hold metadata (=Coordinates of the stations), and the ´GeeDynamicModelData` class can hold timeseries data.
+
+.. note::
+    Extracting data from a GEE dataset, can be done directly from a `GeeStaticModelData`
+    or a `GeeDynamicModelData`. In addition, one can call extractions also directly from
+    a `Dataset`, see the *Extracting data* section in the `Dataset` API documentation.
+
+
+.. note::
+   Keep in mind that the Modeldata does not hold gridded data, but timeseries of
+   point extractions at the locations of the stations. Therefore a Modeldata
+   instance is linked to a collection of stations defined by the `metadf` attribute.
+
+Demo examples on the Modeldata class can be found here: :ref:`Extracting ERA5 timeseries`_ .
+
+
+GeeStaticModelData
+--------------------
+
+.. currentmodule:: metobs_toolkit
+
+.. autosummary::
+   :toctree: api/
+
+   GeeStaticModelData
+   GeeStaticModelData.get_info
+   GeeStaticModelData.extract_static_point_data
+   GeeStaticModelData.extract_static_buffer_frac_data
+   GeeStaticModelData.make_gee_plot
+
+
+GeeDynamicModelData
+--------------------
+
+.. autosummary::
+   :toctree: api/
+
+   GeeDynamicModelData
+   GeeDynamicModelData.get_info
+   GeeDynamicModelData.add_modelobstype
+   GeeDynamicModelData.extract_timeseries_data
+   GeeDynamicModelData.save_modeldata
+   GeeDynamicModelData.set_modeldata_from_csv
+   GeeDynamicModelData.import_modeldata_from_pkl
+   GeeDynamicModelData.make_plot
+   GeeDynamicModelData.make_gee_plot

docs/reference/obstype.rst

@@ -46,87 +46,41 @@ Developers methods and attributes for Obstype
 
 .. _ModelObstype api:
 
-==============
-ModelObstype
-==============
+==============================
+Obstypes used for GEE datasets
+===============================
 
-A child of :ref:`Obstype api` that adds info on how this observationtype is represented in modeloutput.
-All methods of Obstype() are inhereted.
+A child of :ref:`Obstype api` that adds info on how this observationtype is represented in a GEE dataset.
 
-Constructor for ModelObstype
------------------------------
+There are two classes:
+ * `ModelObstype` : Represent a scalar Obstype for which there exists a band in a GEE dataset.
+ * `ModelObstype_Vectorfield` : Represent a vectorfield, for which the *u* and *v* components exists in bands of a GEE dataset.
 
-.. autosummary::
-   :toctree: api/
 
-   ModelObstype
+ModelObstype
+-----------------------------
 
-General methods and attributes for ModelObstype
-------------------------------------------------
+All methods of `Obstype` are inhereted.
 
 .. autosummary::
    :toctree: api/
 
-   ModelObstype.get_mapped_datasets
-   ModelObstype.get_bandname
+   ModelObstype
    ModelObstype.get_modelunit
-   ModelObstype.add_new_band
+   ModelObstype.get_modelband
 
-Developers methods and attributes for ModelObstype
----------------------------------------------------
 
-.. autosummary::
-   :toctree: api/
-
-   ModelObstype.get_bandname_mapper
-   ModelObstype.has_mapped_band
-
-
-.. _ModelObstype_Vectorfield api:
-
-==========================
 ModelObstype_Vectorfield
-==========================
-
-A child of :ref:`Obstype api`, similar to :ref:`ModelObstype api`, that adds info on how this handle 2D vectorfields in the modeloutput.
-A vectorfield in the modeloutput is defined by its components.
-
-All methods of Obstype() are inhereted.
+-----------------------------
 
-Constructor for ModelObstype_Vectorfield
------------------------------------------
+All methods of `Obstype` are inhereted.
 
 .. autosummary::
    :toctree: api/
 
    ModelObstype_Vectorfield
-
-General methods and attributes for ModelObstype_Vectorfield
--------------------------------------------------------------
-
-.. autosummary::
-   :toctree: api/
-
-   ModelObstype_Vectorfield.get_mapped_datasets
    ModelObstype_Vectorfield.get_modelunit
-   ModelObstype_Vectorfield.add_new_band
-
-Developers methods and attributes
-------------------------------------
-
-.. autosummary::
-   :toctree: api/
-
-   ModelObstype_Vectorfield.get_bandname_mapper
-   ModelObstype_Vectorfield.has_mapped_band
-
-
-Developers vectorfield conversion functions
----------------------------------------------
-These functions are used by the :ref:`ModelObstype_Vectorfield api` to convert components to amplitudes and angles.
-
-.. autosummary::
-   :toctree: api/
-
-   obstype_modeldata.compute_amplitude
-   obstype_modeldata.compute_angle
+   ModelObstype_Vectorfield.get_modelband_u
+   ModelObstype_Vectorfield.get_modelband_v
+   ModelObstype_Vectorfield.compute_angle
+   ModelObstype_Vectorfield.compute_amplitude