Adding description of output

To help users better understand the outputs of TCRM, include a page in the
documentation describing the output files and formats.

docs/output.rst

@@ -0,0 +1,180 @@
+Model output
+============
+
+TCRM generates a variety of output that can be used to analyse the
+input dataset and the resulting hazard estimates. The five primary
+modules (:mod:`DataProcess`, :mod:`StatInterface`,
+:mod:`TrackGenerator`, :mod:`wind` and :mod:`hazard`) all generate
+data files and figures that help interpret the results and assist in
+ensuring the model is performing as expected.
+
+Output directory structure
+--------------------------
+
+The output directory structure is 
+:: 
+  |-process
+  |       |-timeseries
+  |-hazard
+  |-log
+  |-tracks
+  |-windfield
+  |-plots
+        |-stats
+	|-hazard
+
+* ``process``: contains a mixture of text and netcdf-format files
+  generated by :mod:`DataProcess` and :mod:`StatInterface`.
+* ``process/timeseries``: contains comma-separated time series data
+  for locations, generated when running `tcevent.py` -- see the
+  :ref:`scenariomodelling` section of the user guide.
+* ``hazard``: contains the final netcdf-format file of return period
+  wind speeds. The file also contains the location, shape and scale
+  parameters for the Generalised Extreme Value (GEV) distribution
+  fitted to the wind speeds at each point. If the ``CalculateCI``
+  option in the ``Hazard`` section of the configuration file was set
+  to `True`, then the file will also contain upper and lower
+  confidence bounds on the hazard levels (values only, not the
+  corresponding distribution parameters).
+* ``log``: Log files generated by `tcrm.py`. If executed using
+  ``mpirun``, then there will be a separate log file for each process.
+* ``tracks``: netcdf-format track files. An outline of the structure
+  is given below.
+* ``windfield``: netcdf-format wind field files. An outline of the
+  structure is given below.
+* ``plots``: images generated by :mod:`DataProcess`,
+  :mod:`StatInterface` (``plots/stats``) - more information below -
+  and :mod:`hazard` (``plots/hazard``). Hazard images include maps of
+  return period wind speed for all specified return periods, and
+  hazard curves for all locations within the model domain (and where
+  valid hazard values are estimated).
+
+.. _trackformat:
+
+Track file format
+-----------------
+
+TCRM generates netCDF4 files for saving gridded data and track
+files. We make use of the heirarchical group support to store multiple
+tracks in a single file, and use compound variables (which map
+directly to a :class:`numpy.recarray`) to define a custom data type
+for the track data itself. Following is the CDL representation of a
+single ``track`` group object in a track netcdf file. Output files
+will contain multiple sub-groups (i.e. ``tracks-0000``,
+``tracks-0001``, etc.). One file holds all tracks for a single
+simulated year.
+
+::
+   netcdf tracks.00000 {
+   // global attributes:
+                :created_on = "2015-07-14 16:09:28" ;
+                :created_by = "carthur" ;
+   group: tracks {
+	group: tracks-0000 {
+	    types:
+	        compound track_dtype {
+		  int CycloneNumber ;
+		  float Datetime ;
+		  float TimeElapsed ;
+		  double Longitude ;
+		  double Latitude ;
+		  double Speed ;
+		  double Bearing ;
+		  double CentralPressure ;
+		  double EnvPressure ;
+		  double rMax ;
+	      }; // track_dtype
+	    dimensions:
+	        time = UNLIMITED ; // (207 currently)
+	    variables:
+	        float time(time) ;
+                    time:units = "hours since 1900-01-01 00:00" ;
+		    time:calendar = "standard" ;
+                track_dtype track(time) ;
+                    track:long_name = "Tropical cyclone track data" ;
+		    track:time_units = "hours since 1900-01-01 00:00" ;
+		    track:calendar = "standard" ;
+		    track:lon_units = "degrees east" ;
+		    track:lat_units = "degrees north" ;
+		    track:pressure_units = "hPa" ;
+		    track:speed_units = "m/s" ;
+		    track:length_units = "km" ;
+		    track:trackId = "(1, 0)" ;
+    } // group tracks-0000
+
+
+Wind field file format
+----------------------
+
+TCRM generates netCDF4 files for wind fields from each separate track
+event. Because only a single event is stored in each file, there are
+no groups defined in these netCDF4 files. Following is a CDL
+representation of the wind field file. The global attributes are not
+included here for brevity, but capture the complete configuration
+settings (as read from the simulation configuration file specified
+when the model is executed).
+
+::
+
+    netcdf gust.001-00000 {
+    dimensions:
+	    lat = 1751 ;
+	    lon = 5001 ;
+    variables:
+	    float lat(lat) ;
+		    lat:units = "degrees_north" ;
+		    lat:long_name = "Latitude" ;
+		    lat:standard_name = "latitude" ;
+		    lat:axis = "Y" ;
+	    float lon(lon) ;
+		    lon:units = "degrees_east" ;
+		    lon:long_name = "Longitude" ;
+		    lon:standard_name = "longitude" ;
+		    lon:axis = "X" ;
+	    float vmax(lat, lon) ;
+		    vmax:_FillValue = -9999.f ;
+		    vmax:grid_mapping = "crs" ;
+		    vmax:actual_range = 0.f, 106.6134f ;
+		    vmax:valid_range = 0., 200. ;
+		    vmax:long_name = "Maximum 3-second gust wind speed" ;
+		    vmax:standard_name = "wind_speed_of_gust" ;
+		    vmax:cell_methods = "time: maximum time: maximum (interval: 3 seconds)" ;
+		    vmax:units = "m/s" ;
+	    float ua(lat, lon) ;
+		    ua:_FillValue = -9999.f ;
+		    ua:grid_mapping = "crs" ;
+		    ua:actual_range = -84.30162f, 79.13363f ;
+		    ua:valid_range = -200., 200. ;
+		    ua:long_name = "Eastward component of maximum wind speed" ;
+		    ua:standard_name = "eastward_wind" ;
+		    ua:units = "m/s" ;
+	    float va(lat, lon) ;
+		    va:_FillValue = -9999.f ;
+		    va:grid_mapping = "crs" ;
+		    va:actual_range = -103.1569f, 85.35658f ;
+		    va:valid_range = -200., 200. ;
+		    va:long_name = "Northward component of maximim wind speed" ;
+		    va:standard_name = "northward_wind" ;
+		    va:units = "m/s" ;
+	    float slp(lat, lon) ;
+		    slp:_FillValue = -9999.f ;
+		    slp:grid_mapping = "crs" ;
+		    slp:actual_range = 1016.37f, 1016.37f ;
+		    slp:valid_range = 70000., 115000. ;
+		    slp:long_name = "Minimum air pressure at sea level" ;
+		    slp:standard_name = "air_pressure_at_sea_level" ;
+		    slp:cell_methods = "time: minimum" ;
+		    slp:units = "Pa" ;
+	    int crs ;
+		    crs:_FillValue = -9999 ;
+		    crs:semi_major_axis = 6378137. ;
+		    crs:longitude_of_prime_meridian = 0. ;
+		    crs:grid_mapping_name = "latitude_longitude" ;
+		    crs:inverse_flattening = 298.257222101 ;
+
+    // global attributes:
+
+
+Statistical plots
+-----------------
+

index.rst

@@ -61,6 +61,7 @@ Contents
    Installation <docs/install>
    Setting up the model <docs/setup>
    Running the model <docs/execution>
+   Model output <docs/output>
    Examples <docs/examples>
    Model evaluation <docs/evaluation>
    Using different TC databases <docs/sources>