Add risk index outcome for navigation in ice-covered waters

docs/developers_guide/api.rst

@@ -157,6 +157,7 @@ Sea ice tasks
    ClimatologyMapSeaIceVolumeTendencyTransp
    TimeSeriesSeaIce
    ClimatologyMapIcebergConc
+   ClimatologyMapRiskIndexOutcome
 
 
 Shared modules

docs/users_guide/analysis_tasks.rst

@@ -80,3 +80,6 @@ Analysis Tasks
    tasks/timeSeriesSeaIceAreaVol
 
    tasks/climatologyMapIcebergConcSH
+
+   tasks/climatologyMapRiskIndexOutcomeNH
+   tasks/climatologyMapRiskIndexOutcomeSH

docs/users_guide/tasks/climatologyMapRiskIndexOutcomeNH.rst

@@ -0,0 +1,92 @@
+.. _task_climatologyMapRiskIndexOutcomeNH:
+
+climatologyMapRiskIndexOutcomeNH
+================================
+
+An analysis task for plotting maps of Arctic risk index outcome (rio) for navigation in ice-covered waters.
+
+Component and Tags::
+
+  component: seaIce
+  tags: climatology, horizontalMap, RiskIndexOutcome
+
+Configuration Options
+---------------------
+
+The following configuration options are available for this task::
+
+  [climatologyMapRiskIndexOutcomeNH]
+  ## options related to plotting maps of the Risk Index Outcome (RIO) for navigability
+  ## in sea-ice covered water from climatologies. The Risk Index Outcome is a navigability
+  ## metric defined by the International Maritime Organization (IMO). The index ranges
+  ## from -80 to 30. It depends on the sea-ice concentration and on Risk Index Values,
+  ## which are assigned to a vessel according to its structural properties and according
+  ## to ice thickness (and age). The maximum RIO refers to navigation in open water.
+  ## Navigation under conditions of negative RIO values is restricted to some types
+  ## of vessels. Navigation should generally be avoided where RIO < -10.
+
+  # table of Risk Index Values (IMO, MSC.1/Circ.1519 6 June 2016)
+  # https://www.imorules.com/GUID-2C1D86CB-5D58-490F-B4D4-46C057E1D102.html
+  rivNH = RIV/riv_MSC.1_Circ.1519_6_June_2016.csv
+
+  # colormap for model/observations
+  colormapNameResult = RdYlBu
+  # whether the colormap is indexed or continuous
+  colormapTypeResult = indexed
+  # color indices into colormapName for filled contours
+  colormapIndicesResult = [0, 56, 85, 170, 198, 227, 241, 248, 255, 255]
+  # colormap levels/values for contour boundaries
+  colorbarLevelsResult = numpy.linspace(-10., 30., 9)
+
+  # Months or seasons to plot (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
+  # Nov, Dec, JFM, AMJ, JAS, OND, ANN)
+  seasons =  ['AMJ', 'OND']
+
+  # comparison grid(s) on which to plot analysis
+  comparisonGrids = ['arctic']
+
+  # Polar Class of vessels, according to IMO, for which RIO maps will be generated.
+  # Range is 1 to 12. Here the values 1-7 refer to the ‘Polar Classes’ PC1-PC7,
+  # assigned by the International Association of Classification Societies (IACS).
+  # A PC1 vessel is capable of year-round operations in all polar waters. PC2 and PC3
+  # vessels can navigate in 2.5 m (or more) thick ice. The values 8-11 correspond
+  # to the Finnish-Swedish ice classes 'IA Super', 'IA', 'IB' and 'IC'.
+  # The last value, 12, refers to ‘Not-Ice-Strengthened’ ships, all vessels without
+  # a Polar Class.
+  polarClass = 6
+
+  # reference floe thicknesses (m) for calculation of the Risk Index Value (RIV)
+  # The thicknesses are intended to render the type of ice as defined by IMO.
+  # There must be as many values as there are types of ice in the RIV table.
+  # The first value has to be zero.
+  h_to_typeofice = [0, 0.005, 0.1, 0.15, 0.3, 0.5, 0.7, 1, 1.2, 1.7, 2, 2.5]
+
+  # whether to use sea-ice categories for sea-ice concentration and thickness
+  useIceCategories = False
+
+  # minimum lat and reference lon for sea ice plots in the northern hemisphere
+  minimumLatitude = 50
+  referenceLongitude = 0
+
+  # arrange subplots vertically?
+  vertical = False
+
+The option ``vertical = True`` can be used to plot 3 panels one above another
+(resulting in a tall, thin image) rather than next to each other, the default
+(resulting in a short, wide image).
+
+For details on the remaining configuration options, see:
+ * :ref:`config_colormaps`
+ * :ref:`config_seasons`
+ * :ref:`config_comparison_grids`
+
+Observations
+------------
+:ref:`imo_riv`
+
+Example Result
+--------------
+
+.. image:: examples/risk_index_outcome_nh.png
+   :width: 720 px
+   :align: center

