Fix issues with drydep plots; Abstract some benchmark utilities code

In this commit, we have fixed issues in the creation of drydep velocity
plots.  We have also taken steps to start abstracting commonly-used
benchmark code into reusable functions in benchmark_utils.py.  This
process will be continued in subsequent PRs.

gcpy/benchmark/modules/benchmark_drydep.py
- Remove unused imports
- Add the "collection" keyword argument
- Rename "datestr" argument to "subdst" for consistency w/ other routines
- Set weightsdir to "." by default
- Set default spcdb_dir to gcpy/species_database.yml
- Updated Pydoc comments
- Removed "plots" argument, as we only have drydep at the surface
- Now call make_output_dir from benchmark_utils.py to make the
  directory where plots will be placed
- Now call read_ref_and_dev tfrom benchmark_utils.py to read
  ref & dev data from disk
- Update the call to get_common_varnames from benchmark_utils.py
- Abstract the code to create the PDF filename to routine "pdf_filename"
  in benchmark_utils.py
- Remove refmetds and devmetds, they're not needed here
- Remove "normalize_by_area" keyword to compare_single_level
- Now pass "log_color_scale" to compare_single_level
- Abstract code to print significant differences to benchmark_utils.py

gcpy/benchmark_utils.py
- Updated Pydoc headers
- Removed unused imports
- Renamed "make_collection_subdir" to "make_output_dir" and simplify code
- Update code in read_ref_and_dev
- Fix bugs in routine "get_common_varnames", add Pydoc
- Add routines "print_sigdiffs" and "write_sigdiff" (needs testing)
- Add routine "pdf_filename" to get the name of the PDF output file
- Add routine "print_benchmark_info" to print a list of which
  benchmark plots/tables will be created.  This is called from the
  run_benchmark, run_1yr_fullchem_benchmark, run_1yr_tt_benchmark
  functions.

gcpy/benchmark/modules/run_1yr_fullchem_benchmark.py
- Now import and call "make_benchmark_drydep_plots" from
  "benchmark_drydep.py"
- Now call "print_benchmark_info" from "benchmark_utils.py" to display
  the list of plots/tables being generated

gcpy/benchmark/run_benchmark.py
gcpy/benchmark/modules/run_1yr_fullchem_benchmark.py
- Now call "print_benchmark_info" from "benchmark_utils.py" to display
  the list of plots/tables being generated

CHANGELOG.md
- Updated accordingly

Signed-off-by: Bob Yantosca <[email protected]>

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to GCPy will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased] - TBD
+### Added
+- Script `gcpy/benchmark/modules/benchmark_utils.py`, with common benchmark utility functions
+- Script `gcpy/benchmark/modules/benchmark_drydep.py`, with code to create drydep velocity plots
+- YAML tag `plot_drydep` in `gcpy/benchmark/config/*.yml` files
+
 ### Changed
 - YAML tag `operations_budget` is now `ops_budget_table` in `gcpy/benchmark/config/1yr_tt_benchmark.yml`
 

gcpy/benchmark/modules/benchmark_drydep.py

@@ -5,9 +5,7 @@
 import gc
 import numpy as np
 from gcpy import util
-from gcpy.constants import skip_these_vars
 from gcpy.plot.compare_single_level import compare_single_level
-from gcpy.plot.compare_zonal_mean import compare_zonal_mean
 import gcpy.benchmark.modules.benchmark_utils as bmk_util
 
 # Suppress numpy divide by zero warnings to prevent output spam
