From dd367f18f7ca605282fc8c599b203d6fb3fa66e9 Mon Sep 17 00:00:00 2001
From: Ryan Murray <74630349+rywm-dhi@users.noreply.github.com>
Date: Sun, 22 Sep 2024 21:42:30 +0200
Subject: [PATCH] Update xns11 docs

---
 docs/user-guide/xns11.qmd | 160 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 160 insertions(+)

diff --git a/docs/user-guide/xns11.qmd b/docs/user-guide/xns11.qmd
index 7fcde2b3..9332739d 100644
--- a/docs/user-guide/xns11.qmd
+++ b/docs/user-guide/xns11.qmd
@@ -1,3 +1,163 @@
 ---
 title: Xns11
 ---
+
+Xns11 is the main interface for accessing cross section data.
+
+## Opening files
+```{python}
+from mikeio1d import Xns11
+xns = Xns11('../data/mikep_cs_demo.xns11')
+xns
+```
+
+## Cross section collections
+Each Xns11 object contains a collection of cross sections via the `xsections` attribute.
+```{python}
+xns.xsections
+```
+
+### Overview
+An overview of a cross section collection can be obtained by calling the 'to_dataframe' method.
+```{python}
+xns.xsections.to_dataframe()
+```
+
+### Indexing
+Cross section collections are dict-like and can be indexed by a tuple of location ID, chainage, and topo ID.
+
+```{python}
+xns.xsections['basin_left1', '122.042', '1']
+```
+Alternatively, the location ID, chainage, and topo ID can be explicitly expressed with the `sel` method.
+```{python}
+xns.xsections.sel(location_id='basin_left1', chainage='122.042', topo_id='1')
+```
+
+### Slicing
+
+Cross section collections can be sliced by location ID, chainage, or topo ID.
+
+```{python}
+xns.xsections['basin_left1'] # all cross sections at location 'basin_left1'
+```
+
+```{python}
+xns.xsections[:, '122.042'] # all cross sections at chainage '122.042'
+```
+
+```{python}
+xns.xsections[:,:,'1'] # all cross sections with topo ID '1'
+```
+
+### Combining
+Cross section collections can be combined into a new collection.
+```{python}
+new_collection = xns.xsections['basin_left1', '2.004'] | xns.xsections['basin_left1', '210.212']
+new_collection.to_dataframe()
+```
+
+### Adding a cross section
+A new cross section can be added to a collection with the `add_xsection` method.
+```{python}
+xs_to_add = xns.xsections.sel(location_id='basin_left1', chainage='33.774', topo_id='1')
+new_collection.add_xsection(xs_to_add)
+new_collection.to_dataframe()
+```
+
+## Cross sections
+A cross section is uniquely identified by its location ID, chainage, and topo ID.
+```{python}
+xs = xns.xsections['basin_left1', '122.042', '1']
+xs
+```
+
+### Plotting
+Cross sections can be plotted directly with the `plot` method.
+```{python}
+xs.plot()
+```
+
+### Raw data
+The raw data of a cross section can be accessed via the `raw` attribute.
+```{python}
+df = xs.raw
+df.head()
+```
+
+Raw data is modifiable by setting the 'raw' attribute with a new DataFrame of the same column names.
+```{python}
+df_modified = xs.raw
+df_modified['z'] = df_modified['z'] + 1000
+xs.raw = df_modified
+xs.plot()
+```
+
+### Markers
+Markers can be viewed with the `markers` attribute.
+```{python}
+xs.markers
+```
+
+Set and unset markers with the `set_marker` and `unset_marker` methods. Alternatively, reassign a modified marker DataFrame like is done for raw data.
+```{python}
+xs.set_marker(42, 50) # set a user-defined marker '42' at the closest point to x=50
+xs.plot()
+```
+
+```{python}
+xs.unset_marker(42) # unset the user-defined marker '42'
+xs.plot()
+```
+
+### Processed data
+Processed data is accessible via the `processed` attribute.
+```{python}
+df = xs.processed
+df.head()
+```
+
+Processed data is modifiable by setting the 'processed' attribute with a new DataFrame of the same column names.
+```{python}
+df_modified = xs.processed
+df_modified['level'] = df_modified['level'] -500
+xs.processed = df_modified
+xs.processed.head()
+```
+To recalculate processed datd based on the raw data, call the `recompute_processed` method.
+```{python}
+xs.processed_allow_recompute = True
+xs.recompute_processed()
+xs.processed.head()
+```
+
+## GeoDataFrames
+
+Cross section collections can be extracted into a GeoDataFrame.
+```{python}
+gdf = xns.xsections.to_geopandas()
+gdf.head()
+```
+
+```{python}
+gdf.plot(column='location_id', cmap='tab20', legend=True)
+```
+It is also possible to extract cross section markers as GeoDataFrames.
+
+```{python}
+gdf = xns.xsections.to_geopandas_markers()
+gdf.head()
+```
+
+```{python}
+ax = xns.xsections.to_geopandas().plot()
+xns.xsections.to_geopandas_markers().plot(ax=ax, column='marker', markersize=9, legend=True)
+```
+
+## Examples
+
+- [Xns11 Basics](../examples/xns11_basic.qmd)
+
+::: callout-tip
+There are also several notebook examples available on our [GitHub repository]()https://github.com/DHI/mikeio1d/tree/main/notebooks.
+:::
\ No newline at end of file