Update documentation

develop/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 73946210d160fba882e604d8a26f9c48
+config: d775ecf3aaaf8144f60332cc5a5dc768
 tags: 645f666f9bcd5a90fca523b33c5a78b7

develop/_sources/users_guide/tasks/timeSeriesOceanRegions.rst.txt

@@ -22,7 +22,81 @@ The following configuration options are available for this task:
     ## options related to plotting time series of groups of ocean regions
 
     # the names of region groups to plot, each with its own section below
-    regionGroups = ['Antarctic Regions']
+    regionGroups = ['Ocean Basins', 'Arctic Ocean Regions', 'Antarctic Regions']
+
+    # a list of variables available to plot
+    availableVariables = [
+        {'name': 'temperature',
+        'title': 'Temperature',
+        'units': r'$$^\circ$$C',
+        'mpas': ['timeMonthly_avg_activeTracers_temperature']},
+        {'name': 'salinity',
+        'title': 'Salinity',
+        'units': 'PSU',
+        'mpas': ['timeMonthly_avg_activeTracers_salinity']},
+        {'name': 'potentialDensity',
+        'title': 'Potential Density',
+        'units': 'kg m$$^{-3}$$',
+        'mpas': ['timeMonthly_avg_potentialDensity']},
+        {'name': 'thermalForcing',
+        'title': 'Thermal Forcing',
+        'units': r'$$^\circ$$C',
+        'mpas': ['timeMonthly_avg_activeTracers_temperature',
+                  'timeMonthly_avg_activeTracers_salinity',
+                  'timeMonthly_avg_density']},
+        {'name': 'oceanHeatContent',
+        'title': 'Ocean Heat Content',
+        'units': r'$$10^{22}$$ J',
+        'mpas': ['timeMonthly_avg_activeTracers_temperature']},
+        {'name': 'mixedLayerDepth',
+        'title': 'Mixed Layer Depth',
+        'units': 'm',
+        'mpas': ['timeMonthly_avg_dThreshMLD']}]
+
+    # allow for longer plot titles
+    maxTitleLength = 70
+
+    [timeSeriesOceanBasins]
+    ## options related to plotting time series of Ocean Basins
+
+    # list of regions to plot or ['all'] for all regions in the masks file.
+    # See "regionNames" in the oceanBasins masks file in
+    # regionMaskSubdirectory for details.
+    regionNames = ['all']
+
+    # a list of variables to plot from availableVariables in timeSeriesOceanRegions
+    variables = ['oceanHeatContent']
+
+    # variables that are anomalies
+    anomalies = ['oceanHeatContent']
+
+    # The minimum and maximum depth over which fields are averaged.
+    zmin = -10000
+    zmax = 0
+
+    # Observational data sets to compare against
+    obs = []
+
+    [timeSeriesArcticOceanRegions]
+    ## options related to plotting time series of Arctic Ocean regions
+
+    # list of regions to plot or ['all'] for all regions in the masks file.
+    # See "regionNames" in the arcticOceanRegions masks file in
+    # regionMaskSubdirectory for details.
+    regionNames = []
+
+    # a list of variables to plot from availableVariables in timeSeriesOceanRegions
+    variables = ['temperature', 'salinity', 'potentialDensity', 'mixedLayerDepth']
+
+    # variables that are anomalies
+    anomalies = []
+
+    # The minimum and maximum depth over which fields are averaged.
+    zmin = -1000
+    zmax = 0
+
+    # Observational data sets to compare against
+    obs = ['WOA18']
 
 
     [timeSeriesAntarcticRegions]
@@ -33,23 +107,12 @@ The following configuration options are available for this task:
     # regionMaskSubdirectory for details.
     regionNames = []
 
-    # a list of variables to plot
-    variables = [{'name': 'temperature',
-                  'title': 'Temperature',
-                  'units': r'$^\circ$C',
-                  'mpas': 'timeMonthly_avg_activeTracers_temperature'},
-                 {'name': 'salinity',
-                  'title': 'Salinity',
-                  'units': 'PSU',
-                  'mpas': 'timeMonthly_avg_activeTracers_salinity'},
-                 {'name': 'potentialDensity',
-                  'title': 'Potential Density',
-                  'units': 'kg m$^{-3}$',
-                  'mpas': 'timeMonthly_avg_potentialDensity'},
-                 {'name': 'mixedLayerDepth',
-                  'title': 'Mixed Layer Depth',
-                  'units': 'm',
-                  'mpas': 'timeMonthly_avg_dThreshMLD'}]
+    # a list of variables to plot from availableVariables in timeSeriesOceanRegions
+    variables = ['temperature', 'salinity', 'potentialDensity', 'thermalForcing',
+                'oceanHeatContent', 'mixedLayerDepth']
+
+    # variables that are anomalies
+    anomalies = ['oceanHeatContent']
 
     # The minimum and maximum depth over which fields are averaged, default is
     # to take these values from the geojson feature's zmin and zmax properties.
@@ -63,14 +126,26 @@ The following configuration options are available for this task:
 Region Groups
 -------------
 
-``regionGroup`` is a list of region groups,each of which will get its own
+``regionGroup`` is a list of region groups, each of which will get its own
 gallery group on the resulting analysis webpage.  See
 :ref:`config_region_groups` for more information on the available region
 groups. For each region group, there should be a corresponding
 ``timeSeries<RegionGroup>`` section of the config file, with any spaces removed
 from the name of the region group.  By default, the only region group for this
 task is ``'Antarctic Regions'``.
 
+Available Variables
+-------------------
+
+The ``availableVariables`` list has a python dictionary for each variable that
+is available to be plotted. A separate gallery will be produced for each
+requested variable with a title given by the ``"title"`` entry in the
+dictionary. The ``"units"`` entry is used for the y-axis label of each plot.
+The ``"name"`` is the name of the variable in the NetCDF files as well as the
+text appended to subtaks names and file names. It should contain no spaces.
+The ``"mpas"`` entry is the name of the corresponding field in the MPAS-Ocean
+``timeSeriesStatsMonthlyOutput`` files.
+
 Region Names
 ------------
 
@@ -90,13 +165,17 @@ region group.  In the case of ``Antarctic Regions``, these are:
 Variables
 ---------
 
-The ``variables`` list has a python dictionary for each variable to be plotted.
-A separate gallery will be produced for each variable with a title given by
-the ``"title"`` entry in the dictionary.  The ``"units"`` entry is used for the
-y-axis label of each plot.  The ``"name"`` is the name of the variable in
-the NetCDF files as well as the text appended to subtaks names and file names.
-It should contain no spaces.  The ``"mpas"`` entry is the name of the
-corresponding field in the MPAS-Ocean ``timeSeriesStatsMonthlyOutput`` files.
+The ``variables`` list are the variables from ``availableVariables`` that
+should be plotted in a given region.
+
+Anomalies
+---------
+
+The ``anomalies`` list are the variables from ``variables`` that should be
+plotted as anomalies from the beginning of the simulation or from
+``anomalyRefYear`` for time series if that config option is defined.
+By default, this is applied to the ocean heat content in cases where it is
+being plotted.
 
 Depth Bounds
 ------------
@@ -113,6 +192,9 @@ since they have negative values.
 Other Config Options
 --------------------
 
+``maxTitleLength`` is used to give titles of these plots more space than
+allowed in typical plots.
+
 For more details, see:
  * :ref:`config_regions`