@@ -19,18 +17,18 @@ def make_benchmark_drydep_plots(
         refstr,
         dev,
         devstr,
-        collection,
+        collection="DryDep",
         dst="./benchmark",
+        subdst=None,
         cmpres=None,
-        datestr=None,
         overwrite=False,
         verbose=False,
         log_color_scale=False,
-        weightsdir=".".
+        weightsdir=".",
+        sigdiff_files=None,
         n_job=-1,
         time_mean=False,
-        spcdb_dir=None,
-        var_prefix="DryDepVel"
+        spcdb_dir=os.path.join(os.path.dirname(__file__), "..", "..")
 ):
     """
     Creates six-panel comparison plots (PDF format) from GEOS-Chem
@@ -48,18 +46,20 @@ def make_benchmark_drydep_plots(
             data set.
         devstr: str
             A string to describe dev (e.g. version number)
-        collection: str
-            String name of collection to plot comparisons for.
 
     Keyword Args (optional):
+        collection : str
+            Name of the diagnostic collection (e.g. "DryDep")
         dst: str
             A string denoting the destination folder where a PDF
             file containing plots will be written.
             Default value: ./benchmark
-        datestr: str
-            A string with date information to be included in both the
-            plot pdf filename and as a destination folder subdirectory
-            for writing plots
+        subdst: str
+            A string denoting the sub-directory of dst where PDF
+            files containing plots will be written.  In practice,
+            subdst is only needed for the 1-year benchmark output,
+            and denotes a date string (such as "Jan2016") that
+            corresponds to the month that is being plotted.
             Default value: None
         benchmark_type: str
             A string denoting the type of benchmark output to plot, options are
@@ -72,13 +72,6 @@ def make_benchmark_drydep_plots(
         verbose: bool
             Set this flag to True to print extra informational output.
             Default value: False.
-        plots: list of strings
-            List of plot types to create.
-            Default value: ['sfc', '500hpa', 'zonalmean']
-        normalize_by_area: bool
-            Set this flag to true to enable normalization of data
-            by surfacea area (i.e. kg s-1 --> kg s-1 m-2).
-            Default value: False
         n_job: int
             Defines the number of simultaneous workers for parallel plotting.
             Set to 1 to disable parallel plotting. Value of -1 allows the
@@ -90,58 +83,51 @@ def make_benchmark_drydep_plots(
         time_mean : bool
             Determines if we should average the datasets over time
             Default value: False
-        var_prefix : str
-            If 
     """
 
-    # Create destination plot directory
-    bmk_util.make_directory(dst, overwrite)
-    target_dst = bmk_util.make_collection_subdir(dst, collection, datestr)
-
-    # Defaults for arguments
-    if plots is None:
-        plots = ["sfc", "500hpa", "zonalmean"]
-    if spcdb_dir is None:
-        spcdb_dir = os.path.join(os.path.dirname(__file__), "..", "..")
+    # Create directory for plots (if it doesn't exist)
+    dst = bmk_util.make_output_dir(
+        dst,
+        collection,
+        subdst,
+        overwrite=overwrite,
+    )
 
     # Read data
-    refds, devds = bmk.util_read_ref_and_dev(ref, dev, time_mean)
-    if refmet is not None and devmet is not None:
-        refmetds, devmetds = bmk_util.read_ref_and_dev(ref, dev, time_mean)
-
-    # Make sure that Ref and Dev datasets have the same variables.
-    # Variables that are in Ref but not in Dev will be added to Dev
-    # with all missing values (NaNs). And vice-versa.
-    # Turn this off for now since add_missing_variables inserts GCC area into
-    # GCHP files, which causes problems with area normalization (ewl)
-    #[refds, devds] = add_missing_variables(refds, devds)
+    refdata, devdata = bmk_util.read_ref_and_dev(
+        ref,
+        dev,
+        time_mean=time_mean
+    )
 
     # Get common variables between Ref and Dev
     varlist = bmk_util.get_common_varnames(
-        refds, 
-        devds, 
-        var_prefix=var_prefix
+        refdata,
+        devdata,
+        prefix="DryDepVel_",
         verbose=verbose
     )
-
-    # Surface plots
-    plotfilename = f"{collection}_Surface.pdf"
-    if datestr is not None:
-        plotfilename = f"{collection}_Surface_{datestr}.pdf"
-    pdfname = os.path.join(target_dst, plotfilename)
+
+    # Create surface plots
+    sigdiff_list = []
+    pdfname = bmk_util.pdf_filename(
+        dst,
+        collection,
+        subdst,
+        plot_type="Surface"
+    )
     compare_single_level(
-        refds,
+        refdata,
         refstr,
-        devds,
+        devdata,
         devstr,
         varlist=varlist,
         cmpres=cmpres,
         ilev=0,
-        refmet=refmetds,
-        devmet=devmetds,
         pdfname=pdfname,
-        normalize_by_area=normalize_by_area,
-        extra_title_txt=datestr,
+        log_color_scale=log_color_scale,
+        extra_title_txt=subdst,
+        sigdiff_list=sigdiff_list,
         weightsdir=weightsdir,
         n_job=n_job,
         spcdb_dir=spcdb_dir
@@ -150,16 +136,20 @@ def make_benchmark_drydep_plots(
         pdfname,
         varlist,
         remove_prefix=collection + '_',
-        verbose=verbose)
-
+        verbose=verbose
     )
 
+    # Write significant differences to file (if there are any)
+    bmk_util.print_sigdiffs(
+        sigdiff_files,
+        sigdiff_list,
+        diff_type="sfc",
+        diff_title="DryDepVel"
+    )
 
     # -------------------------------------------
     # Clean up
     # -------------------------------------------
-    del refds
-    del devds
-    del refmetds
-    del devmetds
+    del refdata
+    del devdata
     gc.collect()