Merge pull request #285 from rschwant/develop

fix regulatory calcualtions and add example on docs

docs/examples/control_wrfchem_mech-0905_2.yaml

@@ -217,7 +217,7 @@ plots:
     domain_name: ["CONUS"]
     region_name: ['epa_region']
     region_list: ['R1','R2','R3','R4','R5','R6','R7','R8','R9','R10'] 
-    model_name_list: ['AirNow','WRF-Chem','WRF-Chem vcp']
+    model_name_list: ['AirNow','RACM_ESRL','RACM_ESRL_VCP']
     data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
     data_proc:
       rem_obs_nan: True
@@ -233,7 +233,7 @@ plots:
     domain_name: ["CONUS",'R1']
     threshold_list: [10,20,30,40,50,60,70,80,90,100]
     score_name: 'Critical Success Index'  #can be used 'Critical Success Index' 'False Alarm Rate' 'Hit Rate'
-    model_name_list: ['AirNow','WRF-Chem','WRF-Chem vcp']
+    model_name_list: ['RACM_ESRL','RACM_ESRL_VCP']
     data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
     data_proc:
       rem_obs_nan: True

docs/examples/control_wrfchem_mech-0905_2_reg.yaml

@@ -0,0 +1,294 @@
+# General Description:
+# - Any key that is specific for a plot type will begin with `ts` for timeseries, `ty` for taylor.
+# - Some keys/groups are optional.
+# - For now, all plots except time series average over the analysis window.
+# - Setting axis values
+#   - If set_axis = True in data_proc section of each plot_grp,
+#     the yaxis for the plot will be set based on the values
+#     specified in the obs section for each variable.
+#   - If set_axis is set to False, then defaults will be used.
+#   - 'vmin_plot' and 'vmax_plot' are needed for
+#     'timeseries', 'spatial_overlay', and 'boxplot'.
+#   - 'vdiff_plot' is needed for 'spatial_bias' plots
+#   - 'ty_scale' is needed for 'taylor' plots.
+#   - 'nlevels' or the number of levels used in the contour plot can also optionally be provided for spatial_overlay plot.
+#   - If set_axis = True and the proper limits are not provided in the obs section,
+#     a warning will print, and the plot will be created using the default limits.
+analysis:
+  start_time: "2019-09-04-06:00:00" # UTC
+  end_time: "2019-09-06-05:00:00" # UTC
+  output_dir: ./output/airnow_wrfchem_reg  # relative to the program using this control file
+  #   Currently, the directory must exist or plot saving will error and fail.
+  debug: True
+
+model:
+  RACM_ESRL: # model label
+    files: example:wrfchem:racm_esrl_reg
+    mod_type: "wrfchem"
+    mod_kwargs:
+      mech: "racm_esrl_vcp"
+      surf_only_nc: True  # specify that we have only one vertical level; WRF-Chem specific
+    radius_of_influence: 12000 # meters
+    mapping: # of _model_ species name to _obs_ species name
+      airnow: # specifically for the obs labeled 'airnow'
+        PM2_5_DRY: "PM2.5"
+        o3: "OZONE"
+    projection: ~
+    plot_kwargs: # optional
+      color: "magenta"
+      marker: "s"
+      linestyle: "-"
+  RACM_ESRL_VCP:
+    files: example:wrfchem:racm_esrl_vcp_reg
+    mod_type: "wrfchem"
+    mod_kwargs:
+      mech: "racm_esrl_vcp"
+      surf_only_nc: True
+    radius_of_influence: 12000
+    mapping:
+      airnow:
+        PM2_5_DRY: "PM2.5"
+        o3: "OZONE"
+    projection: ~
+    plot_kwargs:
+      color: "gold"
+      marker: "o"
+      linestyle: "-"
+
+obs:
+  airnow: # obs label
+    use_airnow: True
+    filename: example:airnow:2019-09
+    obs_type: pt_sfc
+    variables: # optional
+      OZONE:
+        unit_scale: 1
+        # ^ optional; Scaling factor
+        unit_scale_method: "*"
+        # ^ optional; Multiply = '*' , Add = '+', subtract = '-', divide = '/'
+        nan_value: -1.0
+        # ^ optional; When loading data, set this value to NaN
+        ylabel_plot: "Ozone (ppbv)"
+        # optional; set ylabel in order to include units and/or other info
+        vmin_plot: 15.0
+        # ^ optional; Min for y-axis during plotting.
+        #   To apply to a plot, change restrict_yaxis = True.
+        vmax_plot: 55.0
+        # ^ optional; Max for y-axis during plotting.
+        #   To apply to a plot, change restrict_yaxis = True.
+        vdiff_plot: 20.0
+        # ^ optional; +/- range to use in bias plots.
+        #   To apply to a plot, change restrict_yaxis = True.
+        nlevels_plot: 21
+        # ^ optional; number of levels used in colorbar for contourf plot.
+        regulatory: True #Opt compute regulatory functions
+        ylabel_reg_plot: 'MDA8 O3 (ppbv)'
+        vmin_reg_plot: 30.0 #Opt
+        vmax_reg_plot: 70.0 #Opt
+        vdiff_reg_plot: 20.0 #Opt
+        #percentile_opt: 95 #Opt, 5, 50, 95, etc. If not specified, simply calculate mean values. Currently used for "spatial_bias".
+      PM2.5:
+        unit_scale: 1
+        unit_scale_method: "*"
+        # obs_min: 0
+        # ^ optional; set all values less than this value to NaN
+        # obs_max: 100
+        # ^ optional; set all values greater than this value to NaN
+        nan_value: -1.0
+        # Note: The obs_min, obs_max, and nan_values are set to NaN first
+        # and then the unit conversion is applied.
+        ylabel_plot: "PM2.5 (ug/m3)"
+        ty_scale: 2.0 # optional; `ty_` indicates for Taylor diagram plot
+        vmin_plot: 0.0
+        vmax_plot: 22.0
+        vdiff_plot: 15.0
+        nlevels_plot: 23
+        regulatory: True #Opt compute regulatory functions
+        ylabel_reg_plot: 'PM2.5_24hr (ug/m3)'
+        vmin_reg_plot: 0.0 #Opt
+        vmax_reg_plot: 22.0 #Opt
+        vdiff_reg_plot: 15.0 #Opt
+        #percentile_opt: 95 #Opt, 5, 50, 95, etc. If not specified, simply calculate mean values. Currently used for "spatial_bias".
+
+plots:
+  plot_grp1:
+    type: "timeseries" # plot type
+    fig_kwargs: # optional; to define figure options
+      figsize: [12, 6] # figure size (width, height) in inches
+    default_plot_kwargs:
+      # ^ optional; Define defaults for all plots.
+      #   Important: Model kwargs overwrite these.
+      linewidth: 2.0
+      markersize: 10.
+    text_kwargs: # optional
+      fontsize: 24.
+    domain_type: ["all", "state_name", "epa_region"]
+    # ^ List of domain types: 'all' or any domain in obs file.
+    #   (e.g., airnow: epa_region, state_name, siteid, etc.)
+    domain_name: ["CONUS", "CA", "R9"]
+    # ^ List of domain names. If domain_type = all,
+    #   the domain name is used in the plot title.
+    data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
+    # ^ make this a list of pairs in obs_model
+    #   where the obs is the obs label and model is the model_label
+    data_proc: # optional??
+      rem_obs_nan: True
+      # ^ True: Remove all points where model or obs variable is NaN.
+      #   False: Remove only points where model variable is NaN.
+      ts_select_time: "time_local"  # `ts_` indicates this is time series plot-specific
+      # ^ Time used for avg and plotting
+      #   Options: 'time' for UTC or 'time_local'
+      ts_avg_window: "D"
+      # ^ Options: None for no averaging, pandas resample rule (e.g., 'h', 'D')
+      set_axis: True
+      # ^ If true, add `vmin_plot` and `vmax_plot` for each variable in obs.
+
+  plot_grp2:
+    type: "taylor"
+    fig_kwargs:
+      figsize: [8, 8]
+    default_plot_kwargs:
+      linewidth: 2.0
+      markersize: 10.
+    text_kwargs:
+      fontsize: 16.
+    domain_type: ["all"]
+    domain_name: ["CONUS"]
+    data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
+    data_proc:
+      rem_obs_nan: True
+      set_axis: True
+
+  plot_grp3:
+    type: "spatial_bias"
+    fig_kwargs: # optional; For all spatial plots, specify map_kwargs here too.
+      states: True  # such as whether to show the state boundaries
+      figsize: [10, 5]
+    text_kwargs:
+      fontsize: 16.
+    domain_type: ["all",]
+    domain_name: ["CONUS"]
+    data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
+    data_proc:
+      rem_obs_nan: True
+      set_axis: True
+
+#Spatial overlay plots are not yet available for reg options
+#  plot_grp4:
+#    type: "spatial_overlay"
+#    fig_kwargs:
+#      states: True
+#      figsize: [10, 5]
+#    text_kwargs:
+#      fontsize: 16.
+#    domain_type: ["all", "epa_region"]
+#    domain_name: ["CONUS", "R9"]
+#    data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
+#    data_proc:
+#      rem_obs_nan: True
+#      set_axis: True
+
+  plot_grp5:
+    type: "boxplot"
+    fig_kwargs:
+      figsize: [8, 6]
+    text_kwargs:
+      fontsize: 20.
+    domain_type: ["all"]
+    domain_name: ["CONUS"]
+    data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
+    data_proc:
+      rem_obs_nan: True
+      set_axis: False
+
+  plot_grp5_5:
+    type: "spatial_bias_exceedance"
+    fig_kwargs:
+      states: True
+      figsize: [10, 5]
+    text_kwargs:
+      fontsize: 16.
+    domain_type: ["all"]
+    domain_name: ["CONUS"]
+    data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
+    data_proc:
+      rem_obs_nan: True
+      set_axis: False
+
+#Scorecard plots are not yet available for reg options
+#  plot_grp6:
+#    type: "scorecard"
+#    fig_kwargs:
+#      figsize: [15, 10]
+#    text_kwargs:
+#      fontsize: 20.
+#    domain_type: ["all"]
+#    domain_name: ["CONUS"]
+#    region_name: ['epa_region']
+#    region_list: ['R1','R2','R3','R4','R5','R6','R7','R8','R9','R10']
+#    urban_rural_name: ['msa_name']
+#    urban_rural_differentiate_value: ''
+#    better_or_worse_method: 'NME'    #support 'RMSE', 'IOA' ,' NMB', 'NME'
+#    model_name_list: ['AirNow','RACM_ESRL','RACM_ESRL_VCP']
+#    data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
+#    data_proc:
+#      rem_obs_nan: True
+#      set_axis: False
+
+  plot_grp7:
+    type: "multi_boxplot"
+    fig_kwargs:
+      figsize: [10, 8]
+    text_kwargs:
+      fontsize: 20.
+    domain_type: ["all"]
+    domain_name: ["CONUS"]
+    region_name: ['epa_region']
+    region_list: ['R1','R2','R3','R4','R5','R6','R7','R8','R9','R10'] 
+    model_name_list: ['AirNow','RACM_ESRL','RACM_ESRL_VCP']
+    data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
+    data_proc:
+      rem_obs_nan: True
+      set_axis: False
+
+  plot_grp8:
+    type: "csi"
+    fig_kwargs:
+      figsize: [10, 8]
+    text_kwargs:
+      fontsize: 20.
+    domain_type: ["all",'epa_region']
+    domain_name: ["CONUS",'R9']
+    threshold_list: [10,20,30,40,50,60,70,80,90,100]
+    score_name: 'Critical Success Index'  #can be used 'Critical Success Index' 'False Alarm Rate' 'Hit Rate'
+    model_name_list: ['RACM_ESRL','RACM_ESRL_VCP']
+    data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]
+    data_proc:
+      rem_obs_nan: True
+      set_axis: False
+
+stats:
+  # Stats require positive numbers, so if you want to calculate temperature use Kelvin!
+  # Wind direction has special calculations for AirNow if obs name is 'WD'
+  stat_list: ["MB", "MdnB", "R2", "RMSE"]
+  # ^ List stats to calculate. Dictionary of definitions included
+  #   in submodule `plots/proc_stats`. Only stats listed below are currently working.
+  #   Full calc list:
+  #   ['STDO', 'STDP', 'MdnNB','MdnNE','NMdnGE',
+  #    'NO', 'NOP', 'NP', 'MO', 'MP', 'MdnO', 'MdnP',
+  #    'RM', 'RMdn', 'MB', 'MdnB', 'NMB', 'NMdnB', 'FB',
+  #    'ME','MdnE','NME', 'NMdnE', 'FE', 'R2', 'RMSE','d1',
+  #    'E1', 'IOA', 'AC']
+  round_output: 2 # optional; defaults to rounding to 3rd decimal place
+  output_table: False
+  # ^ Always outputs a .txt file.
+  #   Optional to also output a Matplotlib figure table (image).
+  output_table_kwargs: # optional
+    figsize: [7, 3]
+    fontsize: 12.
+    xscale: 1.4
+    yscale: 1.4
+    edges: "horizontal"
+  domain_type: ["all"]
+  domain_name: ["CONUS"]
+  data: ["airnow_RACM_ESRL", "airnow_RACM_ESRL_VCP"]

