Add MpasClimatologyTask and RemapMpasClimatologySubtask

README.md

@@ -83,6 +83,33 @@ for more details.
      `--generate` flag on the command line.  See the comments in
      `mpas_analysis/config.default` for more details on this option.
 
+## List of MPAS output files that are needed by MPAS-Analysis:
+
+  * mpas-o files:
+      * `mpaso.hist.am.timeSeriesStatsMonthly.*.nc` (Note: since OHC
+        anomalies are computed wrt the first year of the simulation,
+        if OHC diagnostics is activated, the analysis will need the
+        first full year of `mpaso.hist.am.timeSeriesStatsMonthly.*.nc`
+        files, no matter what `[timeSeries]/startYear` and
+        `[timeSeries]/endYear`  are. This is especially important to know if
+        short term archiving is used in the run to analyze: in that case, set
+        `[input]/runSubdirectory`, `[input]/oceanHistorySubdirectory` and
+        `[input]/seaIceHistorySubdirectory` to the appropriate run and archive
+        directories and choose `[timeSeries]/startYear` and
+        `[timeSeries]/endYear` to include only data that have been short-term
+        archived).
+      * `mpaso.hist.am.meridionalHeatTransport.0001-03-01.nc` (or any
+        `hist.am.meridionalHeatTransport` file)
+      * `mpaso.rst.0002-01-01_00000.nc` (or any other mpas-o restart file)
+      * `streams.ocean`
+      * `mpas-o_in`
+  * mpas-cice files:
+      * `mpascice.hist.am.timeSeriesStatsMonthly.*.nc`
+      * `mpascice.rst.0002-01-01_00000.nc` (or any other mpas-cice restart
+        file)
+      * `streams.cice`
+      * `mpas-cice_in`
+
 ## Purge Old Analysis
 
 To purge old analysis (delete the whole output directory) before running run

docs/api.rst

@@ -11,12 +11,12 @@ Top-level script: run_mpas_analysis
 .. autosummary::
    :toctree: generated/
 
-   run_mpas_analysis.update_generate
-   run_mpas_analysis.run_parallel_tasks
-   run_mpas_analysis.wait_for_task
    run_mpas_analysis.build_analysis_list
    run_mpas_analysis.determine_analyses_to_generate
+   run_mpas_analysis.add_task_and_subtasks
+   run_mpas_analysis.update_generate
    run_mpas_analysis.run_analysis
+   run_mpas_analysis.wait_for_task
 
 
 Analysis tasks
@@ -32,7 +32,9 @@ Base Class
 
    AnalysisTask
    AnalysisTask.setup_and_check
-   AnalysisTask.run_analysis
+   AnalysisTask.run_task
+   AnalysisTask.run_after
+   AnalysisTask.add_subtask
    AnalysisTask.run
    AnalysisTask.check_generate
    AnalysisTask.check_analysis_enabled
@@ -109,17 +111,20 @@ Climatology
 .. autosummary::
    :toctree: generated/
 
-   get_lat_lon_comparison_descriptor
+   get_comparison_descriptor
+   get_antarctic_stereographic_projection
    get_remapper
-   get_mpas_climatology_dir_name
    get_observation_climatology_file_names
    compute_monthly_climatology
    compute_climatology
-   cache_climatologies
-   update_climatology_bounds_from_file_names
    add_years_months_days_in_month
-   remap_and_write_climatology
-   compute_climatologies_with_ncclimo
+
+   MpasClimatologyTask
+   MpasClimatologyTask.add_variables
+   MpasClimatologyTask.get_file_name
+
+   RemapMpasClimatologySubtask
+   RemapMpasClimatologySubtask.get_file_name
 
 Time Series
 -----------

mpas_analysis/analysis_task_template.py

@@ -85,7 +85,7 @@ class MyTask(AnalysisTask):  # {{{
     #        def __init__(self, config, fieldName):...
     #    and yu would then make a new task something like this:
     #        myTask = MyTask(config, fieldName='seaIceArea')
