Merge pull request #1069 from xylar/fix-bsf-again

Fix barotropic streamfunction calculation

Author: xylar

docs/users_guide/tasks/climatologyMapBSF.rst

@@ -21,22 +21,25 @@ The following configuration options are available for this task::
   ## (if available)
 
   # colormap for model/observations
-  colormapNameResult = blue-orange-div
+  colormapNameResult = 3wave-blue-red-brown
   # whether the colormap is indexed or continuous
   colormapTypeResult = continuous
   # color indices into colormapName for filled contours
   # the type of norm used in the colormap
-  normTypeResult = symLog
+  normTypeResult = linear
   # A dictionary with keywords for the norm
-  normArgsResult = {'linthresh': 30., 'linscale': 0.5, 'vmin': -100., 'vmax': 100.}
-  colorbarTicksResult = [-100.,-40., -20., -10., 0., 10., 20., 40., 100.]
+  normArgsResult = {'vmin': -100, 'vmax': 200.}
   # Adding contour lines to the figure
-  contourLevelsResult = np.arange(-100., 101.0, 10.)
+  contourLevelsResult = np.arange(-100., 201.0, 10.)
   contourThicknessResult = 0.5
   contourColorResult = black
-  # Add arrows to contour lines
-  # whether to include arrows on the contour lines showing the direction of flow
-  arrowsOnContourResult = True
+  # The spacing (in meters) between arrows on contours in projection plots
+  # (None to disable)
+  arrowSpacingResult = 8e5
+  # The width (in meters) of arrows on contours in projection plots (None to
+  # disable)
+  arrowWidthResult = 1.5e4
+
   # colormap for differences
   colormapNameDifference = cmo.balance
   # whether the colormap is indexed or continuous
@@ -54,18 +57,76 @@ The following configuration options are available for this task::
   # comparison grid(s) on which to plot analysis
   comparisonGrids = ['latlon', 'subpolar_north_atlantic']
 
-  # list of tuples(pairs) of depths (min, max) to integrate horizontal transport over
-  depthRanges = [(0.0, -10000.0), (0.0, -2000.0)]
+  # list of tuples(pairs) of depths (min, max) to integrate horizontal transport
+  # over
+  depthRanges = [(10.0, -10000.0), (10.0, -2000.0)]
 
-  # minimum latitude (degrees) above which the mean BSF on boundary vertices
-  # averages to zero
-  minLatitudeForZeroBSF = -45.0
+  # minimum and maximum latitude (degrees) between which the mean BSF on boundary
+  # vertices averages to zero
+  latitudeRangeForZeroBSF = (-45.0, 90.0)
 
 
 By default, the BSF is computed over two depth ranges---the full depth of
 the ocean and only to 2000 m.  By default, global and subpolar North Atlantic
 plots are produced.  The BSF is constrained to have a mean value on coastal
-boundaries of zero north of ``minLatitudeForZeroBSF``.
+boundaries between the bounds set in ``latitudeRangeForZeroBSF``.
+
+You can set config options for individual comparison grids in a separate
+seciton with the suffix associated with the comparison grid appended, e.g.::
+
+  [climatologyMapBSF]
+  ## options related to plotting horizontally remapped climatologies of
+  ## the barotropic streamfunction (BSF) against control model results
+  ## (if available)
+
+  # comparison grid(s) on which to plot analysis
+  comparisonGrids = ['latlon', 'arctic_extended', 'antarctic_extended',
+                    'subpolar_north_atlantic', 'fris']
+
+  [climatologyMapBSFAntarcticExtended]
+  ## options related to plotting Antarctic climatologies of the barotropic
+  ## streamfunction (BSF)
+
+  # colormap for model/observations
+  colormapNameResult = blue-orange-div
+  # whether the colormap is indexed or continuous
+  colormapTypeResult = continuous
+  # color indices into colormapName for filled contours
+  # the type of norm used in the colormap
+  normTypeResult = symLog
+  # A dictionary with keywords for the norm
+  normArgsResult = {'linthresh': 30., 'linscale': 0.5, 'vmin': -150., 'vmax': 150.}
+  colorbarTicksResult = [-150., -100.,-60., -40., -20., -10., 0., 10., 20., 40., 60., 100., 150.]
+  # Adding contour lines to the figure
+  contourLevelsResult = np.arange(-150., 150.1, 10.)
+  contourThicknessResult = 0.5
+  contourColorResult = black
+  # The spacing (in meters) between arrows on contours in projection plots
+  # (None to disable)
+  arrowSpacingResult = 8e5
+  # The width (in meters) of arrows on contours in projection plots (None to
+  # disable)
+  arrowWidthResult = 1.5e4
+
+  # colormap for differences
+  colormapNameDifference = cmo.balance
+  # whether the colormap is indexed or continuous
+  colormapTypeDifference = continuous
+  # the type of norm used in the colormap
+  normTypeDifference = linear
+  # A dictionary with keywords for the norm
+  normArgsDifference = {'vmin': -10., 'vmax': 10.}
+  # colorbarTicksDifference = numpy.linspace(-10., 10., 9)
+
+  # minimum and maximum latitude (degrees) between which the mean BSF on boundary
+  # vertices averages to zero
+  latitudeRangeForZeroBSF = (-90.0, -60.0)
+
+You must define both a new set of colormaps, norms, etc. and a new range of
+latitudes over which the BSF is constrained to have a mean value of zero.
+
+This is useful because plots are more intuitive if the BSF is close to zero
+at local boundaries.
 
 For more details, see:
  * :ref:`config_colormaps`

