Merge pull request #917 from cbegeman/add_ocean_histogram_task

Add histogram plot type and ocean histogram task

docs/users_guide/analysis_tasks.rst

@@ -35,6 +35,7 @@ Analysis Tasks
    tasks/geojsonTransects
    tasks/oceanRegionalProfiles
    tasks/regionalTSDiagrams
+   tasks/oceanHistogram
 
    tasks/climatologyMapSeaIceConcNH
    tasks/climatologyMapSeaIceThickNH

docs/users_guide/config/regions.rst

@@ -35,17 +35,17 @@ web page.
 Region Groups
 -------------
 
-Currently, seven analysis tasks (:ref:`task_climatologyMapAntarcticMelt`,
+Currently, eight analysis tasks (:ref:`task_climatologyMapAntarcticMelt`,
 :ref:`task_hovmollerOceanRegions`, :ref:`task_oceanRegionalProfiles`,
 :ref:`task_regionalTSDiagrams`, :ref:`task_streamfunctionMOC`,
-:ref:`task_timeSeriesAntarcticMelt`, and :ref:`task_timeSeriesOceanRegions`)
-use masks that define regions in an MPAS mesh as part of their analysis.  Most
-of these region group are defined in
+:ref:`task_oceanHistogram`, :ref:`task_timeSeriesAntarcticMelt`, and
+:ref:`task_timeSeriesOceanRegions`) use masks that define regions in an MPAS
+mesh as part of their analysis.  Most of these region group are defined in
 :py:func:`geometric_features.aggregation.get_aggregator_by_name()`.
-Several tasks (:ref:`task_hovmollerOceanRegions`,
+Several tasks (:ref:`task_hovmollerOceanRegions`, :ref:`task_oceanHistogram`,
 :ref:`task_oceanRegionalProfiles`, :ref:`task_regionalTSDiagrams`, and
 :ref:`task_timeSeriesOceanRegions`) can use any of the defined region groups.
-Currently, available region groups are: ``Antarctic Regions``,
+Currently, available region groups are: ``Artic Ocean Regions``, ``Antarctic Regions``,
 ``Ocean Basins``, ``Ice Shelves``, and ``Ocean Subbasins``.
 
 The option ``regionMaskSubdirectory`` in the ``[diagnostics]`` section specifies

docs/users_guide/tasks/oceanHistogram.rst

@@ -0,0 +1,120 @@
+.. _task_oceanHistogram:
+
+oceanHistogram
+==============
+
+An analysis task for plotting histograms of 2-d variables of climatologies
+in ocean regions.
+
+Component and Tags::
+
+  component: ocean
+  tags: climatology, histogram, regions, publicObs
+
+Configuration Options
+---------------------
+
+The following configuration options are available for this task:
+
+.. code-block:: cfg
+
+    [oceanHistogram]
+    ## options related to plotting histograms of climatologies of 2-d ocean
+    ## variables
+
+    # list of variables to plot
+    variableList = []
+
+    # list of observations to compare against
+    obsList = ['AVISO']
+
+    # list of ocean variables by which to weight variables in variable list
+    weightList = []
+
+    # list of regions to plot from the region list in [regions] below
+    regionGroups = ['Ocean Basins']
+
+    # list of region names within the region group listed above
+    regionNames = []
+
+    # Seasons to conduct analysis over
+    # Note: start and end year will be inherited from climatology section
+    seasons =  ['ANN']
+
+    # Number of histogram bins
+    bins = 40
+
+Region Groups
+-------------
+
+A list of groups of regions, each of which will get its own gallery on
+the resulting analysis web page.  See :ref:`config_region_groups` for
+more information on the available region groups.  By default,
+the only region group is ``'Ocean Basins'``.
+
+Region Names
+------------
+
+The ``regionNames`` can be set to ``['all']`` to plot all of the
+regions in the geojson file.  In the case of ``Antarctic Regions``, these
+are:
+
+.. code-block:: cfg
+
+    ["Southern Ocean", "Southern Ocean 60S", "Eastern Weddell Sea Shelf",
+     "Eastern Weddell Sea Deep", "Western Weddell Sea Shelf",
+     "Western Weddell Sea Deep", "Weddell Sea Shelf", "Weddell Sea Deep",
+     "Bellingshausen Sea Shelf", "Bellingshausen Sea Deep", "Amundsen Sea Shelf",
+     "Amundsen Sea Deep", "Eastern Ross Sea Shelf", "Eastern Ross Sea Deep",
+     "Western Ross Sea Shelf", "Western Ross Sea Deep",
+     "East Antarctic Seas Shelf", "East Antarctic Seas Deep"]
+
+For ``Ocean Basins``, they are:
+
+.. code-block:: cfg
+
+    ["Atlantic_Basin", "Pacific_Basin", "Indian_Basin", "Arctic_Basin",
+     "Southern_Ocean_Basin", "Mediterranean_Basin", "Global Ocean",
+     "Global Ocean 65N to 65S", "Global Ocean 15S to 15N"]
+
+Variable List
+-------------
+The ``variableList`` option determines the variables to plot. Currently, only
+2-d variables are supported but we envision extending to 3-d variables in the
+near future. The variables are to be listed according to their registry names, with ``timeMontly_avg_`` prepended in the code.
+
+Observations
+------------
+The ``obsList`` option contains a list of the names of observational data sets.
+Currently, "AVISO" is the only data set available, but we anticipate adding
+several additional data sets in the near future.
+
+:ref:`aviso_ssh`
+
+Weight List
+-----------
+The ``weightList`` option determines the variables to normalize by in plotting
+the histogram. This is an optional feature. If used, ``weightList`` should be
+of the same length as ``variableList``. We currently only support for 2-d
+variables that are the same size as their corresponding variables in
+``variableList`` and that are present in the restart file. For example, we use
+``areaCell`` to weight cell-centered variables such as ``ssh``.
+
+Bins
+----
+``bins`` sets the number of bins to include in the histogram.
+
+Other Config Options
+--------------------
+
+Other config options include ``lineWidth``, ``mainColor``, ``obsColor``,
+``controlColor``, ``titleFontSize``, ``defaultFontSize``. For more details on
+the remaining config options, see
+ * :ref:`config_seasons`
+
+Example Result
+--------------
+
+.. image:: examples/histogram_ssh_aviso_atl.png
+   :width: 500 px
+   :align: center

mpas_analysis/__main__.py

@@ -197,6 +197,9 @@ def build_analysis_list(config, controlConfig):
                                         controlConfig))
     analyses.append(ocean.TimeSeriesTransport(config, controlConfig))
 
