Merge branch 'main' into obs

DHI · Mar 20, 2024 · 9c6cb0e · 9c6cb0e
2 parents 45f041e + 42823e3
commit 9c6cb0e
Show file tree

Hide file tree

Showing 54 changed files with 889 additions and 321 deletions.
diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
@@ -1,9 +1,12 @@
-name: Build documentation (don't publish)
+name: Build documentation
 
 on:
   push:
-    pull_request:
-      branches: [ main ]
+    branches:    
+      - main
+  pull_request:
+  workflow_dispatch:
+
 
 jobs:
   build:
@@ -23,9 +26,3 @@ jobs:
     
     - name: Mkdocs build
       run: mkdocs build
-
-    - name: Upload documentation
-      uses: actions/upload-artifact@v2
-      with:
-        name: html
-        path: site/
diff --git a/docs/api/comparer.md b/docs/api/comparer.md
@@ -1,26 +1,26 @@
 # Comparer
 
-The `Comparer` class is the main class of the ModelSkill package. It holds the *matched* observation and model data for a *single* observation and has methods for plotting and skill assessment.
+The `Comparer` class is the main class of the ModelSkill package. It is returned by [`match()`](matching.md/#modelskill.match), [`from_matched()`](matching.md/#modelskill.from_matched) or as an element in a [`ComparerCollection`](comparercollection.md). It holds the *matched* observation and model data for a *single* observation and has methods for plotting and skill assessment.
 
 Main functionality:
 
 * selecting/filtering data
-    - `sel()`
-    - `query()`
+    - [`sel()`](#modelskill.Comparer.sel)
+    - [`query()`](#modelskill.Comparer.query)
 * skill assessment
-    - `skill()`
-    - `gridded_skill()` (for track observations)
+    - [`skill()`](#modelskill.Comparer.skill)
+    - [`gridded_skill()`](#modelskill.Comparer.gridded_skill) (for track observations)
 * plotting
-    - `plot.timeseries()`
-    - `plot.scatter()`
-    - `plot.kde()`
-    - `plot.qq()`
-    - `plot.hist()`
-    - `plot.box()`
+    - [`plot.timeseries()`](#modelskill.comparison._comparer_plotter.ComparerPlotter.timeseries)
+    - [`plot.scatter()`](#modelskill.comparison._comparer_plotter.ComparerPlotter.scatter)
+    - [`plot.kde()`](#modelskill.comparison._comparer_plotter.ComparerPlotter.kde)
+    - [`plot.qq()`](#modelskill.comparison._comparer_plotter.ComparerPlotter.qq)
+    - [`plot.hist()`](#modelskill.comparison._comparer_plotter.ComparerPlotter.hist)
+    - [`plot.box()`](#modelskill.comparison._comparer_plotter.ComparerPlotter.box)
 * load/save/export data
-    - `load()`
-    - `save()`
-    - `to_dataframe()`
+    - [`load()`](#modelskill.Comparer.load)
+    - [`save()`](#modelskill.Comparer.save)
+    - [`to_dataframe()`](#modelskill.Comparer.to_dataframe)
 
 
 

diff --git a/docs/api/comparercollection.md b/docs/api/comparercollection.md
@@ -1,6 +1,25 @@
 # ComparerCollection
 
-The `ComparerCollection` is one of the main objects of the `modelskill` package. It is collection of `Comparer` objects and is returned by the `match()` method of the `Model` class. 
+The `ComparerCollection` is one of the main objects of the `modelskill` package. It is a collection of [`Comparer`](comparer.md) objects and created either by the [`match()`](matching.md/#modelskill.match) method, by passing a list of Comparers to the [`ComparerCollection`](comparercollection.md/#modelskill.ComparerCollection) constructor, or by reading a config file using the [`from_config()`](matching.md/#modelskill.from_config) function.
+
+Main functionality:
+
+* selecting/filtering data
+    - `__get_item__()` - get a single Comparer, e.g., `cc[0]` or `cc['obs1']` 
+    - [`sel()`](#modelskill.ComparerCollection.sel)
+    - [`query()`](#modelskill.ComparerCollection.query)
+* skill assessment
+    - [`skill()`](#modelskill.ComparerCollection.skill)
+    - [`mean_skill()`](#modelskill.ComparerCollection.mean_skill)
+    - [`gridded_skill()`](#modelskill.ComparerCollection.gridded_skill) (for track observations)
+* plotting
+    - [`plot.scatter()`](#modelskill.comparison._collection_plotter.ComparerCollectionPlotter.scatter)
+    - [`plot.kde()`](#modelskill.comparison._collection_plotter.ComparerCollectionPlotter.kde)
+    - [`plot.hist()`](#modelskill.comparison._collection_plotter.ComparerCollectionPlotter.hist)
+* load/save/export data
+    - [`load()`](#modelskill.ComparerCollection.load)
+    - [`save()`](#modelskill.ComparerCollection.save)
+
 
 
 ::: modelskill.ComparerCollection

diff --git a/docs/api/matching.md b/docs/api/matching.md
@@ -3,8 +3,8 @@
 A Comparer/ComparerCollection can be created in one of the following ways:
 
 * [`match()`](#modelskill.match) - match observations and model results
-* [`from_matched()`](#modelskill.from_matched) - create a Comparer/ComparerCollection from matched data
-* [`from_config()`](#modelskill.from_config) - create a Comparer/ComparerCollection from a config file
+* [`from_matched()`](#modelskill.from_matched) - create a Comparer from matched data
+* [`from_config()`](#modelskill.from_config) - create a ComparerCollection from a config file
 
 
 ::: modelskill.match

diff --git a/docs/api/model/dummy.md b/docs/api/model/dummy.md
@@ -0,0 +1,3 @@
+# DummyModelResult
+
+::: modelskill.DummyModelResult
diff --git a/docs/api/model/index.md b/docs/api/model/index.md
@@ -1,19 +1,13 @@
 # Model Result
 
-## Types of model results
-
 A model result can either be a simple point/track, or spatial field (e.g. 2d dfsu file) from which data can be *extracted* at the observation positions by spatial interpolation. The following types are available:
 
 * Timeseries
-    - `PointModelResult` - a point result from a dfs0/nc file or a DataFrame
-    - `TrackModelResult` - a track (moving point) result from a dfs0/nc file or a DataFrame
+    - [`PointModelResult`](point.md) - a point result from a dfs0/nc file or a DataFrame
+    - [`TrackModelResult`](track.md) - a track (moving point) result from a dfs0/nc file or a DataFrame
 * SpatialField (extractable)
-    - `GridModelResult` - a spatial field from a dfs2/nc file or a Xarray Dataset
-    - `DfsuModelResult` - a spatial field from a dfsu file
-
-A model result can be created by explicitly invoking one of the above classes or using the `model_result()` function which will return the appropriate type based on the input data (if possible).
-
+    - [`GridModelResult`](grid.md) - a spatial field from a dfs2/nc file or a Xarray Dataset
+    - [`DfsuModelResult`](dfsu.md) - a spatial field from a dfsu file
 
-## model_result()
+A model result can be created by explicitly invoking one of the above classes or using the [`model_result()`](model_result.md) function which will return the appropriate type based on the input data (if possible).
 
-::: modelskill.model_result
diff --git a/docs/api/model/model_result.md b/docs/api/model/model_result.md
@@ -0,0 +1,3 @@
+# model_result()
+
+::: modelskill.model_result
diff --git a/docs/api/model/point.md b/docs/api/model/point.md
@@ -1,3 +1,5 @@
 # PointModelResult
 
-::: modelskill.PointModelResult
+::: modelskill.PointModelResult
+
+::: modelskill.timeseries._plotter.MatplotlibTimeSeriesPlotter
diff --git a/docs/api/model/track.md b/docs/api/model/track.md
@@ -1,3 +1,5 @@
 # TrackModelResult
 
-::: modelskill.TrackModelResult
+::: modelskill.TrackModelResult
+
+::: modelskill.timeseries._plotter.MatplotlibTimeSeriesPlotter
diff --git a/docs/api/observation/index.md b/docs/api/observation/index.md
@@ -2,12 +2,8 @@
 
 ModelSkill supports two types of observations:
 
-* `PointObservation` - a point timeseries from a dfs0/nc file or a DataFrame
-* `TrackObservation` - a track (moving point) timeseries from a dfs0/nc file or a DataFrame
+* [`PointObservation`](point.md) - a point timeseries from a dfs0/nc file or a DataFrame
+* [`TrackObservation`](track.md) - a track (moving point) timeseries from a dfs0/nc file or a DataFrame
 
-An observation can be created by explicitly invoking one of the above classes or using the `observation()` function which will return the appropriate type based on the input data (if possible).
+An observation can be created by explicitly invoking one of the above classes or using the [`observation()`](observation.md) function which will return the appropriate type based on the input data (if possible).
 
-
-## observation()
-
-::: modelskill.observation
diff --git a/docs/api/observation/observation.md b/docs/api/observation/observation.md
@@ -0,0 +1,3 @@
+# observation()
+
+::: modelskill.observation
diff --git a/docs/api/observation/point.md b/docs/api/observation/point.md
@@ -1,3 +1,5 @@
 # PointObservation
 
-::: modelskill.PointObservation
+::: modelskill.PointObservation
+
+::: modelskill.timeseries._plotter.MatplotlibTimeSeriesPlotter
diff --git a/docs/api/observation/track.md b/docs/api/observation/track.md
@@ -1,3 +1,5 @@
 # TrackObservation
 
-::: modelskill.TrackObservation
+::: modelskill.TrackObservation
+
+::: modelskill.timeseries._plotter.MatplotlibTimeSeriesPlotter
diff --git a/docs/images/dhi-white-logo.svg b/docs/images/dhi-white-logo.svg
diff --git a/docs/images/obs_timeseries.png b/docs/images/obs_timeseries.png
diff --git a/docs/images/plot_taylor.png b/docs/images/plot_taylor.png
diff --git a/docs/images/spatial_overview.png b/docs/images/spatial_overview.png
diff --git a/docs/images/temporal_coverage.png b/docs/images/temporal_coverage.png
diff --git a/docs/images/wind_rose.png b/docs/images/wind_rose.png
diff --git a/docs/index.md b/docs/index.md
@@ -2,53 +2,57 @@
 
 
 # ModelSkill: Assess the skill of your MIKE model
+![OS](https://img.shields.io/badge/OS-Windows%20%7C%20Linux-blue)
 ![Python version](https://img.shields.io/pypi/pyversions/modelskill.svg)
 ![PyPI version](https://badge.fury.io/py/modelskill.svg)
+
 
 Compare results from MIKE simulations with observations.
 [ModelSkill](https://github.com/DHI/modelskill) would like to be your
 companion during the different phases of a MIKE modelling workflow.
 
 
-## Installation
+**Useful links**:
+[Terminology](user-guide/terminology.md) |
+[Overview](user-guide/overview.md) |
+[Plotting](user-guide/plotting.md) |
+[Issues](https://github.com/DHI/modelskill/issues) |
+[Discussion](https://github.com/DHI/modelskill/discussions)
+
+
+<div class="grid cards" markdown>
+
+-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+    ---
+
+    Install **ModelSkill** with [`pip`](https://pypi.org/project/modelskill/) and get up
+    and running in minutes
 
-ModelSkill is available as open-source on PyPI and can be installed with pip:
+    [:octicons-arrow-right-24: Getting started](user-guide/getting-started.md)
 
-```bash
-$ pip install modelskill
-```
+-   :fontawesome-brands-python:{ .lg .middle } __It's just Python__
 
-ModelSkill is compatible with Python 3.8 and later versions on Windows and Linux.
+    ---
 
+    Focus on your modelling and less on generate a validation report
 
-## Getting started
+    [:octicons-arrow-right-24: API Reference](api/index.md)
 
-Are your observations and model results already matched? 
+-   :fontawesome-solid-ruler:{ .lg .middle } __Made to measure__
 
-```python
-import modelskill as ms
-cmp = ms.from_matched("matched_data.dfs0", obs_item="obs_WL", mod_item="WL")
-cmp.skill()
-```
+    ---
 
-Or do you need to match the observations and results first?
+    Choose between different skill metrics and customizable tables and charts
 
-```python
-import modelskill as ms
-o = ms.PointObservation("obs.dfs0", item="obs_WL")
-mr = ms.PointModelResult("model.dfs0", item="WL")
-cmp = ms.match(o, mr)
-cmp.skill()
-```
+    [:octicons-arrow-right-24: Metrics](api/metrics.md)
 
-Read more in the [Getting started guide](getting-started.md) or in the [overview](overview.md) of the package.
+-   :material-scale-balance:{ .lg .middle } __Open Source, MIT__
 
+    ---
 
-## Resources
+    ModelSkill is licensed under MIT and available on [GitHub](https://github.com/DHI/modelskill)
 
-- [Documentation](https://dhi.github.io/modelskill/) (this site)
-- [Getting started guide](getting-started.md)
-- [Example notebooks](https://nbviewer.jupyter.org/github/DHI/modelskill/tree/main/notebooks/)
-- [PyPI](https://pypi.org/project/modelskill/)
-- [Source code](https://github.com/DHI/modelskill/)
+    [:octicons-arrow-right-24: License](license.md)
 
+</div>
diff --git a/docs/license.md b/docs/license.md
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DHI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.