docs/users_guide/tasks/climatologyMapRiskIndexOutcomeSH.rst

@@ -0,0 +1,92 @@
+.. _task_climatologyMapRiskIndexOutcomeSH:
+
+climatologyMapRiskIndexOutcomeSH
+================================
+
+An analysis task for plotting maps of Antarctic risk index outcome (rio) for navigation in ice-covered waters.
+
+Component and Tags::
+
+  component: seaIce
+  tags: climatology, horizontalMap, RiskIndexOutcome
+
+Configuration Options
+---------------------
+
+The following configuration options are available for this task::
+
+  [climatologyMapRiskIndexOutcomeSH]
+  ## options related to plotting maps of the Risk Index Outcome (RIO) for navigability
+  ## in sea-ice covered water from climatologies. The Risk Index Outcome is a navigability
+  ## metric defined by the International Maritime Organization (IMO). The index ranges
+  ## from -80 to 30. It depends on the sea-ice concentration and on Risk Index Values,
+  ## which are assigned to a vessel according to its structural properties and according
+  ## to ice thickness (and age). The maximum RIO refers to navigation in open water.
+  ## Navigation under conditions of negative RIO values is restricted to some types
+  ## of vessels. Navigation should generally be avoided where RIO < -10.
+
+  # table of Risk Index Values (IMO, MSC.1/Circ.1519 6 June 2016)
+  # https://www.imorules.com/GUID-2C1D86CB-5D58-490F-B4D4-46C057E1D102.html
+  rivSH = RIV/riv_MSC.1_Circ.1519_6_June_2016.csv
+
+  # colormap for model/observations
+  colormapNameResult = RdYlBu
+  # whether the colormap is indexed or continuous
+  colormapTypeResult = indexed
+  # color indices into colormapName for filled contours
+  colormapIndicesResult = [0, 56, 85, 170, 198, 227, 241, 248, 255, 255]
+  # colormap levels/values for contour boundaries
+  colorbarLevelsResult = numpy.linspace(-10., 30., 9)
+
+  # Months or seasons to plot (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
+  # Nov, Dec, JFM, AMJ, JAS, OND, ANN)
+  seasons =  ['AMJ', 'OND']
+
+  # comparison grid(s) on which to plot analysis
+  comparisonGrids = ['antarctic']
+
+  # Polar Class of vessels, according to IMO, for which RIO maps will be generated.
+  # Range is 1 to 12. Here the values 1-7 refer to the ‘Polar Classes’ PC1-PC7,
+  # assigned by the International Association of Classification Societies (IACS).
+  # A PC1 vessel is capable of year-round operations in all polar waters. PC2 and PC3
+  # vessels can navigate in 2.5 m (or more) thick ice. The values 8-11 correspond
+  # to the Finnish-Swedish ice classes 'IA Super', 'IA', 'IB' and 'IC'.
+  # The last value, 12, refers to ‘Not-Ice-Strengthened’ ships, all vessels without
+  # a Polar Class.
+  polarClass = 6
+
+  # reference floe thicknesses (m) for calculation of the Risk Index Value (RIV)
+  # The thicknesses are intended to render the type of ice as defined by IMO.
+  # There must be as many values as there are types of ice in the RIV table.
+  # The first value has to be zero.
+  h_to_typeofice = [0, 0.005, 0.1, 0.15, 0.3, 0.5, 0.7, 1, 1.2, 1.7, 2, 2.5]
+
+  # whether to use sea-ice categories for sea-ice concentration and thickness
+  useIceCategories = False
+
+  # minimum lat and reference lon for sea ice plots in the southern hemisphere
+  minimumLatitude = -50
+  referenceLongitude = 180
+
+  # arrange subplots vertically?
+  vertical = False
+
+The option ``vertical = True`` can be used to plot 3 panels one above another
+(resulting in a tall, thin image) rather than next to each other, the default
+(resulting in a short, wide image).
+
+For details on the remaining configuration options, see:
+ * :ref:`config_colormaps`
+ * :ref:`config_seasons`
+ * :ref:`config_comparison_grids`
+
+Observations
+------------
+:ref:`imo_riv`
+
+Example Result
+--------------
+
+.. image:: examples/risk_index_outcome_sh.png
+   :width: 720 px
+   :align: center

mpas_analysis/__main__.py

@@ -334,6 +334,12 @@ def build_analysis_list(config, controlConfig):
     analyses.append(sea_ice.ClimatologyMapSeaIceProduction(
         config=config, mpas_climatology_task=seaIceClimatologyTask,
         hemisphere='SH', control_config=controlConfig))