docs/users_guide/tasks/examples/bsf.png

@@ -265,7 +265,7 @@ comparisonSubpolarNorthAtlanticResolution = 20.
 # The comparison FRIS Antarctic polar stereographic grid size and resolution in km
 comparisonFrisBounds = [-1800., -400., 100., 1500.]
 # comparisonFrisWidth = 6000.
-comparisonFrisResolution = 10.
+comparisonFrisResolution = 4.
 
 # interpolation order for model and observation results. Likely values are
 #   'bilinear', 'neareststod' (nearest neighbor) or 'conserve'
@@ -1564,22 +1564,25 @@ comparisonGrids = ['latlon', 'subpolar_north_atlantic']
 ## (if available)
 
 # colormap for model/observations
-colormapNameResult = blue-orange-div
+colormapNameResult = 3wave-blue-red-brown
 # whether the colormap is indexed or continuous
 colormapTypeResult = continuous
 # color indices into colormapName for filled contours
 # the type of norm used in the colormap
-normTypeResult = symLog
+normTypeResult = linear
 # A dictionary with keywords for the norm
-normArgsResult = {'linthresh': 30., 'linscale': 0.5, 'vmin': -100., 'vmax': 100.}
-colorbarTicksResult = [-100.,-40., -20., -10., 0., 10., 20., 40., 100.]
+normArgsResult = {'vmin': -100, 'vmax': 200.}
 # Adding contour lines to the figure
-contourLevelsResult = np.arange(-100., 101.0, 10.)
+contourLevelsResult = np.arange(-100., 201.0, 10.)
 contourThicknessResult = 0.5
 contourColorResult = black
-# Add arrows to contour lines
-# whether to include arrows on the contour lines showing the direction of flow
-arrowsOnContourResult = True
+# The spacing (in meters) between arrows on contours in projection plots
+# (None to disable)
+arrowSpacingResult = 8e5
+# The width (in meters) of arrows on contours in projection plots (None to
+# disable)
+arrowWidthResult = 1.5e4
+
 # colormap for differences
 colormapNameDifference = cmo.balance
 # whether the colormap is indexed or continuous
@@ -1597,12 +1600,14 @@ seasons =  ['ANN']
 # comparison grid(s) on which to plot analysis
 comparisonGrids = ['latlon', 'subpolar_north_atlantic']
 
-# list of tuples(pairs) of depths (min, max) to integrate horizontal transport over
-depthRanges = [(0.0, -10000.0), (0.0, -2000.0)]
+# list of tuples(pairs) of depths (min, max) to integrate horizontal transport
+# over
+depthRanges = [(10.0, -10000.0), (10.0, -2000.0)]
+
+# minimum and maximum latitude (degrees) between which the mean BSF on boundary
+# vertices averages to zero
+latitudeRangeForZeroBSF = (-45.0, 90.0)
 
-# minimum latitude (degrees) above which the mean BSF on boundary vertices
-# averages to zero
-minLatitudeForZeroBSF = -45.0
 
 [climatologyMapOHCAnomaly]
 ## options related to plotting horizontally remapped climatologies of