Documentation minor tweaks

docs/_quarto.yml

@@ -46,6 +46,7 @@ website:
         - user-guide/matching.qmd
         - user-guide/selecting-data.qmd
         - user-guide/plotting.qmd
+        - user-guide/statistics.qmd
 
     - title: "Examples"
       contents:
@@ -56,9 +57,17 @@ website:
           text: Hydrology Vistula Catchment
         - href: examples/Metocean_track_comparison.qmd
           text: Metocean track comparison
+        - href: examples/Gridded_NetCDF_ModelResult.qmd
+          text: Gridded NetCDF ModelResult
         - href: examples/Prematched_with_auxiliary.qmd
           text: Prematched with auxiliary
-
+        - href: examples/Skill_vs_dummy.qmd
+          text: Compare with dummy results
+        - href: examples/Metrics_custom_metric.qmd
+          text: Custom metric
+        - href: examples/Directional_data_comparison.qmd
+          text: Directional data comparison
+
     - title: "API Reference"
       contents:
         - href: api/index.qmd
@@ -81,6 +90,7 @@ website:
           contents:
             - api/match.qmd
             - api/from_matched.qmd
+            - api/from_config.qmd
         - section: "Comparison"
           href: api/comparison.qmd
           contents:
@@ -89,10 +99,26 @@ website:
               href: api/comparison.ComparerPlotter.qmd
             - api/ComparerCollection.qmd
             - text: "ComparerCollectionPlotter"
-              href: api/comparison.ComparerCollectionPlotter.qmd
+              href: api/comparison.ComparerCollectionPlotter.qmd            
+        - section: "Skill"
+          contents:            
             - api/SkillTable.qmd
+            - text: "SkillArray"
+              href: api/skill.SkillArray.qmd
+            - text: "SkillArrayPlotter"
+              href: api/skill.SkillArrayPlotter.qmd
+            - text: "SkillGrid"
+              href: api/skill_grid.SkillGrid.qmd
+            - text: "SkillGridArray"
+              href: api/skill_grid.SkillGridArray.qmd
         - text: "Plotting"
           href: api/plotting.qmd
+          contents:
+            - api/plotting.scatter.qmd
+            - api/plotting.wind_rose.qmd
+            - api/plotting.taylor_diagram.qmd
+            - api/plotting.spatial_overview.qmd
+            - api/plotting.temporal_coverage.qmd
         - text: "Metrics"
           href: api/metrics.qmd
         - text: "Settings"
@@ -147,7 +173,7 @@ quartodoc:
         - GridModelResult
         - DummyModelResult
     - title: Matching
-      desc: Matching classes and functions
+      desc: Matching functions
       contents:
         - match
         - from_matched
@@ -181,8 +207,16 @@ quartodoc:
             - sel
             - save
             - load
-        - name : comparison.ComparerCollectionPlotter
+        - name: comparison.ComparerCollectionPlotter
+
+    - title: Skill
+      desc: ""
+      contents:
         - name: SkillTable
+        - name: skill.SkillArray
+        - name: skill.SkillArrayPlotter
+        - name: skill_grid.SkillGrid
+        - name: skill_grid.SkillGridArray
 
     - title: Plotting
       desc: ""

docs/api/_metadata.yml

@@ -0,0 +1 @@
+repo-actions: false

docs/api/_styles-quartodoc.css

@@ -1,5 +1,5 @@
 /*
-This file generated automatically by quartodoc version 0.8.0.
+This file generated automatically by quartodoc version 0.9.1.
 Modifications may be overwritten by quartodoc build. If you want to
 customize styles, create a new .css file to avoid losing changes.
 */

docs/examples/Directional_data_comparison.qmd

@@ -0,0 +1,49 @@
+---
+title: Comparing Directional Data (e.g. wind direction)
+jupyter: python3
+---
+
+
+Comparing directional data is easy from version 1.0 if the quantity is defined as directional. This happens automatically if data is loaded from a dfs file with EUM unit in "degrees" or if loaded from a xarray dataset with attribute "units" set to "degrees". The quantity can also be created as directional manually by `ms.Quantity(..., is_directional=True)`.
+
+In the below example, the EUM unit is "degrees".
+
+
+```{python}
+import modelskill as ms
+import mikeio
+```
+
+```{python}
+fn = "../data/wave_dir.dfs0"
+ds = mikeio.read(fn)
+ds
+```
+
+```{python}
+cmp = ms.from_matched(ds, obs_item=3, mod_items=[2])
+cmp
+```
+
+```{python}
+cmp.quantity
+```
+
+Circular metrics are used to compare directional data if the quantity is defined as directional. 
+
+```{python}
+cmp.skill(metrics=["c_rmse","c_max_error"]).round(1)
+```
+
+```{python}
+cmp.plot.timeseries(figsize=(8,5));
+```
+
+```{python}
+cmp.plot.kde();   # note: the KDE estimate is not directional! (yet)
+```
+
+```{python}
+cmp.plot.scatter();  # note: regression line and Q-Q are not shown 
+```
+

docs/examples/Gridded_NetCDF_ModelResult.qmd

@@ -0,0 +1,107 @@
+---
+title: Gridded NetCDF modelresults
+jupyter: python3
+---
+
+
+2D modelresults stored in NetCDF or Grib can be loaded to ModelSkill using xarray. In this way, MIKE 21 modelresults in dfsu format can easily be compared to model results from third party providers often stored in NetCDF. 
+
+
+```{python}
+import xarray as xr
+import modelskill as ms
+```
+
+## Observations
+
+```{python}
+o1 = ms.PointObservation('../data/SW/HKNA_Hm0.dfs0', item=0, x=4.2420, y=52.6887, name="HKNA")
+o2 = ms.PointObservation("../data/SW/eur_Hm0.dfs0", item=0, x=3.2760, y=51.9990, name="EPL")
+o3 = ms.TrackObservation("../data/SW/Alti_c2_Dutch.dfs0", item=3, name="c2")
+```
+
+## MIKE ModelResult
+
+```{python}
+mrMIKE = ms.model_result('../data/SW/HKZN_local_2017_DutchCoast.dfsu', name='MIKE21SW', item=0)
+```
+
+## NetCDF ModelResult
+
+```{python}
+fn = "../data/SW/ERA5_DutchCoast.nc"
+xr.open_dataset(fn)
+```
+
+```{python}
+mrERA5 = ms.model_result(fn, item="swh", name='ERA5')
+```
+
+```{python}
+mrERA5
+```
+
+```{python}
+mrERA5.data  # mr contains the xr.Dataset
+```
+
+## Test extract from XArray
+
+1) Extract point 
+2) Extract track
+
+```{python}
+mrERA5.extract(o1, spatial_method="nearest").data.head()
+```
+
+```{python}
+mrERA5.extract(o3).data.head()
+```
+
+## Multi-file ModelResult
+
+Use mfdataset to load multiple files as a single ModelResult.
+
+```{python}
+fn = "../data/SW/CMEMS_DutchCoast_*.nc"
+mrCMEMS = ms.model_result(fn, item="VHM0", name='CMEMS')
+mrCMEMS
+```
+
+
+## Connect multiple models and observations and extract
+
+```{python}
+ms.plotting.temporal_coverage(obs=[o1,o2,o3], mod=[mrERA5, mrCMEMS, mrMIKE])
+```
+
+```{python}
+# o1 is slightly outside the model domain of mrERA5, 
+# we therefore use "nearest" instead of the default spatial interpolation method  
+cc = ms.match(
+    obs=[o1, o2, o3], 
+    mod=[mrERA5, mrCMEMS, mrMIKE], 
+    spatial_method='nearest',
+)
+```
+
+## Analysis and plotting
+Which model is better? 
+
+```{python}
+sk = cc.skill()
+sk.swaplevel().sort_index(level="observation").style()
+```
+
+```{python}
+sk["urmse"].plot.bar(figsize=(6,3));
+```
+
+```{python}
+cc.mean_skill().style()
+```
+
+```{python}
+cc.plot.taylor(figsize=6)
+```
+

docs/examples/Hydrology_Vistula_Catchment.qmd

@@ -4,7 +4,7 @@ jupyter: python3
 ---
 
 
-The Vistula catchment is the largest catchment in Poland, with an area of 194,424 km2. This notebook shows how a hydrolgoical model can evaluated using ModelSkill.  
+The Vistula catchment is the largest catchment in Poland, with an area of 194,424 km2. This notebook shows how a hydrological model can evaluated using ModelSkill.  
 
 
 ```{python}

docs/examples/MIKE21HD_dfsu.qmd

@@ -16,6 +16,11 @@ mr = ms.model_result('../data/Oresund2D.dfsu',
 mr
 ```
 
+
+```{python}
+mr.data.geometry.plot(cmap="Blues_r");
+```
+
 ```{python}
 mr.data.geometry.projection
 ```
@@ -33,7 +38,7 @@ o1
 Confirm that the observation is correctly located in the model domain.
 
 ```{python}
-ms.plotting.spatial_overview(o1, mr, figsize=(8, 8));
+ms.plotting.spatial_overview(o1, mr, figsize=(4, 4));
 ```
 
 Match the observed data to the model result (interpolate the model result to the observation points).

docs/examples/Metrics_custom_metric.qmd

@@ -0,0 +1,60 @@
+---
+title: Custom Metrics 
+jupyter: python3
+---
+
+ModelSkill comes with many metrics to choose from, but you can also define your own. 
+
+```{python}
+import numpy as np
+import modelskill as ms
+```
+
+```{python}
+fn = '../data/SW/HKZN_local_2017_DutchCoast.dfsu'
+mr = ms.model_result(fn, name='HKZN_local', item=0)
+o1 = ms.PointObservation('../data/SW/HKNA_Hm0.dfs0', item=0, x=4.2420, y=52.6887, name="HKNA")
+o2 = ms.PointObservation("../data/SW/eur_Hm0.dfs0", item=0, x=3.2760, y=51.9990, name="EPL")
+o3 = ms.TrackObservation("../data/SW/Alti_c2_Dutch.dfs0", item=3, name="c2")
+cc = ms.match([o1, o2, o3], mr)
+cc
+```
+
+Standard set of metrics
+
+```{python}
+cc.skill()
+```
+
+Some metrics has parameters, which require a bit special treatment.
+
+```{python}
+from modelskill.metrics import hit_ratio
+
+def hit_ratio_05_pct(obs, model):
+    return hit_ratio(obs, model, 0.5) * 100
+
+def hit_ratio_01_pct(obs, model):
+    return hit_ratio(obs, model, 0.1) * 100
+
+
+cc.skill(metrics=[hit_ratio_05_pct, hit_ratio_01_pct])
+```
+
+And you are always free to specify your own special metric or import metrics from other libraries, e.g. scikit-learn.
+
+```{python}
+def my_special_metric_with_long_descriptive_name(obs, model):
+
+    res = obs - model
+
+    res_clipped = np.clip(res,0,np.inf)
+
+    return np.mean(np.abs(res_clipped))
+
+# short alias to avoid long column names in output
+def mcae(obs, model): return my_special_metric_with_long_descriptive_name(obs, model)
+
+cc.skill(metrics=mcae)
+```
+