+    analyses.append(sea_ice.ClimatologyMapRiskIndexOutcome(
+        config=config, mpas_climatology_task=seaIceClimatologyTask,
+        hemisphere='NH', control_config=controlConfig))
+    analyses.append(sea_ice.ClimatologyMapRiskIndexOutcome(
+        config=config, mpas_climatology_task=seaIceClimatologyTask,
+        hemisphere='SH', control_config=controlConfig))
     analyses.append(sea_ice.ClimatologyMapSeaIceMelting(
         config=config, mpas_climatology_task=seaIceClimatologyTask,
         hemisphere='SH', control_config=controlConfig))

mpas_analysis/default.cfg

@@ -4804,6 +4804,120 @@ referenceLongitude = 180
 vertical = False
 
 
+[climatologyMapRiskIndexOutcomeNH]
+## options related to plotting maps of the Risk Index Outcome (RIO) for navigability
+## in sea-ice covered water from climatologies. The Risk Index Outcome is a navigability
+## metric defined by the International Maritime Organization (IMO). The index ranges
+## from -80 to 30. It depends on the sea-ice concentration and on Risk Index Values,
+## which are assigned to a vessel according to its structural properties and according
+## to ice thickness (and age). The maximum RIO refers to navigation in open water.
+## Navigation under conditions of negative RIO values is restricted to some types
+## of vessels. Navigation should generally be avoided where RIO < -10. 
+
+# table of Risk Index Values (IMO, MSC.1/Circ.1519 6 June 2016)
+# https://www.imorules.com/GUID-2C1D86CB-5D58-490F-B4D4-46C057E1D102.html
+rivNH = RIV/riv_MSC.1_Circ.1519_6_June_2016.csv
+
+# colormap for model/observations
+colormapNameResult = RdYlBu
+# whether the colormap is indexed or continuous
+colormapTypeResult = indexed
+# color indices into colormapName for filled contours
+colormapIndicesResult = [0, 56, 85, 170, 198, 227, 241, 248, 255, 255]
+# colormap levels/values for contour boundaries
+colorbarLevelsResult = numpy.linspace(-10., 30., 9)
+
+# Months or seasons to plot (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
+# Nov, Dec, JFM, AMJ, JAS, OND, ANN)
+seasons =  ['AMJ', 'OND']
+
+# comparison grid(s) on which to plot analysis
+comparisonGrids = ['arctic']
+
+# Polar Class of vessels, according to IMO, for which RIO maps will be generated.
+# Range is 1 to 12. Here the values 1-7 refer to the ‘Polar Classes’ PC1-PC7,
+# assigned by the International Association of Classification Societies (IACS).
+# A PC1 vessel is capable of year-round operations in all polar waters. PC2 and PC3
+# vessels can navigate in 2.5 m (or more) thick ice. The values 8-11 correspond
+# to the Finnish-Swedish ice classes 'IA Super', 'IA', 'IB' and 'IC'.
+# The last value, 12, refers to ‘Not-Ice-Strengthened’ ships, all vessels without
+# a Polar Class.
+polarClass = 6
+
+# reference floe thicknesses (m) for calculation of the Risk Index Value (RIV)
+# The thicknesses are intended to render the type of ice as defined by IMO.
+# There must be as many values as there are types of ice in the RIV table.
+# The first value has to be zero.
+h_to_typeofice = [0, 0.005, 0.1, 0.15, 0.3, 0.5, 0.7, 1, 1.2, 1.7, 2, 2.5]
+
+# whether to use sea-ice categories for sea-ice concentration and thickness
+useIceCategories = False
+
+# minimum lat and reference lon for sea ice plots in the northern hemisphere
+minimumLatitude = 50
+referenceLongitude = 0
+
+# arrange subplots vertically?
+vertical = False
+
+
+[climatologyMapRiskIndexOutcomeSH]
+## options related to plotting maps of the Risk Index Outcome (RIO) for navigability
+## in sea-ice covered water from climatologies. The Risk Index Outcome is a navigability
+## metric defined by the International Maritime Organization (IMO). The index ranges
+## from -80 to 30. It depends on the sea-ice concentration and on Risk Index Values,
+## which are assigned to a vessel according to its structural properties and according
+## to ice thickness (and age). The maximum RIO refers to navigation in open water.
+## Navigation under conditions of negative RIO values is restricted to some types
+## of vessels. Navigation should generally be avoided where RIO < -10. 
+
+# table of Risk Index Values (IMO, MSC.1/Circ.1519 6 June 2016)
+# https://www.imorules.com/GUID-2C1D86CB-5D58-490F-B4D4-46C057E1D102.html
+rivSH = RIV/riv_MSC.1_Circ.1519_6_June_2016.csv
+
+# colormap for model/observations
+colormapNameResult = RdYlBu
+# whether the colormap is indexed or continuous
+colormapTypeResult = indexed
+# color indices into colormapName for filled contours
+colormapIndicesResult = [0, 56, 85, 170, 198, 227, 241, 248, 255, 255]
+# colormap levels/values for contour boundaries
+colorbarLevelsResult = numpy.linspace(-10., 30., 9)
+
+# Months or seasons to plot (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
+# Nov, Dec, JFM, AMJ, JAS, OND, ANN)
+seasons =  ['AMJ', 'OND']
+
+# comparison grid(s) on which to plot analysis
+comparisonGrids = ['antarctic']
+
+# Polar Class of vessels, according to IMO, for which RIO maps will be generated.
+# Range is 1 to 12. Here the values 1-7 refer to the ‘Polar Classes’ PC1-PC7,
+# assigned by the International Association of Classification Societies (IACS).
+# A PC1 vessel is capable of year-round operations in all polar waters. PC2 and PC3
+# vessels can navigate in 2.5 m (or more) thick ice. The values 8-11 correspond
+# to the Finnish-Swedish ice classes 'IA Super', 'IA', 'IB' and 'IC'.
+# The last value, 12, refers to ‘Not-Ice-Strengthened’ ships, all vessels without
+# a Polar Class.
+polarClass = 6
+
+# reference floe thicknesses (m) for calculation of the Risk Index Value (RIV)
+# The thicknesses are intended to render the type of ice as defined by IMO.
+# There must be as many values as there are types of ice in the RIV table.
+# The first value has to be zero.
+h_to_typeofice = [0, 0.005, 0.1, 0.15, 0.3, 0.5, 0.7, 1, 1.2, 1.7, 2, 2.5]
+
+# whether to use sea-ice categories for sea-ice concentration and thickness
+useIceCategories = False
+
+# minimum lat and reference lon for sea ice plots in the southern hemisphere
+minimumLatitude = -50
+referenceLongitude = 180
+
+# arrange subplots vertically?
+vertical = False
+
+
 [climatologyMapSeaIceProductionNH]
 # options related to plotting horizontally remapped climatologies of
 # sea ice production against control model results and observations