-    def __init__(self, config, myArg='myDefaultValue'):  # {{{
+    def __init__(self, config, prerequsiteTask, myArg='myDefaultValue'):  # {{{
         '''
         Construct the analysis task.
         <Add any additional description of what happens during construction>
@@ -95,9 +95,15 @@ def __init__(self, config, myArg='myDefaultValue'):  # {{{
         config :  instance of MpasAnalysisConfigParser
             Contains configuration options
 
+        prerequsiteTask : ``AnotherTaskClass``
+            <This could be a task that needs to run before this task, a
+            prerequisite.  For example, a task for computing a climatology
+            that this task will then plot.>
+
         myArg : str, optional
             <Describe the arg, or just remove remove it>
 
+
         Authors
         -------
         <List of authors>
@@ -136,6 +142,40 @@ def __init__(self, config, myArg='myDefaultValue'):  # {{{
         # Example:
         # self.fieldName = fieldName
 
+        # If you need to, you can add task that needs to run before this task
+        # (a prerequisite), just add it as follows:
+        self.prerequsiteTask = prerequsiteTask
+        self.run_after(prerequsiteTask)
+
+        # You may want to break this task into several subtasks that can run
+        # in parallel with one another or one after the other, depending on
+        # how you set them up.
+        #
+        # An example where the subtasks run in parallel with one another:
+        for season in ['JFM', 'JAS', 'ANN']:
+            subtask = MySubtask(parentTask=self, season=season)
+            self.add_subtask(subtask)
+
+        # An example where the subtasks run in sequence because each one
+        # depends on the previous one
+        remapObservations = MyRemapObservationsSubtask(parentTask=self)
+        # You can make sure MyRemapObservationsSubtask also runs after the
+        # prerequisite task:
+        remapObservations.run_after(prerequsiteTask)
+        self.add_subtask(remapObservations)
+
+        plotObservations = MyPlotObservationsSubtask(
+                remapObservations=remapObservations)
+        # This is the part that makes sure MyPlotObservationsSubtask runs after
+        # MyRemapObservationsSubtask.  Note: you might do this inside of
+        # MyPlotObservationsSubtask instead of here.
+        plotObservations.run_after(remapObservations)
+        self.add_subtask(plotObservations)
+
+        # Note: I have not included stubs for MyRemapObservationsSubtask and
+        # MyPlotObservationsSubtask but they would be qualitatively similar
+        # to MySubtask below.
+
         # }}}
 
     # this function will be called to figure out if the analysis task should
@@ -349,10 +389,35 @@ def _make_plot(self, plotParameter, optionalArgument=None):  # {{{
             imageDescription=caption,
             imageCaption=caption)
 
-
-        #
         # }}}
 
+
+class MySubtask(AnalysisTask):
+    def __init__(self, parentTask, season):
+        self.parentTask = parentTask
+        self.season = season
+        super(MySubtask, self).__init__(
+                config=parentTask.config,
+                taskName=parentTask.taskName,
+                subtaskName=season,
+                componentName=parentTask.component,
+                tags=parentTask.tags)
+
+    def setup_and_check(self):
+        # do whatever setup is needed for the subtask.  You don't have
+        # to redundantly do setup that happened in parentTask because
+        # you can access its fields if needed
+        assert(self.parentTask.streamName ==
+               'timeSeriesStatsMonthlyOutput')
+
+    def run_analsysis(self):
+        # do the main action of the subplot.  Note: you can't access any
+        # fields created when parentTask runs for 2 reasions: 1) parentTask
+        # runs after this task and 2) parentTask and all other tasks may
+        # run in a separate process from this task so the data will not be
+        # communicated to this process.
+        pass
+
 # }}}
 
 # vim: foldmethod=marker ai ts=4 sts=4 et sw=4 ft=python

mpas_analysis/config.default

@@ -522,7 +522,10 @@ colorbarLevelsDifference = [-5, -3, -2, -1, 0, 1, 2, 3, 5]
 
 # Times for comparison times (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
 # Nov, Dec, JFM, AMJ, JAS, OND, ANN)
-comparisonTimes =  ['JFM', 'JAS', 'ANN']
+seasons =  ['JFM', 'JAS', 'ANN']
+
+# comparison grid(s) ('lonlat', 'anatarctic') on which to plot analysis
+comparisonGrids = ['latlon']
 
 [climatologyMapSSS]
 ## options related to plotting horizontally remapped climatologies of
@@ -544,7 +547,10 @@ colorbarLevelsDifference = [-3, -2, -1, -0.5, 0, 0.5, 1, 2, 3]
 
 # Times for comparison times (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
 # Nov, Dec, JFM, AMJ, JAS, OND, ANN)
-comparisonTimes =  ['JFM', 'JAS', 'ANN']
+seasons =  ['JFM', 'JAS', 'ANN']
+
+# comparison grid(s) ('lonlat', 'anatarctic') on which to plot analysis
+comparisonGrids = ['latlon']
 
 [climatologyMapMLD]
 ## options related to plotting horizontally remapped climatologies of
@@ -566,7 +572,10 @@ colorbarLevelsDifference = [-150, -80, -30, -10, 0, 10, 30, 80, 150]
 
 # Times for comparison times (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
 # Nov, Dec, JFM, AMJ, JAS, OND, ANN)
-comparisonTimes =  ['JFM', 'JAS', 'ANN']
+seasons =  ['JFM', 'JAS', 'ANN']
+
+# comparison grid(s) ('lonlat', 'anatarctic') on which to plot analysis
+comparisonGrids = ['latlon']
 
 [climatologyMapSeaIceConcNH]
 ## options related to plotting horizontally remapped climatologies of