examples of reading output in MATLAB and Python

Author: edoddridge

doc/getting_started/getting_started.rst

@@ -598,7 +598,16 @@ and model diagnostics is described in chap_diagnosticsio.
 MDSIO output files
 ~~~~~~~~~~~~~~~~~~
 
-The “traditional” output files are generated by the ``mdsio`` package (link to section_mdsio).
+The “traditional” output files are generated by the ``mdsio`` package 
+(link to section_mdsio).The ``mdsio`` model data are written according to a
+“meta/data” file format. Each variable is associated with two files with
+suffix names ``.data`` and ``.meta``. The ``.data`` file contains the
+data written in binary form (big endian by default). The ``.meta`` file
+is a “header” file that contains information about the size and the
+structure of the ``.data`` file. This way of organizing the output is
+particularly useful when running multi-processors calculations. 
+
+
 At a minimum, the instantaneous “state” of the model is written out,
 which is made of the following files:
 
@@ -654,18 +663,31 @@ append `NetCDF files <http://www.unidata.ucar.edu/software/netcdf/>`_. Unlike th
 placed within a subdirectory with a name such as ``mnc_output_`` (by default, NetCDF tries to append, rather than overwrite, existing files,
 so a unique output directory is helpful for each separate run).
 
+
+The MNC output files are all in the “self-describing” NetCDF format and
+can thus be browsed and/or plotted using tools such as:
+
+-  `ncdump <https://www.unidata.ucar.edu/software/netcdf/netcdf-4/newdocs/netcdf/ncdump.html>`_ is a utility which is typically included with every NetCDF
+   install, and converts the NetCDF binaries into formatted ASCII text files.
+
+-  `ncview <http://meteora.ucsd.edu/~pierce/ncview_home_page.html>`_ is a very convenient and quick way to plot NetCDF
+   data and it runs on most platforms. `Panoply <https://www.giss.nasa.gov/tools/panoply/>`_ is a similar alternative.
+
+-  Matlab, GrADS, IDL and other common post-processing environments provide
+   built-in NetCDF interfaces.
+
+
 Looking at the output
 ---------------------
 
-The traditional or ``mdsio`` model data are written according to a
-“meta/data” file format. Each variable is associated with two files with
-suffix names ``.data`` and ``.meta``. The ``.data`` file contains the
-data written in binary form (big endian by default). The ``.meta`` file
-is a “header” file that contains information about the size and the
-structure of the ``.data`` file. This way of organizing the output is
-particularly useful when running multi-processors calculations. The repository
-version of the model includes a few Matlab utilities to read output
-files written in this format. The Matlab scripts are located in the
+MATLAB
+~~~~~~
+
+MDSIO output
+############
+
+The repository includes a few Matlab utilities to read output
+files written in the ``mdsio`` format. The Matlab scripts are located in the
 directory ``utils/matlab`` under the root tree. The script ``rdmds.m``
 reads the data. Look at the comments inside the script to see how to use
 it.
@@ -686,20 +708,44 @@ Some examples of reading and visualizing some output in Matlab:
     >> eta=rdmds('Eta',[0:10:100]);
     >> for n=1:11; imagesc(eta(:,:,n)');axis ij;colorbar;pause(.5);end
 
+
+NetCDF
+######
+
 Similar scripts for netCDF output (``rdmnc.m``) are available and they
 are described in Section [sec:pkg:mnc].
 
-The MNC output files are all in the “self-describing” NetCDF format and
-can thus be browsed and/or plotted using tools such as:
 
--  `ncdump <https://www.unidata.ucar.edu/software/netcdf/netcdf-4/newdocs/netcdf/ncdump.html>`_ is a utility which is typically included with every NetCDF
-   install, and converts the NetCDF binaries into formatted ASCII text files.
+Python
+~~~~~~
 
--  `ncview <http://meteora.ucsd.edu/~pierce/ncview_home_page.html>`_ is a very convenient and quick way to plot NetCDF
-   data and it runs on most platforms. `Panoply <https://www.giss.nasa.gov/tools/panoply/>`_ is similar alternative.
+MDSIO output
+############
 
--  Matlab, GrADS, IDL and other common post-processing environments provide
-   built-in NetCDF interfaces.
+The repository includes Python scripts for reading the ``mdsio`` format under ``utils/python``. The following example shows how to load in some data:
+
+::
+  
+    # python
+    import mds
+
+    Eta = mds.rdmds('Eta', itrs=10)
+
+The docstring for ``mds.rdmds`` contains much more detail about using this function and the options that it takes.
+
+NetCDF output
+#############
+
+The NetCDF output is currently produced with one file per processor. This means the individual tiles need to be stitched together to create a single NetCDF file that spans the model domain. The script ``gluemncbig.py`` in the ``utils/python`` folder can do this efficiently from the command line. 
+
+The following example shows how to use the `xarray package <http://xarray.pydata.org/>`_ to read the resulting NetCDF file into python:
+
+::
+  
+  # python
+  import xarray as xr
+
+  Eta = xr.open_dataset('Eta.nc')
 
 
 .. _chap_modelExamples: