CDAT Migration Phase 2: Refactor core utilities and lat_lon set

.pre-commit-config.yaml

@@ -33,5 +33,6 @@ repos:
     rev: v0.991
     hooks:
       - id: mypy
-        args: ["--config=setup.cfg"]
-        additional_dependencies: [types-pyYAML==6.0.12.6]
+        args: ["--config=pyproject.toml"]
+    additional_dependencies:
+      [dask, numpy>=1.23.0, xarray>=2023.3.0, types-PyYAML]

.vscode/e3sm_diags.code-workspace

@@ -22,17 +22,14 @@
       "editor.rulers": [80, 88, 120],
       "editor.wordWrap": "wordWrapColumn",
       "editor.wordWrapColumn": 120,
-      "editor.defaultFormatter": "ms-python.python"
+      "editor.defaultFormatter": "ms-python.black-formatter"
     },
     // Code Formatting and Linting
     // ---------------------------
-    "python.formatting.provider": "black",
-    "python.linting.flake8Enabled": true,
-    "python.linting.flake8Args": ["--config=setup.cfg"],
+    "flake8.args": ["--config=setup.cfg"],
     // Type checking
     // ---------------------------
-    "python.linting.mypyEnabled": true,
-    "python.linting.mypyArgs": ["--config=setup.cfg"],
+    "mypy-type-checker.args": ["--config=setup.cfg"],
     // Testing
     // ---------------------------
     // NOTE: Debugger doesn't work if pytest-cov is enabled, so set "--no-cov"

auxiliary_tools/issue-658-compare-metrics.py

@@ -0,0 +1,158 @@
+# %%
+"""
+This script compares the absolute and relative differences between metrics
+generates by the `ex1` script on the `refactor/658-lat-lon-set` and `main`
+branch.
+
+Relative differences should be taken into consideration moreso than absolute
+differences.
+  - Relative differences show the scale using a percentage unit.
+  - Absolute differences is just a raw number that doesn't factor in
+    floating point size (e.g., 100.00 vs. 0.0001), which can be misleading.
+
+
+Metrics flow
+
+1. Loop over variables
+2. Get climatology variable (test and reference (optional))
+  - If time series, calculate climatology (CONFIRMED SAME)
+3. <OPTIONAL> Apply land sea mask if region is land or ocean
+  - Requires regridding land sea mask to the grid of the variable
+4. <OPTIONAL> If region is not global then subset on region
+5. <OPTONAL> Regrid to the lower resolution if one of the variables has a lower res
+6. Calculate metrics
+  - min, max, mean (spatial avg), rmse, std, corr
+"""
+import glob
+import time
+from typing import List
+
+import pandas as pd
+
+DEV_RESULTS = "/global/cfs/cdirs/e3sm/www/vo13/examples/ex1_modTS_vs_modTS_3years_658/lat_lon/model_vs_model"
+PROD_RESULTS = "/global/cfs/cdirs/e3sm/www/vo13/examples/ex1_modTS_vs_modTS_3years_main/lat_lon/model_vs_model"
+
+DEV_GLOB = sorted(glob.glob(DEV_RESULTS + "/*.json"))
+PROD_GLOB = sorted(glob.glob(PROD_RESULTS + "/*.json"))
+
+
+def get_metrics(filepaths: List[str]) -> pd.DataFrame:
+    """Get the metrics using a glob of `.json` metric files in a directory.
+
+    Parameters
+    ----------
+    filepaths : List[str]
+        The filepaths for metrics `.json` files.
+
+    Returns
+    -------
+    pd.DataFrame
+        The DataFrame containing the metrics for all of the variables in
+        the results directory.
+    """
+    metrics = []
+
+    for filepath in filepaths:
+        df = pd.read_json(filepath)
+
+        filename = filepath.split("/")[-1]
+        var_key = filename.split("-")[1]
+
+        # Add the variable key to the MultiIndex and update the index
+        # before stacking to make the DataFrame easier to parse.
+        multiindex = pd.MultiIndex.from_product([[var_key], [*df.index]])
+        df = df.set_index(multiindex)
+        df.stack()
+
+        metrics.append(df)
+
+    df_final = pd.concat(metrics)
+
+    # Reorder columns and drop "unit" column (string dtype breaks Pandas
+    # arithmetic).
+    df_final = df_final[["test", "test_regrid", "ref", "ref_regrid", "diff", "misc"]]
+
+    return df_final
+
+
+def get_diffs(df_a: pd.DataFrame, df_b: pd.DataFrame) -> pd.DataFrame:
+    """The metrics differences between two DataFrames.
+
+    Parameters
+    ----------
+    df_a : pd.DataFrame
+        The first DataFrame representing "actual" results (aka development).
+    df_b : pd.DataFrame
+        The second DataFrame representing "reference" results (aka production).
+
+    Returns
+    -------
+    pd.DataFrame
+        The DataFrame containing absolute and relative differences between
+        the metrics DataFrames.
+    """
+    #  Absolute difference: abs(actual - reference)
+    df_abs = abs(df_a - df_b)
+    df_abs = df_abs.add_suffix("_abs")
+
+    # Relative difference: abs(actual - reference) / abs(actual)
+    df_rel = abs(df_a - df_b) / abs(df_a)
+    df_rel = df_rel.add_suffix("_rel")
+
+    # Combine both DataFrames
+    df_final = pd.concat([df_abs, df_rel], axis=1, join="outer")
+
+    return df_final
+
+
+def _sort_cols(df: pd.DataFrame) -> pd.DataFrame:
+    columns = [
+        "test_dev",
+        "test_prod",
+        "test_abs",
+        "test_rel",
+        "test_regrid_dev",
+        "test_regrid_prod",
+        "test_regrid_abs",
+        "test_regrid_rel",
+        "ref_dev",
+        "ref_prod",
+        "ref_abs",
+        "ref_rel",
+        "ref_regrid_dev",
+        "ref_regrid_prod",
+        "ref_regrid_abs",
+        "ref_regrid_rel",
+        "diff_dev",
+        "diff_prod",
+        "diff_abs",
+        "diff_rel",
+        "misc_dev",
+        "misc_prod",
+        "misc_abs",
+        "misc_rel",
+    ]
+    df = df[columns]
+
+    return df
+
+
+# %%
+time_str = time.strftime("%Y%m%d-%H%M%S")
+
+# %%
+df_dev = get_metrics(DEV_GLOB)
+df_prod = get_metrics(PROD_GLOB)
+df_diff = get_diffs(df_dev, df_prod)
+
+df_diff.to_excel(f"{time_str}-issue-658-metrics-diff.xlsx")
+
+# %%
+df_dev_pref = df_dev.add_suffix("_dev")
+df_prod_pref = df_prod.add_suffix("_prod")
+
+df_final = pd.concat([df_diff, df_dev_pref, df_prod_pref], axis=1, join="outer")
+df_final = _sort_cols(df_final)
+
+# %%
+df_final.to_excel(f"{time_str}-issue-658-metrics-diff.xlsx")

