From 9b43c69a7420abf538b35b78008e6988bb46ea8b Mon Sep 17 00:00:00 2001 From: SarahAlidoost <55081872+SarahAlidoost@users.noreply.github.com> Date: Fri, 30 Jun 2023 16:20:02 +0200 Subject: [PATCH] Explain experiments and use case recipe in docs (#143) Co-authored-by: Stefan Verhoeven --- README.md | 66 ++++++++++++++++++++++++++++++++------------ docs/data_recipes.md | 56 +++++++++++++++++++++++++++++++++++++ docs/models.md | 15 ++++++++++ docs/recipes.md | 53 +++++------------------------------ mkdocs.yml | 4 +-- 5 files changed, 129 insertions(+), 65 deletions(-) create mode 100644 docs/data_recipes.md create mode 100644 docs/models.md diff --git a/README.md b/README.md index 6e57af76..209354fe 100644 --- 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/). @@ -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/). - diff --git a/docs/data_recipes.md b/docs/data_recipes.md new file mode 100644 index 00000000..bea333b4 --- /dev/null +++ b/docs/data_recipes.md @@ -0,0 +1,56 @@ + + +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" %} + ``` \ No newline at end of file diff --git a/docs/models.md b/docs/models.md new file mode 100644 index 00000000..a9c9b01a --- /dev/null +++ b/docs/models.md @@ -0,0 +1,15 @@ + + +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). + \ No newline at end of file diff --git a/docs/recipes.md b/docs/recipes.md index bea333b4..fcce5c18 100644 --- 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" %} ``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index d9da436f..c0989cff 100644 --- 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: