Merge pull request #360 from DHI/docs

Twek index / getting started pages

Author: jsmariegaard

README.md

@@ -6,7 +6,7 @@
 
 [ModelSkill](https://github.com/DHI/modelskill) is a python package for scoring [MIKE](https://www.mikepoweredbydhi.com) models (other models can be evaluated as well). 
 
-Read more about the [vision and scope](https://dhi.github.io/modelskill/vision.html). Contribute with new ideas in the [discussion](https://github.com/DHI/modelskill/discussions), report an [issue](https://github.com/DHI/modelskill/issues) or browse the [documentation](https://dhi.github.io/modelskill/). Access observational data (e.g. altimetry data) from the sister library [WatObs](https://github.com/DHI/watobs). 
+Contribute with new ideas in the [discussion](https://github.com/DHI/modelskill/discussions), report an [issue](https://github.com/DHI/modelskill/issues) or browse the [documentation](https://dhi.github.io/modelskill/). Access observational data (e.g. altimetry data) from the sister library [WatObs](https://github.com/DHI/watobs). 
 
 
 ## Use cases
@@ -30,20 +30,21 @@ Or the development version:
 
 ## Example notebooks
 
-* [Quick_and_dirty_compare.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Quick_and_dirty_compare.ipynb)
-* [SW_DutchCoast.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/SW_DutchCoast.ipynb)
-* [Multi_model_comparison.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Multi_model_comparison.ipynb)
+
+* [Hydrology_Vistula_Catchment.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Hydrology_Vistula_Catchment.ipynb)
+* [Metocean_multi_model_comparison.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Metocean_multi_model_comparison.ipynb)
 * [Multi_variable_comparison.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Multi_variable_comparison.ipynb)
-* [Track_comparison.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Track_comparison.ipynb) (including global wave model example)
-* [NetCDF_ModelResult.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/NetCDF_ModelResult.ipynb)
+* [Metocean_track_comparison_global.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Metocean_track_comparison_global.ipynb) 
+* [Gridded_NetCDF_ModelResult.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Gridded_NetCDF_ModelResult.ipynb)
+* [Directional_data_comparison.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Directional_data_comparison.ipynb)
 * [Combine_comparers.ipynb](https://nbviewer.jupyter.org/github/DHI/modelskill/blob/main/notebooks/Combine_comparers.ipynb)
 
 
 ## Workflow
 
 1. Define **ModelResults**
 2. Define **Observations**
-3. **Compare** Observations and ModelResults
+3. **Match** Observations and ModelResults
 4. Do plotting, statistics, reporting using the **Comparer**
 
 Read more about the workflow in the [getting started guide](https://dhi.github.io/modelskill/getting-started.html).

docs/getting-started.md

@@ -18,20 +18,17 @@ The typical ModelSkill workflow consists of these five steps:
 
 ### 1. Define ModelResults
 
-The result of a MIKE 21/3 simulation is stored in one or more dfs files.
-The most common formats are .dfsu for distributed data and .dfs0 for
-time series point data. A ModelSkill ModelResult is defined by the
-result file path and a name:
+The result of a simulation is stored in one or more result files, e.g. dfsu, dfs0, nc, csv.
 
-```python
+The name is used to identify the model result in the plots and tables.
+
+```python hl_lines="4"
 import modelskill as ms
-mr = ms.DfsuModelResult("SW/HKZN_local_2017_DutchCoast.dfsu", name='HKZN_local', item="Sign. Wave Height")
+mr = ms.DfsuModelResult("SW/HKZN_local_2017_DutchCoast.dfsu", 
+                         item="Sign. Wave Height",
+                         name='HKZN_local')
 ```
 
-Currently, ModelResult supports .dfs0 and .dfsu files and pandas
-DataFrame. Only the file header is read when the ModelResult object is
-created. The data will be read later.
-
 ### 2. Define Observations
 
 The next step is to define the measurements to be used for the skill
@@ -40,12 +37,15 @@ assessment. Two types of observation are available:
 -   [PointObservation](api/observation/point.md)
 -   [TrackObservation](api/observation/track.md)
 
-Let\'s assume that we have one PointObservation and one
-TrackObservation:
+Let's assume that we have one PointObservation and one
+TrackObservation (`name` is used to identify the observation, similar to the `name` of the model above). 
 
-```python
-hkna = ms.PointObservation("HKNA_Hm0.dfs0", item=0, x=4.2420, y=52.6887, name="HKNA")
-c2 = ms.TrackObservation("Alti_c2_Dutch.dfs0", item=3, name="c2")
+```python hl_lines="3 5"
+hkna = ms.PointObservation("HKNA_Hm0.dfs0", item=0,
+                            x=4.2420, y=52.6887,
+                            name="HKNA")
+c2 = ms.TrackObservation("Alti_c2_Dutch.dfs0", item=3,
+                          name="c2")
 ```
 
 In this case both observations are provided as .dfs0 files but pandas
@@ -57,7 +57,7 @@ file, the item number (or item name) and a name. A PointObservation
 further needs to be initialized with it\'s x-, y-position.
 
 
-### 3. Connect observations and ModelResults
+### 3. Match observations and ModelResults
 
 ```python
 cc = ms.match([hkna, c2], mr)

docs/index.md

@@ -26,21 +26,19 @@ ModelSkill is compatible with Python 3.8 and later versions on Windows and Linux
 Are your observations and model results already matched? 
 
 ```python
->>> import modelskill as ms
->>> cmp = ms.from_matched("matched_data.dfs0", obs_item="obs_WL", mod_item="WL")
->>> cmp.skill()
-...
+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?
 
 ```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)[0]
->>> cmp.skill()
-...
+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()
 ```
 
 Read more in the [Getting started guide](getting-started.md) or in the [overview](overview.md) of the package.

notebooks/Metocean_track_comparison_global.ipynb

@@ -72,7 +72,7 @@
             "metadata": {},
             "outputs": [],
             "source": [
-                "cmp = ms.match(o1, mr)[0]  # compare returns a list of comparison objects, here we only have one"
+                "cmp = ms.match(o1, mr)"
             ]
         },
         {