Meteorological Evaluation Toolkit + smaller bug fixes

docs/appendix/yaml.rst

@@ -19,6 +19,7 @@ General Rules
   * spatial_overlay - average over entire analysis window
   * spatial_overlay_exceedance - number of exceedances within the analysis window 
   * boxplot - calculated over entire analysis window
+  * rose_plot - calculated over entire analysis window
 * If "set_axis" = True in "data_proc" section of each "plot_grp", the y-axis 
   for that "plot_grp" will be set based on the values specified in the "obs" 
   section for each "variable". If "set_axis" = False, then the automatic
@@ -111,8 +112,17 @@ Shell variables prefixed with the ``$`` symbol, such as ``$HOME``, will be expan
 please provide location of ``*.metcro2d.ncf`` files here.
 Shell variables prefixed with the ``$`` symbol, such as ``$HOME``, will be expanded.
 
-**mod_type:** The model type. Options are: "cmaq", "wrfchem", "rrfs", "gsdchem",
-"cesm_fv", "cesm_se", and "raqms". 
+**mod_type:** The model type. Current options available: 
+
+* cmaq
+* wrfchem
+* ufschem
+* rrfs
+* gsdchem
+* cesm_fv 
+* cesm_se 
+* raqms
+
 If you specify another name, MELODIES MONET will try to read in the data using
 xarray.open_mfdataset and xarray.open_dataset().
 
@@ -126,6 +136,65 @@ data (e.g., surf_only: True).
 Typically this is set at the horizontal resolution of your model * 1.5. Setting 
 this to a smaller value will speed up the pairing process. 
 
+**extra_calc:** The extra_calc section allows users to calculate complex meteorological 
+variables that may not have standard variable names across datasets. E.g. u, v, u10, and v10
+all commonly refer to the u and v components of wind speed. However, the naming convention
+varies by model. 
+
+This section allows dewpoint, relative humidity, wind speed, and wind direction to be 
+calculated. Users can also specify whether their spatial overlay, spatial bias, and spatial 
+exceedance plots display wind barbs. 
+
+**NOTE:** All extra_calc calculations should be left in SI units. See example yaml files:
+
+   * ``control_ish_lite_ufschem-example.yaml``
+   * ``control_ish_ufschem-example.yaml``
+   * ``control_ufschem-example.yaml``
+
+* **Hydrometeorology:** 
+
+   * Observations will sometimes only record dewpoint or relative humidity. Hence, both options are available for
+     calculation, provided the model has specific humidity. 
+
+   * **Model dewpoint:** can be calculated with the specific humidity. Users will need to know the
+     naming convention of specific humidity in their specific model. Observations will sometimes 
+     only record dewpoint or relative humidity. Hence, both options are available for calculation,
+     provided the model has specific humidity. 
+
+   * **Model relative humidity:** can be calculated with the specific humidity. Users will need to know 
+     the naming convention of specific humidity in their specific model. 
+
+   * *Calculations for standardized hydrometeorological variables continue to be incorporated into MELODIES-MONET.*
+
+* **Wind speed and direction:**
+
+   * **Wind speed:** is calculated using the u-component and v-component. Users are responsible for
+     knowing what those components are called in their model. If modeled wind speed is already 
+     available, simply add the variable name to the variable list. 
+
+   * **Wind direction:** is calculated using the u-component and v-component. Users are responsible for
+     knowing what those components are called in their model. If modeled wind direction is already 
+     available, simply add the variable name to the variable list. 
+
+   * **Wind barbs:** can be plotted using the u-component and v-component. Users are responsible for
+     knowing what those components are called in their model. **NOTE: plotted wind barbs are in knots. 
+     Wind speed everywhere else in the model/observations are by default m/s unless specified elsewhere in the 
+     YAML options.** 
+
+* **Potential temperature:**
+
+   * **Modeled potential temperature:** is calculated using the modeled pressure and temperature. Users are responsible for
+     knowing what those components are called in their model. 
+
+   * **Observed potential temperature:** is calculated using the observed pressure and temperature. Users are responsible for
+     knowing what those components are called in their model.
+
+   * **NOTE:** Potential temperature is the only variable where model and observed calculations are supported.   
+
+* **Tropopause:**
+
+   * **Tropopause:** under development. 
+
 **apply_ak:** Removed. Instead, specify ``pairing_kwargs`` in the analysis section.
 
 **is_global:** Optional boolean argument to specify if the model dataset is global or
