add an example for how to connect to output file, slice data

docs/source/guides/subsidence_guide.inc

@@ -43,5 +43,5 @@ Subsidence behavior can be easily modified by :ref:`creating a subclass <customi
 
 An example of using subclassing to create a model setup with subsidence confined to only part of the model domain is included in the documentation:
 
-:doc:`/examples/subsidence_region`
+* :doc:`/examples/subsidence_region`
 

docs/source/guides/user_guide.rst

@@ -276,6 +276,7 @@ Keyword arguments supplied at this point will supersede values specified in the
 See :ref:`our guide for model customization <customize_the_model>` for a complete explanation and demonstration for how to modify model behavior.
 
 ..
+    =============================
     Advanced model configurations
     =============================
     ** Advanced model configuration guide is imported from another file. **
@@ -284,13 +285,23 @@ See :ref:`our guide for model customization <customize_the_model>` for a complet
 
 
 ..
+    =======================
     Working with Subsidence
     =======================
     ** Subsidence guide is imported from another file. **
 
 .. include:: subsidence_guide.inc
 
 
+..
+    =======================
+    dsfasf
+    =======================
+    ** Subsidence guide is imported from another file. **
+
+.. include:: /info/outputfile.rst
+
+
 Supporting documentation and files
 ==================================
 

docs/source/info/outputfile.rst

@@ -1,20 +1,24 @@
-******************
-Output File Format
-******************
+=================
+Model Output File
+=================
+
+If configured to save any output data, model outputs are saved using the `netCDF4 <http://unidata.github.io/netcdf4-python/>`_ file format.
 
-Model outputs are saved using the `netCDF4 <http://unidata.github.io/netcdf4-python/>`_ file format.
 
 Gridded Variables
------------------
+=================
+
 In any given run, the saving parameters "save_<var>_grids" control whether or
 not that 2-D grid variable (e.g. velocity) is saved to the netCDF4 file.
 In the netCDF4 file, a 3-D array with the dimensions
 *time* x *length* x *width* is created for each 2-D grid variable that is set
 to be saved. The appropriate units for these variables are stored as well,
 such as "meters per second" for the *velocity* grid.
 
+
 Grid Coordinates
-----------------
+================
+
 To save the model information associated with the domain itself, variables
 associated with the grid are saved as well. These are the meshed 2-D grids
 corresponding to the distance of each cell from the boundary in the "Width"
@@ -23,8 +27,10 @@ boundary of each cell in the "Length" dimension, as *y* in meters. Similarly, a
 *time* variable is stored which is a 1-D array (vector) holding the model time
 values in seconds, associated with each set of saved output data.
 
+
 Model Metadata
---------------
+==============
+
 In addition to the grid coordinates, model metadata is saved as a group of
 1-D arrays (vectors) and 0-D arrays (floats and integers). The values that are
 saved as metadata are the following:
@@ -39,11 +45,13 @@ saved as metadata are the following:
 - Sediment concentration: `C0_percent`
 - Characteristic Velocity: `u0`
 - If subsidence is enabled:
-   - Subsidence start time: `start_subsidence`
-   - Subsidence rate: `sigma`
+  - Subsidence start time: `start_subsidence`
+  - Subsidence rate: `sigma`
+
 
 Working with Model Outputs
---------------------------
+==========================
+
 The resulting netCDF4 output file can be read using any netCDF4-compatible
 library. These libraries range from the
 `netCDF4 Python package <https://github.com/Unidata/netcdf4-python>`_ itself,
@@ -52,3 +60,24 @@ to higher-level libraries such as
 *pyDeltaRCM*, there is also a package under development called
 `DeltaMetrics <https://github.com/DeltaRCM/DeltaMetrics>`_,
 that is being designed to help post-process and analyze *pyDeltaRCM* outputs.
+
+
+Here, we show how to read the output NetCDF file with Python package ``netCDF4``.
+
+.. code::
+
+   import netCDF4 as nc
+
+   data = nc.Dataset('pyDeltaRCM_output.nc')  # the output file path!
+
+This `data` object is a `Dataset` object that can be sliced the same was as a `numpy` array.
+For example, we can slice the final bed elevation and velocity of a model run:
+
+.. code::
+
+   final_bed_elevation = data['eta'][-1, :, :]
+   final_velocity = data['velocity'][-1, :, :]
+
+These slices look like this, if we were to plot them.
+
+.. plot:: guides/output_file.py

docs/source/pyplots/guides/output_file.py

@@ -0,0 +1,46 @@
+import warnings
+
+import matplotlib
+import matplotlib.pyplot as plt
+import numpy as np
+
+import pyDeltaRCM
+
+
+# filter out the warning raised about no netcdf being found
+warnings.filterwarnings("ignore", category=UserWarning)
+
+
+n = 20
+cm = matplotlib.cm.get_cmap('tab10')
+
+
+# init delta model
+with pyDeltaRCM.shared_tools._docs_temp_directory() as output_dir:
+
+    delta = pyDeltaRCM.DeltaModel(
+        out_dir=output_dir,
+        resume_checkpoint='../../_resources/checkpoint')
+
+
+_shp = delta.eta.shape
+
+# set up axis
+fig, ax = plt.subplots(1, 2, figsize=(6, 3))
+vmin, vmax = delta.eta.min(), delta.eta.max()
+
+# fill in axis
+ax[0].imshow(
+    delta.eta, vmin=vmin, vmax=vmax, cmap='cividis')
+ax[0].set_xticks([])
+ax[0].set_yticks([])
+ax[0].set_title('bed elevation')
+
+ax[1].imshow(
+    delta.uw, cmap='plasma')
+ax[1].set_xticks([])
+ax[1].set_yticks([])
+ax[0].set_title('velocity')
+
+plt.tight_layout()
+plt.show()