+    analyses.append(ocean.OceanHistogram(config, oceanClimatologyTasks['avg'],
+                                         oceanRegionMasksTask,
+                                         controlConfig))
     analyses.append(ocean.MeridionalHeatTransport(
         config, oceanClimatologyTasks['avg'], controlConfig))
 
@@ -211,7 +214,8 @@ def build_analysis_list(config, controlConfig):
     analyses.append(ocean.SoseTransects(config, oceanClimatologyTasks['avg'],
                                         controlConfig))
 
-    analyses.append(ocean.GeojsonTransects(config, oceanClimatologyTasks['avg'],
+    analyses.append(ocean.GeojsonTransects(config,
+                                           oceanClimatologyTasks['avg'],
                                            controlConfig))
 
     oceanRegionalProfiles = ocean.OceanRegionalProfiles(
@@ -242,16 +246,16 @@ def build_analysis_list(config, controlConfig):
         hemisphere='SH', controlConfig=controlConfig))
     analyses.append(seaIceTimeSeriesTask)
     analyses.append(sea_ice.ClimatologyMapSeaIceProduction(
-        config=config, mpas_climatology_task=seaIceClimatolgyTask,
+        config=config, mpas_climatology_task=seaIceClimatologyTask,
         hemisphere='NH', control_config=controlConfig))
     analyses.append(sea_ice.ClimatologyMapSeaIceProduction(
-        config=config, mpas_climatology_task=seaIceClimatolgyTask,
+        config=config, mpas_climatology_task=seaIceClimatologyTask,
         hemisphere='SH', control_config=controlConfig))
     analyses.append(sea_ice.ClimatologyMapSeaIceMelting(
-        config=config, mpas_climatology_task=seaIceClimatolgyTask,
+        config=config, mpas_climatology_task=seaIceClimatologyTask,
         hemisphere='NH', control_config=controlConfig))
     analyses.append(sea_ice.ClimatologyMapSeaIceMelting(
-        config=config, mpas_climatology_task=seaIceClimatolgyTask,
+        config=config, mpas_climatology_task=seaIceClimatologyTask,
         hemisphere='SH', control_config=controlConfig))
 
     analyses.append(sea_ice.TimeSeriesSeaIce(config, seaIceTimeSeriesTask,
@@ -715,7 +719,8 @@ def purge_output(config):
               'No purge necessary.'.format(outputDirectory))
     else:
         for subdirectory in ['plots', 'logs', 'mpasClimatology', 'mapping',
-                             'timeSeries', 'html', 'mask', 'profiles']:
+                             'timeSeries', 'html', 'mask', 'profiles',
+                             'histogram']:
             option = '{}Subdirectory'.format(subdirectory)
             directory = build_config_full_path(
                 config=config, section='output',

mpas_analysis/default.cfg

@@ -171,6 +171,7 @@ logsSubdirectory = logs
 mpasClimatologySubdirectory = clim/mpas
 mappingSubdirectory = mapping
 timeSeriesSubdirectory = timeseries
+histogramSubdirectory = histograms
 profilesSubdirectory = profiles
 maskSubdirectory = masks
 # provide an absolute path to put HTML in an alternative location (e.g. a web
@@ -3415,6 +3416,33 @@ observationsLabel = SeaWIFS
 galleryLabel = Chlorophyll
 
 
+[oceanHistogram]
+## options related to plotting histograms of climatologies of 2-d ocean
+## variables
+
+# list of variables to plot
+variableList = []
+
+# list of observations to compare against
+obsList = ['AVISO']
+
+# list of ocean variables by which to weight variables in variable list
+weightList = []
+
+# list of regions to plot from the region list in [regions] below
+regionGroups = ['Ocean Basins']
+
+# list of region names within the region group listed above
+regionNames = []
+
+# Seasons to conduct analysis over
+# Note: start and end year will be inherited from climatology section
+seasons =  ['ANN']
+
+# Number of histogram bins
+bins = 40
+
+
 [oceanRegionalProfiles]
 ## options related to plotting vertical profiles of regional means (and
 ## variability) of 3D MPAS fields

mpas_analysis/ocean/__init__.py

@@ -31,6 +31,7 @@
 from mpas_analysis.ocean.time_series_ssh_anomaly import TimeSeriesSSHAnomaly
 
 from mpas_analysis.ocean.time_series_sst import TimeSeriesSST
+from mpas_analysis.ocean.histogram import OceanHistogram
 from mpas_analysis.ocean.index_nino34 import IndexNino34
 from mpas_analysis.ocean.streamfunction_moc import StreamfunctionMOC
 from mpas_analysis.ocean.meridional_heat_transport import \