docs/examples/intro_examples.rst

@@ -13,6 +13,10 @@ Three examples compare AirNow surface observations to model data:
 * :doc:`camchem`
 * :doc:`airnow_camchem_se`
 
+This example compares AirNow surface observations to model data for the regulatory metrics of MDA8 ozone and 24 hour PM\ :sub:`2.5`\:
+
+* :doc:`airnow_wrfchem_reg`
+
 Other examples:
 
 * :doc:`idealized`

docs/examples/output/airnow_wrfchem_reg/.gitignore

@@ -0,0 +1 @@
+*.png

docs/examples/output/airnow_wrfchem_reg/stats.OZONE_reg.all.CONUS.2019-09-04_06.2019-09-06_05.csv

@@ -0,0 +1,5 @@
+Stat_ID,Stat_FullName,airnow_RACM_ESRL,airnow_RACM_ESRL_VCP
+MB,Mean_Bias,2.5,1.2
+MdnB,Median_Bias,2.73,1.43
+R2,Coefficient_of_Determination_(R2),0.63,0.59
+RMSE,Root_Mean_Square_Error,8.52,8.63

docs/examples/output/airnow_wrfchem_reg/stats.PM2.5_reg.all.CONUS.2019-09-04_06.2019-09-06_05.csv

@@ -0,0 +1,5 @@
+Stat_ID,Stat_FullName,airnow_RACM_ESRL,airnow_RACM_ESRL_VCP
+MB,Mean_Bias,1.99,1.94
+MdnB,Median_Bias,1.68,1.67
+R2,Coefficient_of_Determination_(R2),0.33,0.33
+RMSE,Root_Mean_Square_Error,4.8,4.71