conda-env/ci.yml

@@ -26,6 +26,8 @@ dependencies:
   - numpy >=1.23.0
   - shapely >=2.0.0,<3.0.0
   - xarray >=2023.02.0
+  - xcdat >=0.5.0
+  - xesmf >=0.7.0
   # Testing
   # ==================
   - scipy

conda-env/dev.yml

@@ -2,6 +2,7 @@
 name: e3sm_diags_dev
 channels:
   - conda-forge
+  - conda-forge/label/xcdat_dev
   - defaults
 dependencies:
   # Base
@@ -24,6 +25,9 @@ dependencies:
   - numpy >=1.23.0
   - shapely >=2.0.0,<3.0.0
   - xarray >=2023.02.0
+  - xskillscore >=0.0.20
+  - xcdat==0.6.0rc1
+  - xesmf >=0.7.0
   # Testing
   # ==================
   - scipy
@@ -49,4 +53,5 @@ dependencies:
   # Developer Tools
   # =================
   - tbump=6.9.0
+  - ipykernel
 prefix: /opt/miniconda3/envs/e3sm_diags_dev

e3sm_diags/derivations/default_regions.py

@@ -1,3 +1,7 @@
+"""
+WARNING: This module will be deprecated and replaced with
+`default_regions_xr.py` once all diagnostic sets are refactored to use that file.
+"""
 import cdutil
 
 regions_specs = {

e3sm_diags/derivations/default_regions_xr.py

@@ -0,0 +1,89 @@
+"""Module for defining regions used for spatial subsetting.
+
+NOTE: Replaces `e3sm_diags.derivations.default_regions`.
+"""
+
+# A dictionary storing the specifications for each region.
+# "lat": The latitude domain for subsetting a variable, (lon_west, lon_east).
+# "lon": The longitude domain for subsetting a variable (lat_west, lat_east).
+# "value": The lower limit for masking.
+REGION_SPECS = {
+    "NHEX": {"lat": (30.0, 90)},
+    "SHEX": {"lat": (-90.0, -30)},
+    "TROPICS": {"lat": (-30.0, 30)},
+    "TRMM_region": {"lat": (-38.0, 38)},
+    "90S50S": {"lat": (-90.0, -50)},
+    "50S20S": {"lat": (-50.0, -20)},
+    "20S20N": {"lat": (-20.0, 20)},
+    "50S50N": {"lat": (-50.0, 50)},
+    "5S5N": {"lat": (-5.0, 5)},
+    "20N50N": {"lat": (20.0, 50)},
+    "50N90N": {"lat": (50.0, 90)},
+    "60S90N": {"lat": (-60.0, 90)},
+    "60S60N": {"lat": (-60.0, 60)},
+    "75S75N": {"lat": (-75.0, 75)},
+    "ocean_seaice": {"value": 0.65},
+    "land_60S90N": {"value": 0.65, "lat": (-60.0, 90)},
+    "ocean_TROPICS": {"value": 0.65, "lat": (-30.0, 30)},
+    "land_NHEX": {"value": 0.65, "lat": (30.0, 90)},
+    "land_SHEX": {"value": 0.65, "lat": (-90.0, -30)},
+    "land_TROPICS": {"value": 0.65, "lat": (-30.0, 30)},
+    "ocean_NHEX": {"value": 0.65, "lat": (30.0, 90)},
+    "ocean_SHEX": {"value": 0.65, "lat": (-90.0, -30)},
+    # follow AMWG polar range,more precise selector
+    "polar_N": {"lat": (50.0, 90.0)},
+    "polar_S": {"lat": (-90.0, -55.0)},
+    # To match AMWG results, the bounds is not as precise in this case
+    # 'polar_N_AMWG':{'domain': Selector("lat":(50., 90.))},
+    # 'polar_S_AMWG':{'domain': Selector("lat":(-90., -55.))},
+    # Below is for modes of variability
+    "NAM": {"lat": (20.0, 90), "lon": (-180, 180)},
+    "NAO": {"lat": (20.0, 80), "lon": (-90, 40)},
+    "SAM": {"lat": (-20.0, -90), "lon": (0, 360)},
+    "PNA": {"lat": (20.0, 85), "lon": (120, 240)},
+    "PDO": {"lat": (20.0, 70), "lon": (110, 260)},
+    # Below is for monsoon domains
+    # All monsoon domains
+    "AllM": {"lat": (-45.0, 45.0), "lon": (0.0, 360.0)},
+    # South American Monsoon
+    "SAMM": {"lat": (-45.0, 0.0), "lon": (240.0, 330.0)},
+    # North African Monsoon
+    "NAFM": {"lat": (0.0, 45.0), "lon": (310.0, 60.0)},
+    # South African Monsoon
+    "SAFM": {"lat": (-45.0, 0.0), "lon": (0.0, 90.0)},
+    # Asian Summer Monsoon
+    "ASM": {"lat": (0.0, 45.0), "lon": (60.0, 180.0)},
+    # Australian Monsoon
+    "AUSM": {"lat": (-45.0, 0.0), "lon": (90.0, 160.0)},
+    # Below is for NINO domains.
+    "NINO3": {"lat": (-5.0, 5.0), "lon": (210.0, 270.0)},
+    "NINO34": {"lat": (-5.0, 5.0), "lon": (190.0, 240.0)},
+    "NINO4": {"lat": (-5.0, 5.0), "lon": (160.0, 210.0)},
+    # Below is for additional domains for diurnal cycle of precipitation
+    "W_Pacific": {"lat": (-20.0, 20.0), "lon": (90.0, 180.0)},
+    "CONUS": {"lat": (25.0, 50.0), "lon": (-125.0, -65.0)},
+    "Amazon": {"lat": (-20.0, 5.0), "lon": (-80.0, -45.0)},
+    # Below is for RRM(regionally refined model) domains.
+    # 'CONUS_RRM': {'domain': "lat":(20., 50., 'ccb'), "lon":(-125., -65., 'ccb'))},For RRM dataset, negative value won't work
+    "CONUS_RRM": {"lat": (20.0, 50.0), "lon": (235.0, 295.0)},
+    # Below is for debugging. A smaller latitude range reduces processing time.
+    "DEBUG": {"lat": (-2.0, 2)},
+}
+
+# A dictionary storing ARM site specifications with specific coordinates.
+# Select nearest grid point to ARM site coordinate.
+# "lat": The latitude point.
+# "lon": The longitude point.
+# "description": The description of the ARM site.
+ARM_SITE_SPECS = {
+    "sgpc1": {"lat": 36.4, "lon": -97.5, "description": "97.5W 36.4N Oklahoma ARM"},
+    "nsac1": {"lat": 71.3, "lon": -156.6, "description": "156.6W 71.3N Barrow ARM"},
+    "twpc1": {"lat": -2.1, "lon": 147.4, "description": "147.4E 2.1S Manus ARM"},
+    "twpc2": {"lat": -0.5, "lon": 166.9, "description": "166.9E 0.5S Nauru ARM"},
+    "twpc3": {"lat": -12.4, "lon": 130.9, "description": "130.9E 12.4S Darwin ARM"},
+    "enac1": {
+        "lat": 39.1,
+        "lon": -28.0,
+        "description": "28.0E 39.1N Graciosa Island ARM",
+    },
+}