@@ -372,7 +441,16 @@ where domain_type is equal to domain_name.
 (e.g., ['epa_region'])
 
 **region_list:** list of regions we will calculate for scorecard. 
-(e.g., ['R1','R2','R3','R4','R5','R6','R7','R8','R9','R10']
+(e.g., ['R1', 'R2', 'R3', 'R4', 'R5', 'R6', 'R7', 'R8', 'R9', 'R10']
+
+**interval_list:** list of points that will create a single groupped boxplot. 
+E.g. [0, 3, 5, 8, 11, 14] will create groupped boxplots for [0-3), [3-5), and so forth.
+
+**interval_var:** the variable a grouped boxplot will be created for. 
+
+**interval_labels:** Labels that refer to the interval list. 
+e.g. ["[0, 3)", "[3, 5)", "[5, 8)", "[8, 11)", "[11, 14)"] are labels that will appear on
+the x-axis
 
 **urban_rural_name:** list of only one string input, which is variable used to
 determine whether urban or rural site. (e.g., ['msa_name'])
@@ -397,11 +475,22 @@ for csi plot, list of model names (only) user choose to set as labels.
 **altitude_variable:** For "vert_profile" plot only. Name of altitude variable in observational 
 dataset (e.g., altitude)
 
-**vertprofile_bins:** For "vert_profile" plot only. List of vertical bins, on which to analyze the data.
-Units should be identical to the units of the altitude_variable specified above (e.g., 
-[0, 500, 1000, 1500, 2000, 2500, 3000, 3500, 4000] if altitude is in meters)
+**vertprofile_bins:** For "vert_profile" plot only. Users input a range in which to bin and analyze the data.
+Units should be identical to the units of the altitude_variable specified above (e.g. pressure_obs (Pa) and altitude (m)). 
+
+For example, ::
+
+    vertprofile_bins
+      range: 
+        start: 0 # starting value
+        stop: 100001 # end value 
+        step: 2000 # interval the binning should increase by 
 
-**color_map:** For 'scatter_density' plot only. Specify a default colormap in Matplotlib (e.g., 'RdBu_r'). 
+**blh_calc:** For "vert_profile" plot only. Provides a numerical estimation of the boundary layer
+height using potential temperature inversion, richardson number, and specific humidity gradient. 
+These calculations are estimates and should be evaluated against the plotted sonde data. 
+
+**color_map:** For 'scatter_density' & rose_plot plots only. Specify a default colormap in Matplotlib (e.g., 'RdBu_r'). NOTE: custom color_map is not available for rose_plot.  
 To use a custom colormap, leave color_map blank and provide the following options:
 
    * **colors:** Specify a list of colors (e.g., ['royalblue', 'cyan', 'yellow', 'orange']).
@@ -448,6 +537,10 @@ No conversions occur. Current options are only 'hPa' and 'Pa'.
 observation label is first and the model label is second 
 (e.g., ['airnow_cmaq_expt', 'airnow_rrfs_13km', 'airnow_wrfchem_v4.2'])
 
+**gridlines:** This allows users to provide background gridlines to their plots. Currently supported on the CSI, boxplot, and multi-boxplots.
+
+
+
 **data_proc:** This section stores all of the data processing information.
 
    * **filter_dict:** This is a dictionary used to filter the paired data sent 
@@ -509,6 +602,18 @@ observation label is first and the model label is second
      plot shaded curves of the 25th and 75th percentile range of each vertical bin or 
      'box' to plot box-plots of each vertical bin.
 
+   * **set_stat_sig:** This option allows the user to calculate an independent 
+     t-test between two independent samples. The variances are assumed to be equal.
+
+      Example output: p-value annotation legend:
+
+      *   ``ns``: 5.00e-02 < p <= 1.00e+00
+      *    ``*``: 1.00e-02 < p <= 5.00e-02
+      *   ``**``: 1.00e-03 < p <= 1.00e-02
+      *  ``***``: 1.00e-04 < p <= 1.00e-03
+      * ``****``: p <= 1.00e-04
+
+
 Stats
 -----
 All input needed to calculate the statistics. The supported statistics available 

docs/examples/UWyoming_UFS-CHEM_Pairing.ipynb

@@ -0,0 +1,228 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "fa641328-fd14-4d05-a2f6-99aa3b0bcdbd",
+   "metadata": {},
+   "source": [
+    "# Example for Pairing University of Wyoming data with UFS-Chem"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d7d709d8-9314-48f7-894e-9fb62fbe696c",
+   "metadata": {},
+   "source": [
+    "This example will demonstrate how to use MELODIES MONET to pair aircraft observations from the University of Wyoming  (https://weather.uwyo.edu/upperair/sounding.shtml) to model output from the UFS-Chem (dyn*.nc and phy*.nc output files) and save the paired data for each flight as a netcdf. Users can then read these files back into MELODIES MONET to create plots or calculate statistics or use this paired data output file to do their own analysis. \n",
+    "\n",
+    "Pairing aircraft data takes awhile so it is recommended that users first pair the data and then produce the plots and statistics, so that you are not repairing everytime you want to change something small during your analysis.\n",
+    "\n",
+    "This example resamples the data to '10S'. To reduce memory constraints, use a smaller window. For examples, on how to submit a job to process more flight days with a shorter resampling, see the end of this jupyter notebook."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5f3155b5-f520-4eaa-8220-4c6b3ed2fc28",
+   "metadata": {},
+   "source": [
+    "### First we import the loop_pairing function from melodies_monet.util.tools."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "90856e9f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from melodies_monet.util.tools import loop_pairing"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fb93d196-12e0-4374-88b7-ee236f564e3e",
+   "metadata": {},
+   "source": [
+    "### Second, we read in a control file that explains all the pairing parameters."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "e1ddf289-b838-4e0d-9230-41cd183dc340",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "control_fn='control_looping_UWY_UFS_CHEM.yaml'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e95f38e3-a807-4fcd-8168-7bfb06ab7597",
+   "metadata": {},
+   "source": [
+    "### There are two options for providing the model and observation data for pairing"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "31153f68-c721-4064-8d44-df588c856fbc",
+   "metadata": {},
+   "source": [
+    "**Option 1)** Provide the info in a dictionary like that below and then pair the data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "dc80edd7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "file_pairs = {\n",
+    "    '0627_L1': {\n",
+    "        'model': {'ufschem': 'example:ufschem:2023-06'},\n",
+    "        'obs': {'uwy': 'example:uwy-sonde:2023-06'}\n",
+    "    }\n",
+    "}"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "129ee7c6-b0b3-4275-9430-1ad72e556505",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "example:ufschem:2023-06\n",
+      "**** Reading UFS-CHEM model output...\n",
+      "Performing extra model calculations...\n",
+      "Calculating modeled Dewpoint...\n",
+      "Calculating modeled relative humidity...\n",
+      "Calculating modeled windpseed...\n",
+      "Calculating modeled wind direction...\n",
+      "Calculating modeled potential temperature...\n",
+      "Performing extra calculations for obs...\n",
+      "Calculating observed potential temperature...\n",
+      "1, in pair data\n",
+      "Note: Point 0, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 1, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 2, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 3, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 4, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 5, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 6, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 7, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 8, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 9, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 10, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 11, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 12, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 13, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 14, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 15, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 16, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "Note: Point 17, is below the mid-point of the lowest model level and nearest neighbor extrapolation occurs for vertical pairing.\n",
+      "After pairing:        longitude  latitude  pressure_obs                time  ghght_obs  \\\n",
+      "0    -122.22360   37.7445      101290.0 2023-06-27 23:05:12        4.0   \n",
+      "1    -122.22345   37.7445      101190.0 2023-06-27 23:05:14       13.0   \n",
+      "2    -122.22330   37.7445      101055.0 2023-06-27 23:05:16       24.0   \n",
+      "3    -122.22315   37.7445      100915.0 2023-06-27 23:05:18       35.5   \n",
+      "4    -122.22305   37.7445      100750.0 2023-06-27 23:05:20       49.5   \n",
+      "...         ...       ...           ...                 ...        ...   \n",
+      "2499 -122.10880   37.7631         580.0 2023-06-28 00:51:42    35152.0   \n",
+      "2500 -122.11110   37.7635         570.0 2023-06-28 00:52:00    35271.0   \n",
+      "2501 -122.11380   37.7636         560.0 2023-06-28 00:52:20    35396.0   \n",
+      "2502 -122.11650   37.7635         550.0 2023-06-28 00:52:40    35526.0   \n",
+      "2503 -122.11910   37.7633         540.0 2023-06-28 00:52:56    35653.0   \n",
+      "\n",
+      "      temperature_C  dpt_obs  ice point temperature_C  relh_obs  \\\n",
+      "0            288.05   284.45                    11.30      79.0   \n",
+      "1            287.70   284.80                    11.65      83.0   \n",
+      "2            287.30   284.60                    11.45      83.5   \n",
+      "3            286.85   284.10                    10.95      83.5   \n",
+      "4            286.75   284.15                    11.00      84.0   \n",
+      "...             ...      ...                      ...       ...   \n",
+      "2499         239.75   196.15                   -72.80       0.0   \n",
+      "2500         240.05   196.35                   -72.60       0.0   \n",
+      "2501         240.75   196.75                   -72.10       0.0   \n",
+      "2502         241.15   197.05                   -71.80       0.0   \n",
+      "2503         241.85   197.55                   -71.30       0.0   \n",
+      "\n",
+      "      humidity wrt ice_%  ...    ptemp_obs  temperature_k      spfh  \\\n",
+      "0                   79.0  ...   286.997049     298.649301  0.007487   \n",
+      "1                   83.0  ...   286.729236     298.650359  0.007487   \n",
+      "2                   83.5  ...   286.439822     298.651417  0.007487   \n",
+      "3                   83.5  ...   286.104473     298.652475  0.007487   \n",
+      "4                   84.0  ...   286.138481     298.653533  0.007487   \n",
+      "...                  ...  ...          ...            ...       ...   \n",
+      "2499                 1.0  ...  1044.189181     242.958584  0.000002   \n",
+      "2500                 1.0  ...  1050.703848     243.204393  0.000002   \n",
+      "2501                 1.0  ...  1059.110187     243.450458  0.000002   \n",
+      "2502                 1.0  ...  1066.345465     243.696847  0.000002   \n",
+      "2503                 1.0  ...  1075.062192     243.943570  0.000003   \n",
+      "\n",
+      "        dewpoint    rel_hum  windspeed     winddir    ptemp_mod       ugrd  \\\n",
+      "0     282.678714  38.242132   3.030429  262.515793   299.538691   3.003940   \n",
+      "1     282.678645  38.238757   3.030515  262.515620   299.539787   3.004024   \n",
+      "2     282.678577  38.235383   3.030601  262.515447   299.540884   3.004109   \n",
+      "3     282.678508  38.232009   3.030687  262.515274   299.541980   3.004193   \n",
+      "4     282.678439  38.228634   3.030773  262.515101   299.543077   3.004278   \n",
+      "...          ...        ...        ...         ...          ...        ...   \n",
+      "2499  200.905502   0.709875  16.208643   89.369021  1060.864931 -16.165206   \n",
+      "2500  201.091601   0.712511  16.513093   89.249683  1067.506127 -16.471298   \n",
+      "2501  201.277689   0.715127  16.818459   89.130271  1074.148456 -16.778300   \n",
+      "2502  201.463694   0.717710  17.124221   89.011731  1080.792206 -17.085719   \n",
+      "2503  201.649502   0.720246  17.429178   88.895602  1087.437384 -17.392395   \n",
+      "\n",
+      "          vgrd  \n",
+      "0     0.398583  \n",
+      "1     0.398601  \n",
+      "2     0.398620  \n",
+      "3     0.398638  \n",
+      "4     0.398656  \n",
+      "...        ...  \n",
+      "2499 -0.313994  \n",
+      "2500 -0.352494  \n",
+      "2501 -0.391158  \n",
+      "2502 -0.429661  \n",
+      "2503 -0.467417  \n",
+      "\n",
+      "[2504 rows x 23 columns]\n",
+      "Writing: ./output/uwy_ufschem/0627_L1_uwy_ufschem.nc4\n",
+      "WARNING: The following variables have been renamed due to illegal characters in the variable name for netcdf4 format. \n",
+      "The original variable names can be found in the `long_name` variable attribute. \n",
+      "['ice point temperature_C', 'humidity wrt ice_%']\n"
+     ]
+    }
+   ],
+   "source": [
+    "loop_pairing(control=control_fn,file_pairs=file_pairs)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}