docs/getting_started/installation.rst

@@ -30,20 +30,32 @@ General instructions
 --------------------
 
 If you are a user and are not planning to modify MELODIES MONET itself,
-installing it is relatively simple.
-The stable branch of MELODIES MONET (``main``) should always be compatible with the
+installing it is relatively simple. There are two methods available.
+
+Option 1) Using Conda
+^^^^^^^^^^^^^^^^^^^^^
+We have recently created a conda-forge release of MELODIES MONET to make installation very simple 
+with just 1 line of code below::
+
+    $ conda create --name melodies-monet -y -c conda-forge python=3.9 melodies-monet wrf-python jupyterlab
+
+.. note::
+   Currently, the wrf-python conda package is not compatible with Apple Silicon (Apple machines using Intel should be fine). If you need to run the WRF-Chem reader and only have access to a machine using Apple Silicon, you can try compiling it from source code from the official repos.
+
+Option 2) Using Conda and GitHub
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You are also welcome to install using our old method. The stable branch of MELODIES MONET (``main``) 
+should always be the same as the conda-forge release of MELODIES MONET and be compatible with the
 conda-forge releases of MONET/MONETIO.
+
 First create and activate a conda environment::
 
     $ conda create --name melodies-monet python=3.9
     $ conda activate melodies-monet
 
 Add dependencies from conda-forge::
 
