Prep for release 2.3.0 (#455)

* Remove .readthedocs.yaml

* Prep for 2.3.0 release

* Use curl + make example in readme work

* Use dict to access forcing and model + case

CHANGELOG.md

@@ -6,10 +6,12 @@ Formatted as described on [https://keepachangelog.com](https://keepachangelog.co
 
 ## [Unreleased]
 
+### [2.3.0] (2024-08-29)
+
 ## Changed
 
-- Use [conda-lock](https://conda.github.io/conda-lock/) to install reproducible conda dependencies. Instead of loosely pinned environment.yml ([#442](https://github.com/eWaterCycle/ewatercycle/pull/442))
-- Esmvaltool is no longer a Python dependency, but a conda dependency ([#442](https://github.com/eWaterCycle/ewatercycle/pull/442))
+- Use [conda-lock](https://conda.github.io/conda-lock/) to install reproducible conda dependencies. Instead of loosely pinned environment.yml ([#357](https://github.com/eWaterCycle/ewatercycle/issues/357))
+- ESMValTool is no longer a Python dependency, but a conda dependency ([#442](https://github.com/eWaterCycle/ewatercycle/pull/442))
 
 ### [2.2.0] (2024-07-08)
 
@@ -255,7 +257,8 @@ Everthing listed at [2.0.0](2.0.0), but without the adding models part.
 - Empty Python project directory structure
 - Added symlink based data files copier
 
-[Unreleased]: https://github.com/eWaterCycle/ewatercycle/compare/2.2.0...HEAD
+[Unreleased]: https://github.com/eWaterCycle/ewatercycle/compare/2.3.0...HEAD
+[2.3.0]: https://github.com/eWaterCycle/ewatercycle/compare/2.2.0...2.3.0
 [2.2.0]: https://github.com/eWaterCycle/ewatercycle/compare/2.1.1...2.2.0
 [2.1.1]: https://github.com/eWaterCycle/ewatercycle/compare/2.1.0...2.1.1
 [2.1.0]: https://github.com/eWaterCycle/ewatercycle/compare/2.0.0...2.1.0

CONTRIBUTING.md

@@ -83,35 +83,36 @@ your pull request.
 This section is for maintainers of the package.
 
 1. Checkout ``HEAD`` of ``main`` branch with ``git checkout main`` and ``git pull``.
-2. If dependencies have changed then create a new [conda lock](https://conda.github.io/conda-lock/) file with ``conda-lock lock -f pyproject.toml``.
-3. Determine what new version (major, minor or patch) to use. Package uses `semantic versioning <https://semver.org>`_.
-4. Set new version in ``pyproject.toml`` file in project section.
-5. Update CHANGELOG.md with changes between current and new version. (Don't forget to also update the links at the bottom of the file)
-6. Make sure pre-commit hooks are green for all files by running ``pre-commit run --all-files``.
-7. Make sure types are correct by running ``mypy``.
-8. Make sure all tests passed by running ``pytest``.
-9. Commit & push changes to GitHub.
-10. Wait for [GitHub
+1. Determine what new version (major, minor or patch) to use. Package uses `semantic versioning <https://semver.org>`_.
+1. Because main branch is protected, you need to create a new branch with ``git checkout -b release-<version>``.
+1. If dependencies have changed then create a new [conda lock](https://conda.github.io/conda-lock/) file with ``conda-lock lock -f pyproject.toml``.
+1. Set new version in ``pyproject.toml`` file in project section.
+1. Update CHANGELOG.md with changes between current and new version. (Don't forget to also update the links at the bottom of the file)
+1. Make sure pre-commit hooks are green for all files by running ``pre-commit run --all-files``.
+1. Make sure types are correct by running ``mypy``.
+1. Make sure all tests passed by running ``pytest``.
+1. Commit & push changes to GitHub.
+1. Create a pull request, review it, wait for actions to be green and merge the pull request.
+1. Wait for [GitHub
     actions](https://github.com/eWaterCycle/ewatercycle/actions?query=branch%3Amain+)
-    to be completed and green.
-
-11. Create a [GitHub release](https://github.com/eWaterCycle/ewatercycle/releases/new)
+    on main branch to be completed and green.
+1. Create a [GitHub release](https://github.com/eWaterCycle/ewatercycle/releases/new)
 
     - Use version as title and tag version.
     - As description use intro text from README.md (to give context to
         Zenodo record) and changes from CHANGELOG.md
 
-12. Verify
+1. Verify
 
     1. Has [new Zenodo
         record](https://zenodo.org/search?page=1&size=20&q=ewatercycle)
         been created?
-    2. Has [stable
+    1. Has [stable
         ReadTheDocs](https://ewatercycle.readthedocs.io/en/stable/) been
         updated?
-    3. Has the [Github publish action](https://github.com/eWaterCycle/ewatercycle/actions/workflows/python-publish.yml)
+    1. Has the [Github publish action](https://github.com/eWaterCycle/ewatercycle/actions/workflows/python-publish.yml)
         successfully uploaded the archives to [PyPI](https://pypi.org/project/ewatercycle/)?
-    4. Can new version be installed with pip using
+    1. Can new version be installed with pip using
         `pip3 install ewatercycle==<new version>`?
 
-13. Celebrate
+1. Celebrate

README.md

@@ -37,7 +37,7 @@ generate forcing data. It is preferred to create a Conda environment to
 install those dependencies:
 
 ```shell
-wget https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/conda-lock.yml
+curl -o conda-lock.yml https://raw.githubusercontent.com/eWaterCycle/ewatercycle/main/conda-lock.yml
 conda install mamba conda-lock -n base -c conda-forge -y
 conda-lock install --no-dev -n ewatercycle
 conda activate ewatercycle
@@ -52,7 +52,7 @@ pip install ewatercycle
 The ewatercycle package ships without any models. Models are packaged in [plugins](https://ewatercycle.readthedocs.io/en/latest/plugins.html). To install all endorsed plugins use
 
 ```shell
-pip install ewatercycle-hype ewatercycle-lisflood ewatercycle-marrmot ewatercycle-pcrglobwb ewatercycle-wflow  ewatercycle-leakybucket
+pip install ewatercycle-hype ewatercycle-lisflood ewatercycle-marrmot ewatercycle-pcrglobwb ewatercycle-wflow ewatercycle-leakybucket
 ```
 
 Besides installing software you will need to create a configuration
@@ -65,60 +65,86 @@ for instructions.
 
 Example using the [Marrmot M14
 (TOPMODEL)](https://github.com/wknoben/MARRMoT/blob/master/MARRMoT/Models/Model%20files/m_14_topmodel_7p_2s.m)
-hydrological model on Merrimack catchment to generate forcing, run it
+hydrological model on Rhine catchment to generate forcing, run it
 and produce a hydrograph.
 
+<details>
+
+<summary>
+In condensed code:
+
+```python
+forcing = ewatercycle.forcing.sources['MarrmotForcing'].generate(...)
+model = ewatercycle.models.sources['MarrmotM14'](forcing)
+model.setup(...)
+model.initialize()
+while (model.time < model.end_time):
+    model.update()
+    value = model.get_value_as_xarray('flux_out_Q')
+model.finalize()
+ewatercycle.analysis.hydrograph(...)
+```
+
+</summary>
+In real code:
+
 ```python
-import pandas as pd
 import ewatercycle.analysis
 import ewatercycle.forcing
 import ewatercycle.models
 import ewatercycle.observation.grdc
+from ewatercycle.testing.fixtures import rhine_shape
+import shapefile
+import pandas as pd
 
-forcing = ewatercycle.forcing.generate(
-    target_model='marrmot',
+forcing = ewatercycle.forcing.sources['MarrmotForcing'].generate(
     dataset='ERA5',
     start_time='2010-01-01T00:00:00Z',
     end_time='2010-12-31T00:00:00Z',
-    shape='Merrimack/Merrimack.shp'
+    shape=rhine_shape()
 )
 
-model = ewatercycle.models.MarrmotM14(version="2020.11", forcing=forcing)
+model = ewatercycle.models.sources['MarrmotM14'](version='2020.11', forcing=forcing)
 
 cfg_file, cfg_dir = model.setup(
     threshold_flow_generation_evap_change=0.1,
-    leakage_saturated_zone_flow_coefficient=0.99,
-    zero_deficit_base_flow_speed=150.0,
-    baseflow_coefficient=0.3,
-    gamma_distribution_phi_parameter=1.8
 )
 
 model.initialize(cfg_file)
 
-observations_df = ewatercycle.observation.grdc.get_grdc_data(
-    station_id=4147380,
-    start_time=model.start_time_as_isostr,
-    end_time=model.end_time_as_isostr,
-    column='observation',
-).observation.to_dataframe()
+# flux_out_Q unit conversion factor from mm/day to m3/s
+sf = shapefile.Reader(rhine_shape())
+area = sf.record(0)['SUB_AREA'] * 1e6 # from shapefile in m2
+conversion_mmday2m3s = 1 / (1000 * 24 * 60 * 60)
+conversion = conversion_mmday2m3s * area
 
 simulated_discharge = []
-timestamps = []
 while (model.time < model.end_time):
     model.update()
-    value = model.get_value('flux_out_Q')[0]
-    # flux_out_Q unit conversion factor from mm/day to m3/s
-    area = 13016500000.0  # from shapefile in m2
-    conversion_mmday2m3s = 1 / (1000 * 24 * 60 * 60)
-    simulated_discharge.append(value * area * conversion_mmday2m3s)
-    timestamps.append(model.time_as_datetime.date())
-simulated_discharge_df = pd.DataFrame({'simulated': simulated_discharge}, index=pd.to_datetime(timestamps))
+    simulated_discharge.append(
+        model.get_value_as_xarray('flux_out_Q')
+    )
+
+observations_ds = ewatercycle.observation.grdc.get_grdc_data(
+    station_id=6335020,  # Rees, Germany
+    start_time=model.start_time_as_isostr,
+    end_time=model.end_time_as_isostr,
+    column='observation',
+)
+
+# Combine the simulated discharge with the observations
+sim_da = xr.concat(simulated_discharge, dim='time') * conversion
+sim_da.name = 'simulated'
+discharge = xr.merge([sim_da, observations_ds["observation"]]).to_dataframe()
+discharge= discharge[["observation", "simulated"]].dropna()
 
 ewatercycle.analysis.hydrograph(simulated_discharge_df.join(observations_df), reference='observation')
 
 model.finalize()
 ```
 
+</details>
+
 More examples can be found in the plugins listed in the
 [documentation](https://ewatercycle.readthedocs.io/en/latest/plugins.html).