Update Master branch to Pastas 1.3.0 (#664)

.github/workflows/ci.yml

@@ -14,31 +14,43 @@ jobs:
   test:
     name: ${{ matrix.name }}
     runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental }}
     strategy:
       fail-fast: false
       matrix:
         include:
           - name: Test suite with py38-ubuntu
             python: "3.8"
             toxenv: py38
+            experimental: false
           - name: Test suite with py39-ubuntu
             python: "3.9"
             toxenv: py39
+            experimental: false
           - name: Test suite with py310-ubuntu
             python: "3.10"
             toxenv: py310
+            experimental: false
           - name: Test suite with py311-ubuntu
             python: "3.11"
             toxenv: py311
+            experimental: false
+          - name: Test suite with py312-ubuntu
+            python: "3.12"
+            toxenv: py312
+            experimental: true
           - name: Formatting with black + isort
             python: "3.9"
             toxenv: format
+            experimental: false
           - name: Linting with flake8
             python: "3.9"
             toxenv: lint
+            experimental: false
           - name: Test suite for all unit tests including Notebooks
             python: "3.9"
             toxenv: all
+            experimental: false
     env:
       # Color Output
       # Rich (pip)

.readthedocs.yml → .readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.11"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -25,7 +25,6 @@ sphinx:
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  system_packages: true
   install:
     - method: pip
       path: .

README.rst

@@ -17,10 +17,10 @@ Pastas: Analysis of Groundwater Time Series
    :target: https://pypi.org/project/pastas/
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1465866.svg
    :target: https://doi.org/10.5281/zenodo.1465866
-.. image:: https://api.codacy.com/project/badge/Grade/952f41c453854064ba0ee1fa0a0b4434
-   :target: https://www.codacy.com/gh/pastas/pastas
+.. image:: https://app.codacy.com/project/badge/Grade/952f41c453854064ba0ee1fa0a0b4434
+   :target: https://app.codacy.com/gh/pastas/pastas/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade
 .. image:: https://api.codacy.com/project/badge/Coverage/952f41c453854064ba0ee1fa0a0b4434
-   :target: https://www.codacy.com/gh/pastas/pastas
+   :target: https://app.codacy.com/gh/pastas/pastas/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage9
 .. image:: https://readthedocs.org/projects/pastas/badge/?version=latest
    :target: https://pastas.readthedocs.io/en/latest/?badge=latest
 .. image:: https://mybinder.org/badge_logo.svg

doc/api/index.rst

@@ -19,13 +19,11 @@ left-hand menu you will find the different categories of the API documentation.
     recharge
     solver
     objective_functions
-    modelplots.Plotting
-    modelcompare.CompareModels
+    plotting
     timeseries.TimeSeries
     timeseries_utils
     utils
     timer.SolveTimer
-    plots
     stats
 
 .. toctree::

doc/conf.py

@@ -108,6 +108,10 @@
     "doc_path": "doc",
 }
 
+html_sidebars = {
+    "map": [],  # Test what page looks like with no sidebar items
+}
+
 # -- Napoleon settings ----------------------------------------------------------------
 
 napoleon_include_init_with_doc = False
@@ -119,6 +123,8 @@
     "ml": "pastas.model.Model",
     "TimestampType": "pandas.Timestamp",
 }
+# add custom section to docstrings in Parameters style
+napoleon_custom_sections = [("Time series settings", "params_style")]
 
 # -- Autodoc, autosummary, and autosectionlabel settings ------------------------------
 

doc/developers/contributing.rst

@@ -7,6 +7,19 @@ GitHub, where Pastas is hosted, also has `good tutorials <https://help.github
 .com/en/github/collaborating-with-issues-and-pull-requests>`_ to learn how
 to commit code changes to GitHub open source projects. Let's start!
 
