Explain experiments and use case recipe in docs (#143)

Co-authored-by: Stefan Verhoeven <[email protected]>
phenology · Jun 30, 2023 · 9b43c69 · 9b43c69
1 parent ce3bdfd
commit 9b43c69
Show file tree

Hide file tree

Showing 5 changed files with 129 additions and 65 deletions.
diff --git a/README.md b/README.md
@@ -99,30 +99,61 @@ e.g.
 
 ```yaml
 datasets:
-  syringa_filtered:
-    dataset: PEP725Phenor
-    species: Syringa vulgaris
-    years: [2000, 2001]
+  npn_obs:
+    dataset: RNPN
+    species_ids:
+      functional_type: "Deciduous broadleaf" # multiple species
+    phenophase_ids:
+        name: breaking leaf buds
+    years: [2015, 2020]
     area:
-      name: somewhere
-      bbox: [4, 45, 8, 50]
-models:
-  target: day_of_first_bloom
-  sklearn:
-    model: sklearn.linear_model
-    options: ...
+      name: Washington
+      bbox:
+        [
+          -124.08406940413612,
+          45.50277198520317,
+          -117.39620059586387,
+          49.99938001479683,
+        ]
+  daymet:
+    dataset: daymet_multiple_points
+    points:
+      source: npn_obs
+    years: [2015, 2020]
+    variables:
+      - tmin
+      - tmax
+    resample:
+      frequency: month
+      operator: median
+dropna: True
+experiment:
+  experiment_type: regression  # --> pycaret.regression.RegressionExperiment
+  setup:
+    ... # setup of the experiment
+  init_kwargs:
+    ... # intial arguments for models
+  compare_models:
+    include:
+      - 'lr'  # linear regression
+      - 'rf'  # random forest regressor
+      - 'sklearn.svm.SVR'
+      - 'interpret.glassbox.ExplainableBoostingRegressor'
+    cross_validation: true
+    n_select: 2
+  plots:
+    - error
+    - residuals
 ```
 
 Such a recipe can then be executed with `springtime` command in a terminal:
 
 ```bash
-springtime run recipe_syringa.yaml
+springtime model_comparison_usecase.yaml
 ```
 
-We provide several "recipes" for downloading data from various sources.
-See "Datasets"
-[documentation](https://springtime.readthedocs.io/en/latest/datasets/).
-
+We provide several "recipes" for running
+[experiments](https://springtime.readthedocs.io/en/latest/experiments/).
 <!--recipe-end-->
 
 <!--api-start-->
@@ -131,6 +162,8 @@ See "Datasets"
 Springtime is written in Python (with parts in R) and can also be used in an
 interactive (IPython/Jupyter) session. For example:
 
+#### Downloading data
+
 ```Python
 from springtime.datasets.PEP725Phenor import PEP725Phenor
 dataset = PEP725Phenor(species='Syringa vulgaris')
@@ -141,5 +174,4 @@ df = dataset.load()
 We provide several notebooks for downloading data from various sources.
 See "Datasets"
 [documentation](https://springtime.readthedocs.io/en/latest/datasets/).
-
 <!--api-end-->
diff --git a/docs/data_recipes.md b/docs/data_recipes.md
@@ -0,0 +1,56 @@
+<!--
+SPDX-FileCopyrightText: 2023 Springtime authors
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+We provide several "recipes" for downloading data from various sources and
+executing a range of ML methods with it.
+Note that a "recipe" is a file with `yaml` extension.
+
+??? example "Daymet recipe"
+    ```yaml
+    {% include "../tests/recipes/daymet.yaml" %}
+    ```
+
+
+??? example "EOBS recipe"
+    ```yaml
+    {% include "../tests/recipes/eobs.yaml" %}
+    ```
+
+
+??? example "MODIS recipe"
+    ```yaml
+    {% include "../tests/recipes/modis.yaml" %}
+    ```
+
+
+??? example "NPN recipe"
+    ```yaml
+    {% include "../tests/recipes/NPN.yaml" %}
+    ```
+
+
+??? example "PEP recipe"
+    ```yaml
+    {% include "../tests/recipes/pep725.yaml" %}
+    ```
+
+
+??? example "PhenoCam recipe"
+    ```yaml
+    {% include "../tests/recipes/phenocam.yaml" %}
+    ```
+
+
+??? example "PPO recipe"
+    ```yaml
+    {% include "../tests/recipes/ppo.yaml" %}
+    ```
+
+
+??? example "PyPhenology recipe"
+    ```yaml
+    {% include "../tests/recipes/pyphenology.yaml" %}
+    ```
diff --git a/docs/models.md b/docs/models.md
@@ -0,0 +1,15 @@
+<!--
+SPDX-FileCopyrightText: 2023 Springtime authors
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+Springtime executes machine learning algorithms that are supported by the
+package [PyCaret](https://pycaret.readthedocs.io/). PyCaret is a Python wrapper
+around several machine learning libraries and frameworks such as
+[scikit-learn](https://scikit-learn.org/stable/), and
+[XGBoost](https://xgboost.readthedocs.io/en/latest/). In addition, springtime
+supports [mixed effects random forest
+(MERF)](https://manifoldai.github.io/merf/) and Glassbox Models from
+[InterpretML](https://interpret.ml/docs/intro.html).
+<!-- see PR #137 -->
diff --git a/docs/recipes.md b/docs/recipes.md
@@ -4,53 +4,14 @@ SPDX-FileCopyrightText: 2023 Springtime authors
 SPDX-License-Identifier: Apache-2.0
 -->
 
-We provide several "recipes" for downloading data from various sources and
-executing a range of ML methods with it.
-Note that a "recipe" is a file with `yaml` extension.
-
-??? example "Daymet recipe"
-    ```yaml
-    {% include "../tests/recipes/daymet.yaml" %}
-    ```
-
-
-??? example "EOBS recipe"
-    ```yaml
-    {% include "../tests/recipes/eobs.yaml" %}
-    ```
-
-
-??? example "MODIS recipe"
-    ```yaml
-    {% include "../tests/recipes/modis.yaml" %}
-    ```
-
-
-??? example "NPN recipe"
-    ```yaml
-    {% include "../tests/recipes/NPN.yaml" %}
-    ```
-
-
-??? example "PEP recipe"
-    ```yaml
-    {% include "../tests/recipes/pep725.yaml" %}
-    ```
-
-
-??? example "PhenoCam recipe"
-    ```yaml
-    {% include "../tests/recipes/phenocam.yaml" %}
-    ```
-
-
-??? example "PPO recipe"
-    ```yaml
-    {% include "../tests/recipes/ppo.yaml" %}
-    ```
+We provide several "recipes" for downloading [data from various
+sources](https://springtime.readthedocs.io/en/latest/datasets/) and executing a
+range of [machine learning
+methods](https://springtime.readthedocs.io/en/latest/models/) with it.
 
+Note that a "recipe" is a file in [yaml format](https://yaml.org/).
 
-??? example "PyPhenology recipe"
+??? example "Model comparison usecase"
     ```yaml
-    {% include "../tests/recipes/pyphenology.yaml" %}
+    {% include "../src/springtime/recipes/model_comparison_usecase.yaml" %}
     ```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -14,7 +14,7 @@ nav:
       - Getting started:
           - Installation: setup.md
           - Usage: usage.md
-      - Example workflow: notebooks/pk_wishful_workflows.ipynb
+      - Recipes: recipes.md
   - Datasets:
       - Data sources and existing tools: datasets.md
       - Field observations:
@@ -27,7 +27,7 @@ nav:
       - Meteorology:
         - Daymet: notebooks/datasets_daymet.ipynb
         - E-OBS: notebooks/datasets_eobs.ipynb
-      - Available dataset recipes: recipes.md
+  - Models: models.md
   - Developer Guide: develop.md
 
 theme: