Improve documentation (#560)

pastas · Feb 21, 2023 · cf48f09 · cf48f09
1 parent 29ef2f9
commit cf48f09
Show file tree

Hide file tree

Showing 34 changed files with 170 additions and 83 deletions.
diff --git a/README.rst b/README.rst
@@ -79,6 +79,7 @@ To get the latest development version, use::
 Related packages
 ~~~~~~~~~~~~~~~~
 - `Pastastore <https://github.com/pastas/pastastore>`_ is a Python package for managing multiple timeseries and pastas models
+- `Metran <https://github.com/pastas/metran>`_ is a Python package to perform multivariate timeseries analysis using a technique called dynamic factor modelling.
 - `Hydropandas <https://github.com/ArtesiaWater/hydropandas/blob/master/examples/03_hydropandas_and_pastas.ipynb>`_ can be used to obtain Dutch timeseries (KNMI, Dinoloket, ..)
 - `PyEt <https://github.com/phydrus/pyet>`_ can be used to compute potential evaporation from meteorological variables.
 

diff --git a/doc/about/01_history.rst b/doc/about/01_history.rst
diff --git a/doc/about/03_citing.rst → doc/about/citing.rst b/doc/about/03_citing.rst → doc/about/citing.rst
diff --git a/doc/about/04_onsite_course.rst → doc/about/courses.rst b/doc/about/04_onsite_course.rst → doc/about/courses.rst
@@ -1,10 +1,9 @@
-On-site-courses
-===============
+Courses
+=======
 
-Every now and then on-site Pastas courses are held. Please check the `GitHub Discussion <https://github
+Every now and then (on-site) Pastas courses and workshops are held. Please check the `GitHub Discussion <https://github
 .com/pastas/pastas/discussions>`_ page for announcements of any public Pastas courses to be held. We can also provide
 private courses on request. To organize such a workshop please contact of the following.
 
 - For courses in the Netherlands, please contact Artesia (info[AT]artesia-water.nl)
 - For international courses, please contact Raoul Collenteur (Raoul.Collenteur[AT]eawag.ch)
-
diff --git a/doc/about/history.rst b/doc/about/history.rst
@@ -0,0 +1,47 @@
+History
+=======
+
+The Development of Pastas started in the spring of 2016 at the TU Delft and
+Artesia in the Netherlands. Researchers at the TU Delft required a flexible
+framework that could support future research on time series analysis of
+groundwater data. Consulting company `Artesia <https://www.artesia-water.nl>`_
+on the other hand, needed a tool that allowed them to perform more complex
+analyses in a scripted environment. As such, Pastas was developed under a
+fruitful partnership between academia and private industry, a collaboration
+that continues to this day.
+
+.. figure:: ./../_static/history_initial.jpg
+    :figwidth: 600px
+
+    Drawing the initial design of Pastas on a whiteboard (5th of April, 2016)
+
+Python was chosen as the programming language for Pastas, being a flexible and
+open-source language that allows for quick prototyping. Moreover, many if not
+most hydrologists learn Python during their education, making the software
+available to many. From the start, all code was made completely open-source
+under MIT license, embracing open science and FAIR (Findability, Accessibility,
+Interoperability, and Reuse) data practices.
+
+International use of Pastas and research grew substantially after the
+publication of the Pastas article in the international journal Groundwater
+:cite:p:`collenteur_pastas_2019`. In addition, the University of Graz in
+Austria and now the Swiss research institute Eawag employed one of the
+maintainers, further pushing the international use and development of Pastas.
+Since its inception, Pastas has been applied in over a dozen countries
+worldwide. Supporting international research continues to be an important goal
+of Pastas. For a list of peer-reviewed publications using Pastas please see the
+:doc:`Publications page <publications>`.
+
+Pastas 1.0
+----------
+
+In february 2023, Pastas version 1.0 was released, the celebration of 7 years
+of research and development of Pastas. Pastas was already operational for a
+couple of years, but the a lot of features were still changing. In Pastas 1.0
+focus lies on Pastas main goal: time series analysis on groundwater levels.
+This was done by improving the documentation, removing unused features,
+unifying the API and relying more on high quality Python packages such as
+Pandas, NumPy and Numba. With version 1.0, Pastas is ready for further future
+developments!
+
+
diff --git a/doc/about/index.rst b/doc/about/index.rst
@@ -19,7 +19,12 @@ and their real-world applications.
 
 .. toctree::
     :hidden:
-    :maxdepth: 4
-    :glob:
+    :maxdepth: 1
 
-    ./*
+    history
+    team
+    related
+    citing
+    courses
+    publications
+    references
diff --git a/doc/about/05_publications.rst → doc/about/publications.rst b/doc/about/05_publications.rst → doc/about/publications.rst
diff --git a/doc/about/06_references.rst → doc/about/references.rst b/doc/about/06_references.rst → doc/about/references.rst
diff --git a/doc/about/related.rst b/doc/about/related.rst
@@ -0,0 +1,38 @@
+Related Packages
+================
+
+Pastas has grown in to a full `GitHub organisation
+<https://github.com/pastas>`_ with many useful tools to complement and improve
+the time series analysis experience. Important packages are:
+
+PastaStore
+----------
+
+`PastaStore <https://github.com/pastas/pastastore>`_ is a module that stores
+Pastas time series and models in a database. Storing time series and models in
+a database allows the user to manage time series and Pastas models on disk,
+which allows the user to pick up where they left off without having to reload
+everything. Additionally, PastaStore has a lot of tools to plot time series
+(spatially).
+
+Metran
+------
+
+While Pastas can only do univariate time series analysis, `Metran
+<https://github.com/pastas/metran>`_ can perform multivariate timeseries
+analysis using a technique called dynamic factor modelling. It can be used to
+describe the variation among many variables in terms of a few underlying but
+unobserved variables called factors.
+
+Others
+------
+
+There are also related packages which are not part of the Pastas organisation
+but depend on Pastas or can be of interest for users for their time series
+analysis workflow:
+
+* `traval <https://github.com/ArtesiaWater/traval>`_ for applying automatic error detection schemes to timeseries
+* `pyet <https://github.com/pyet-org/pyet>`_ for estimating potential/reference evaporation
+* `hydropandas <https://github.com/ArtesiaWater/traval>`_ for (automatically) loading observation data and time series from Dutch datasets
+* `SPEI <https://github.com/martinvonk/spei>`_ for calculating drought indices for time series such as the SPI, SPEI and SGI
+
diff --git a/doc/about/02_team.rst → doc/about/team.rst b/doc/about/02_team.rst → doc/about/team.rst
diff --git a/doc/developers/index.rst b/doc/developers/index.rst
@@ -8,10 +8,12 @@ serves to document code conventions and quick how-to's for maintainers and devel
 
 .. toctree::
     :maxdepth: 1
-    :glob:
     :hidden:
 
-    ./*
+    code_style
+    contributing
+    new_release
+    roadmap
 
 Bug reports / Feature requests
 ------------------------------

diff --git a/doc/examples/04_adding_rivers.ipynb → doc/examples/adding_rivers.ipynb b/doc/examples/04_adding_rivers.ipynb → doc/examples/adding_rivers.ipynb
diff --git a/doc/examples/07_adding_trends.ipynb → doc/examples/adding_trends.ipynb b/doc/examples/07_adding_trends.ipynb → doc/examples/adding_trends.ipynb
diff --git a/doc/examples/05_adding_wells.ipynb → doc/examples/adding_wells.ipynb b/doc/examples/05_adding_wells.ipynb → doc/examples/adding_wells.ipynb
diff --git a/doc/examples/01_basic_model.ipynb → doc/examples/basic_model.ipynb b/doc/examples/01_basic_model.ipynb → doc/examples/basic_model.ipynb
@@ -262,7 +262,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.15 | packaged by conda-forge | (main, Nov 22 2022, 08:41:22) [MSC v.1929 64 bit (AMD64)]"
+   "version": "3.9.15"
   },
   "vscode": {
    "interpreter": {

diff --git a/doc/examples/03_calibration_options.ipynb → doc/examples/calibration_options.ipynb b/doc/examples/03_calibration_options.ipynb → doc/examples/calibration_options.ipynb
diff --git a/doc/examples/08_changing_responses.ipynb → doc/examples/changing_responses.ipynb b/doc/examples/08_changing_responses.ipynb → doc/examples/changing_responses.ipynb
diff --git a/doc/examples/13_comparing_models.ipynb → doc/examples/comparing_models.ipynb b/doc/examples/13_comparing_models.ipynb → doc/examples/comparing_models.ipynb
diff --git a/doc/examples/14_diagnostic_checking.ipynb → doc/examples/diagnostic_checking.ipynb b/doc/examples/14_diagnostic_checking.ipynb → doc/examples/diagnostic_checking.ipynb
diff --git a/doc/examples/02_fix_parameters.ipynb → doc/examples/fix_parameters.ipynb b/doc/examples/02_fix_parameters.ipynb → doc/examples/fix_parameters.ipynb
diff --git a/doc/examples/index.rst b/doc/examples/index.rst
@@ -10,7 +10,27 @@ on the `examples directory on GitHub <https://github.com/pastas/pastas/tree/mast
     :hidden:
     :glob:
 
-    ./*
+    prepare_timeseries
+    basic_model
+    fix_parameters
+    calibration_options
+    adding_rivers
+    adding_wells
+    multiple_wells
+    adding_trends
+    changing_responses
+    threshold_non_linear
+    non_linear_recharge
+    recharge_estimation
+    snowmodel
+    comparing_models
+    diagnostic_checking
+    timestep_analysis
+    uncertainty
+    uncertainty_emcee
+    standardized_groundwater_index
+    signatures
+
 
 Basics
 ------
@@ -23,10 +43,10 @@ Basics
 
 `Calibration`_
 
-.. _Preprocessing user-provided time series: 00_prepare_timeseries.ipynb
-.. _A basic model: 01_basic_model.ipynb
-.. _Fixating parameters while fitting: 02_fix_parameters.ipynb
-.. _Calibration: 03_calibration_options.ipynb
+.. _Preprocessing user-provided time series: prepare_timeseries.ipynb
+.. _A basic model: basic_model.ipynb
+.. _Fixating parameters while fitting: fix_parameters.ipynb
+.. _Calibration: calibration_options.ipynb
 
 
 Stressmodels
@@ -42,11 +62,11 @@ Stressmodels
 
 `Changing response functions`_
 
-.. _Adding surface water levels: 04_adding_rivers.ipynb
-.. _Adding pumping wells: 05_adding_wells.ipynb
-.. _Adding multiple wells: 06_multiple_wells.ipynb
-.. _Adding trends: 07_adding_trends.ipynb
-.. _Changing response functions: 08_changing_responses.ipynb
+.. _Adding surface water levels: adding_rivers.ipynb
+.. _Adding pumping wells: adding_wells.ipynb
+.. _Adding multiple wells: multiple_wells.ipynb
+.. _Adding trends: adding_trends.ipynb
+.. _Changing response functions: changing_responses.ipynb
 
 Non-linear (Recharge) Models
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -59,30 +79,30 @@ Non-linear (Recharge) Models
 
 `Modeling snow`_
 
-.. _Threshold non-linearities: 09_threshold_non_linear.ipynb
-.. _Non-linear recharge models: 10_non_linear.ipynb
-.. _Estimating recharge: 11_recharge_estimation.ipynb
-.. _Modeling snow: 12_snowmodel.ipynb
+.. _Threshold non-linearities: threshold_non_linear.ipynb
+.. _Non-linear recharge models: non_linear_recharge.ipynb
+.. _Estimating recharge: recharge_estimation.ipynb
+.. _Modeling snow: snowmodel.ipynb
 
 
 Model Evaluation
 ----------------
 
 `Comparing models visually`_
 
-`Diagnostics checking`_
+`Diagnostic checking`_
 
 `Reducing autocorrelation`_
 
 `Uncertainty quantification`_
 
 `MCMC uncertainty`_
 
-.. _Comparing models visually: 13_comparing_models.ipynb
-.. _Diagnostics checking: 14_diagnostics_checking.ipynb
-.. _`Reducing autocorrelation`: 15_timestep_analysis.ipynb
-.. _Uncertainty quantification: 16_uncertainty.ipynb
-.. _MCMC uncertainty: 17_emcee_uncertainty.ipynb
+.. _Comparing models visually: comparing_models.ipynb
+.. _Diagnostic checking: diagnostic_checking.ipynb
+.. _`Reducing autocorrelation`: timestep_analysis.ipynb
+.. _Uncertainty quantification: uncertainty.ipynb
+.. _MCMC uncertainty: uncertainty_emcee.ipynb
 
 
 Applications
@@ -92,5 +112,17 @@ Applications
 
 `Groundwater signatures`_
 
-.. _Standardized Groundwater Index: 18_sgi_example.ipynb
-.. _Groundwater signatures: 19_signatures.ipynb
+.. _Standardized Groundwater Index: standardized_groundwater_index.ipynb
+.. _Groundwater signatures: signatures.ipynb
+
+
+STOWA Manual (Dutch only)
+-------------------------
+
+In 2021 the STOWA published a manual on time series analysis. This manual has
+some general notebooks on preprocessing data, model structure, calibration and
+assessment with Pastas. There are also more case-specific notebooks available
+on determining stresses, characteristics, system analysis and predicting. The
+notebooks (currently Dutch only) can be found `here
+<https://github.com/ArtesiaWater/stowa_handleiding_tijdreeksanalyse>`_.
+
diff --git a/doc/examples/06_multiple_wells.ipynb → doc/examples/multiple_wells.ipynb b/doc/examples/06_multiple_wells.ipynb → doc/examples/multiple_wells.ipynb
diff --git a/doc/examples/10_non_linear_recharge.ipynb → doc/examples/non_linear_recharge.ipynb b/doc/examples/10_non_linear_recharge.ipynb → doc/examples/non_linear_recharge.ipynb
diff --git a/doc/examples/00_prepare_timeseries.ipynb → doc/examples/prepare_timeseries.ipynb b/doc/examples/00_prepare_timeseries.ipynb → doc/examples/prepare_timeseries.ipynb
@@ -136,7 +136,7 @@
     "series = pd.Series(data=np.arange(10.0), index=range(10), name=\"Stress\")\n",
     "\n",
     "# Here's error message returned by Pastas\n",
-    "ps.validate_stress(series)"
+    "# ps.validate_stress(series)"
    ]
   },
   {

diff --git a/doc/examples/11_recharge_estimation.ipynb → doc/examples/recharge_estimation.ipynb b/doc/examples/11_recharge_estimation.ipynb → doc/examples/recharge_estimation.ipynb
diff --git a/doc/examples/19_signatures.ipynb → doc/examples/signatures.ipynb b/doc/examples/19_signatures.ipynb → doc/examples/signatures.ipynb
diff --git a/doc/examples/12_snowmodel.ipynb → doc/examples/snowmodel.ipynb b/doc/examples/12_snowmodel.ipynb → doc/examples/snowmodel.ipynb
@@ -6,7 +6,7 @@
    "id": "9f197b14",
    "metadata": {},
    "source": [
-    "# Snow\n",
+    "# Modeling snow\n",
     "*R.A. Collenteur, University of Graz / Eawag, November 2021*\n",
     "\n",
     "In this notebook it is shown how to account for snowfall and smowmelt on groundwater recharge and groundwater levels, using a degree-day snow model. This notebook is work in progress and will be extended in the future."

diff --git a/doc/examples/18_sgi_example.ipynb → ...ples/standardized_groundwater_index.ipynb b/doc/examples/18_sgi_example.ipynb → ...ples/standardized_groundwater_index.ipynb
diff --git a/doc/examples/09_threshold_non_linear.ipynb → doc/examples/threshold_non_linear.ipynb b/doc/examples/09_threshold_non_linear.ipynb → doc/examples/threshold_non_linear.ipynb
diff --git a/doc/examples/15_timestep_analysis.ipynb → doc/examples/timestep_analysis.ipynb b/doc/examples/15_timestep_analysis.ipynb → doc/examples/timestep_analysis.ipynb
diff --git a/doc/examples/16_uncertainty.ipynb → doc/examples/uncertainty.ipynb b/doc/examples/16_uncertainty.ipynb → doc/examples/uncertainty.ipynb
diff --git a/doc/examples/17_emcee_uncertainty.ipynb → doc/examples/uncertainty_emcee.ipynb b/doc/examples/17_emcee_uncertainty.ipynb → doc/examples/uncertainty_emcee.ipynb
diff --git a/doc/index.rst b/doc/index.rst
@@ -2,11 +2,11 @@ Introduction
 ============
 
 Pastas is an open source Python package to analyse hydro(geo)logical time
-series. The objective of Pastas is twofold: to provide a scientific
-framework to develop and test new methods, and to provide a reliable
-ready‐to‐use software tool for groundwater practitioners. All code is
-available from the `Pastas GitHub <https://github.com/pastas/pastas>`_. Want
-to contribute to the project? Check out the :doc:`Developers <developers/index>` section.
+series. The objective of Pastas is twofold: to provide a scientific framework
+to develop and test new methods, and to provide a reliable ready‐to‐use
+software tool for groundwater practitioners. All code is available from the
+`Pastas GitHub <https://github.com/pastas/pastas>`_. Want to contribute to the
+project? Check out the :doc:`Developers <developers/index>` section.
 
 .. grid::
 
@@ -38,13 +38,14 @@ to contribute to the project? Check out the :doc:`Developers <developers/index>`
         Want to contribute to Pastas? Find resources and guides for developers here.
 
     .. grid-item-card:: Publications
-        :link: about/05_publications
+        :link: about/publications
         :link-type: doc
 
         Find an overview of scientific peer-reviewed studies that used Pastas.
 
     .. grid-item-card:: More Pastas
-        :link: https://github.com/pastas/
+        :link: about/organisation
+        :link-type: doc
 
         Find out more useful resources developed by the Pastas community!
 
@@ -85,8 +86,8 @@ Quick Example
 Using Pastas? Please cite us!
 -----------------------------
 
-If you find Pastas useful and use it in your research or project, we kindly
-ask you to cite the Pastas article published in Groundwater journal as follows:
+If you find Pastas useful and use it in your research or project, we kindly ask
+you to cite the Pastas article published in Groundwater journal as follows:
 
 - Collenteur, R.A., Bakker, M., Caljé, R., Klop, S.A., Schaars, F. (2019)
   `Pastas: open source software for the analysis of groundwater time series.
@@ -103,5 +104,3 @@ ask you to cite the Pastas article published in Groundwater journal as follows:
     Benchmarks <benchmarks/index>
     Developers <developers/index>
     About <about/index>
-
-
diff --git a/tests/test_notebooks.py b/tests/test_notebooks.py
@@ -26,8 +26,8 @@ def test_notebook(file) -> None:
 
     os.chdir(pathname)
     if file not in [
-        "00_prepare_timeseries.ipynb",
-        "12_emcee_uncertainty.ipynb",
+        "prepare_timeseries.ipynb",
+        "emcee_uncertainty.ipynb",
     ]:
         try:
             # run autotest on each notebook