mpas_analysis/obs/observational_datasets.xml

@@ -2157,6 +2157,54 @@
     </nameInDocs>
   </observation>
 
+  <observation>
+    <name>
+      Risk Index Values
+    </name>
+    <component>
+      seaice
+    </component>
+    <description>
+      This data set contains the Risk Index Values in Table 1.3 of the
+      International Maritime Organization rules within the Polar Operational 
+      Limit Assessment Risk Indexing System (POLARIS). The basis of POLARIS is 
+      an evaluation of the risks posed to the ship by ice conditions in relation 
+      to the ship's assigned ice class.
+    </description>
+    <source>
+      [International Maritime Organization (IMO) Rules Website](https://www.imorules.com/GUID-2C1D86CB-5D58-490F-B4D4-46C057E1D102.html)
+    </source>
+    <releasePolicy>
+      Unknown, openly available on website.
+    </releasePolicy>
+    <references>
+      [International Maritime Organization (2016)](https://www.imorules.com/GUID-2C1D86CB-5D58-490F-B4D4-46C057E1D102.html)
+    </references>
+    <bibtex>
+      @misc{IMO2016,
+      author = {International Maritime Organization},
+      title = {{Guidance on Methodologies for Assessing Operational Capabilities and Limitations in Ice}},
+      year = {2016},
+      howpublished = {{IMO Publications and Documents - Circulars - Maritime Safety Committee - MSC.1/Circular.1519 - Guidance on Methodologies for Assessing Operational Capabilities and Limitations in Ice - (6 June 2016) - Appendix - Methodology for Assessing Operational Capabilities and Limitations in Ice: Polar Operational Limit Assessment Risk Indexing System (POLARIS)}}
+      url = {https://www.imorules.com/GUID-2C1D86CB-5D58-490F-B4D4-46C057E1D102.html}
+      }
+    </bibtex>
+    <dataUrls>
+    </dataUrls>
+    <preprocessing>
+    </preprocessing>
+    <tasks>
+      - climatologyMapRiskIndexOutcomeNH
+      - climatologyMapRiskIndexOutcomeSH
+    </tasks>
+    <subdirectory>
+      SeaIce/RIV
+    </subdirectory>
+    <nameInDocs>
+      imo_riv
+    </nameInDocs>
+  </observation>
+
   <!-- ICEBERGS -->
 
   <observation>

mpas_analysis/sea_ice/__init__.py

@@ -31,3 +31,5 @@
     ClimatologyMapSeaIceSnowMelt
 from mpas_analysis.sea_ice.climatology_map_area_pond import \
     ClimatologyMapSeaIcePondArea
+from mpas_analysis.sea_ice.climatology_map_risk_index_outcome import \
+    ClimatologyMapRiskIndexOutcome