+.. note::
+    If you are new to GitHub, we recommend to first read the `GitHub
+    documentation <https://help.github.com/en/github>`_ to learn how to
+    use GitHub.
+
+0. Pick an Issue
+----------------
+Before you start, it is a good idea to check if there are any issues that you can help 
+with. You can find a list of issues that are open on the `GitHub Issues page 
+<https://github.com/pastas/pastas/labels/good-first-issue>`_` with the tag 
+"good-first-issue". These issues are a good place to start if you are new to Pastas 
+and want to contribute to the project.
+
 1. Create a GitHub Issue
 ------------------------
 Before you start you can start a GitHub Issue describing the changes you

doc/examples/adding_rivers.ipynb

@@ -19,7 +19,6 @@
    "source": [
     "import pandas as pd\n",
     "import pastas as ps\n",
-    "import matplotlib.pyplot as plt\n",
     "\n",
     "ps.show_versions()\n",
     "ps.set_log_level(\"INFO\")"
@@ -92,6 +91,14 @@
     "axes = ml.plots.results(figsize=(12, 8))\n",
     "axes[-1].set_xlim(0, 10);  # By default, the axes between responses are shared."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Normalizing river water levels\n",
+    "It can be helpful to normalize the river water levels by substracting the mean or minimum water level value. Especially, when using a river level that is high above a certain datum (which is not the case in this example)."
+   ]
   }
  ],
  "metadata": {

doc/examples/adding_trends.ipynb

@@ -167,7 +167,7 @@
    },
    "outputs": [],
    "source": [
-    "ci = ml.fit.ci_contribution(\"step\", alpha=0.05)\n",
+    "ci = ml.solver.ci_contribution(\"step\", alpha=0.05)\n",
     "axes = ml.plots.results(adjust_height=False, figsize=(10, 5))\n",
     "axes[-2].fill_between(ci.index, ci.iloc[:, 0], ci.iloc[:, 1], zorder=-10, alpha=0.5);"
    ]

doc/examples/adding_wells.ipynb

@@ -104,7 +104,7 @@
     "As can be seen from the above plot, the observed heads show a clear rise whereas the simulated heads do not show this behaviour. The rise in the heads cannot be explained by an increased precipitation or a decreased evaporation over time, and it is likely another force is driving the heads upwards. Given the location of the well, we can hypothesize that the groundwater pumping caused a lowering of the heads in the beginning of the observations, which decreased when the pumping well was shut down. A next logical step is to add the effect of the pumping well and see if it improves the simulation of the head.\n",
     "\n",
     "## 3. Add the effect of the pumping well\n",
-    "To simulate the effect of the pumping well a new stress model is added. The effect of the well is simulated using the `ps.StressModel`, which convoluted a stress with a response function. As a response function the `ps.Hantush` response function is used. The keyword-argument `up=False` is provided to tell the model this stress is supposed to have a lowering effect on the groundwater levels."
+    "To simulate the effect of the pumping well a new stress model is added. The effect of the well is simulated using the `ps.StressModel`, which convolved a stress with a response function. As a response function the `ps.Hantush` response function is used. The keyword-argument `up=False` is provided to tell the model this stress is supposed to have a lowering effect on the groundwater levels."
    ]
   },
   {

doc/examples/changing_responses.ipynb

@@ -64,7 +64,7 @@
    "source": [
     "## 2. The weighting factor\n",
     "\n",
-    "The stress is convoluted two times with different response functions. Then, a weighting function is used to add the two contributions together and compute the final contribution. "
+    "The stress is convolved two times with different response functions. Then, a weighting function is used to add the two contributions together and compute the final contribution. "
    ]
   },
   {

doc/examples/comparing_models.ipynb

@@ -551,7 +551,7 @@
     "mc.plot_acf(axn=\"acf\")\n",
     "for axlbl in mc.axes:\n",
     "    mc.axes[axlbl].grid(True)\n",
-    "mc.share_xaxes(\n",
+    "ps.plots.share_xaxes(\n",
     "    [\n",
     "        mc.axes[\"ose\"],\n",
     "        mc.axes[\"sim\"],\n",

doc/examples/example_freq_obs.py

@@ -0,0 +1,32 @@
+"""
+This test file is meant for developing purposes. Providing an easy method to
+test the functioning of Pastas during development.
+
+"""
+import pandas as pd
+
+import pastas as ps
+
+ps.set_log_level("INFO")
+
+# read observations and create the time series model
+obs = pd.read_csv("data/head_nb1.csv", index_col=0, parse_dates=True).squeeze("columns")
+
+# Create the time series model
+ml = ps.Model(obs, name="head")
+
+# read weather data
+rain = pd.read_csv("data/rain_nb1.csv", index_col=0, parse_dates=True).squeeze(
+    "columns"
+)
+evap = pd.read_csv("data/evap_nb1.csv", index_col=0, parse_dates=True).squeeze(
+    "columns"
+)
+
+# Create stress
+sm = ps.RechargeModel(prec=rain, evap=evap, rfunc=ps.Exponential(), name="recharge")
+ml.add_stressmodel(sm)
+
+# Solve and only fit on one observation per year
+ml.solve(freq_obs="365D")
+ml.plot()

doc/examples/example_uncertainty.py

@@ -22,7 +22,7 @@
 # Solve
 ml.solve()
 #
-df = ml.fit.prediction_interval()
+df = ml.solver.prediction_interval()
 inside = (obs > df.loc[obs.index, 0.025]) & (obs < df.loc[obs.index, 0.975])
 print("percentage inside:", np.count_nonzero(inside) / len(inside) * 100)
 
@@ -38,7 +38,7 @@
     label="95% Prediction interval",
 )
 axes[0].legend(ncol=3)
-df = ml.fit.ci_contribution("recharge", tmin="2010", tmax="2015")
+df = ml.solver.ci_contribution("recharge", tmin="2010", tmax="2015")
 axes[2].fill_between(
     df.index,
     df.iloc[:, 0],
@@ -49,7 +49,7 @@
     label="95% confidence",
 )
 
-df = ml.fit.ci_step_response("recharge", alpha=0.05, n=1000)
+df = ml.solver.ci_step_response("recharge", alpha=0.05, n=1000)
 axes[3].fill_between(
     df.index,
     df.iloc[:, 0],

doc/examples/multiple_wells.ipynb

@@ -387,7 +387,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ml_wm.plots.stacked_results(figsize=(10, 8), stacklegend=True);"
+    "ml_wm.plots.stacked_results(\n",
+    "    figsize=(10, 8),\n",
+    "    stacklegend=True,\n",
+    "    stackcolors={\"Extraction_2\": \"C1\", \"Extraction_3\": \"C2\"},\n",
+    ");"
    ]
   },
   {
@@ -494,7 +498,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Visually compare the two models, including the calculated contribution of the wells:"
+    "Visually compare the two models, including the calculated contribution of the wells.\n",
+    "\n",
+    "Note that there is some extra code at the bottom to calculate two step responses for the\n",
+    "\"WellModel\" model, for comparison purposes with the \"2-wells\" model."
    ]
   },
   {
@@ -520,7 +527,20 @@
     "mc.axes[\"con1\"].plot(\n",
     "    sumwells.index, sumwells, ls=\"dashed\", color=\"C0\", label=\"sum 2_wells\"\n",
     ")\n",
-    "mc.axes[\"con1\"].legend(loc=(0, 1), frameon=False, ncol=4);"
+    "mc.axes[\"con1\"].legend(loc=(0, 1), frameon=False, ncol=4)\n",
+    "\n",
+    "# remove WellModel response for r=1m and add response twice, scaled with actual\n",
+    "# distances, for comparison with the two responses from the first model\n",
+    "mc.axes[\"rf1\"].lines[-1].remove()  # remove original step response\n",
+    "for istress in range(2):\n",
+    "    # get parameters and distance for istress\n",
+    "    p = ml_wm.stressmodels[\"WellModel\"].get_parameters(istress=istress)\n",
+    "    # calculate step\n",
+    "    step = ml_wm.get_step_response(\"WellModel\", p=p)\n",
+    "    # plot step\n",
+    "    mc.axes[\"rf1\"].plot(step.index, step, color=\"C1\")\n",
+    "# recalculate axes limits\n",
+    "mc.axes[\"rf1\"].relim()"
    ]
   },
   {
@@ -532,8 +552,22 @@
   }
  ],
  "metadata": {
+  "kernelspec": {
+   "display_name": "artesia",
+   "language": "python",
+   "name": "python3"
+  },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
   }
  },
  "nbformat": 4,