-    $ conda install -y -c conda-forge pyyaml pandas=1 'matplotlib-base<3.9' monet monetio netcdf4 wrf-python typer rich pooch
-
-.. note::
-   Currently, the wrf-python conda package is not compatible with Apple Silicon (Apple machines using Intel should be fine). If you need to run the WRF-Chem reader and only have access to a machine using Apple Silicon, you can try compiling it from souce code from the official repos.
+    $ conda install -y -c conda-forge pyyaml pandas=1 'matplotlib-base<3.9' monet monetio netcdf4 wrf-python typer rich pooch jupyterlab
    
 Now, install the stable branch of MELODIES MONET to the environment::
 

docs/index.rst

@@ -78,6 +78,7 @@ MONETIO please refer to:
    examples/intro_examples
    examples/tutorial-data
    examples/airnow_wrfchem
+   examples/airnow_wrfchem_reg
    examples/airnow_camchem_se
    examples/camchem
    examples/idealized

docs/users_guide/supported_diagnostics.rst

@@ -8,7 +8,7 @@ Calculating Regulatory Metrics
 
 MDA8 (8-hour daily maximum) ozone and 24 hour average PM\ :sub:`2.5` \ can be
 calculated within MELODIES MONET from hourly observational and model data. All plots
-except for the "spatial_overlay" plot and all stats will work with the regulatory
+except for the ``spatial_overlay`` and ``scorecard`` plots and all stats will work with the regulatory
 metrics.
 
 The MDA8 ozone metric is calculated based on the following: