Update documentation for v3.1.0 features and parameters

This commit updates the documentation to reflect new features and
parameters added in v3.1.0:

1. Updated available-parameters.rst:
   - Added time_slices parameter for snapshot analysis
   - Added lat_lon_native set-specific parameters (test_grid_file,
     ref_grid_file, antialiased)
   - Added test_file and ref_file parameters
   - Updated regrid_tool default from 'esmf' to 'xesmf'
   - Updated granulate default to include 'time_slices'
   - Updated sets default list to include all current diagnostic sets
   - Added notes about mutual exclusivity of time_slices and seasons

2. Updated examples.rst:
   - Added Example 8: Native Grid Visualization
   - Added Example 9: Snapshot Analysis for Core Sets
   - Updated running instructions to include new examples
   - Updated batch script example with ex8 and ex9

3. Created example files:
   - examples/ex8-native-grid-visualization/ (ex8.py, diags.cfg, README.md)
   - examples/ex9-snapshot-analysis/ (ex9.py, diags.cfg, README.md)

These changes document the two major features introduced in v3.1.0:
- Native grid visualization using UXarray
- Snapshot analysis for core diagnostic sets using time_slices

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: chengzhuzhang

docs/source/available-parameters.rst

@@ -70,11 +70,18 @@ functionality of the diagnostics.
 -  **regrid_method**: What regrid method of the regrid tool to use.
    Possible values are ``'linear'`` or ``'conservative'``. Default is ``'conservative'``.
    Read the xCDAT documentation on `regridding`_ for more information.
--  **regrid_tool**: The regrid tool to use. Default is ``'esmf'``.
+-  **regrid_tool**: The regrid tool to use. Default is ``'xesmf'``.
    Read the xCDAT documentation on `regridding`_ for more information.
+   **Note:** The ``lat_lon_native`` set does not use regridding, so this parameter is ignored for that set.
 -  **seasons**: A list of season to use. Default is annual and all seasons: ``['ANN', 'DJF', 'MAM', 'JJA', 'SON']``.
+   **Note:** This parameter is mutually exclusive with ``time_slices``. When using ``time_slices``, do not set ``seasons``.
+-  **time_slices**: *(v3.1.0+)* A list of time indices for snapshot analysis. Examples: ``['0']``, ``['5']``, ``['0', '1', '2']``.
+   Time slices are zero-based indices into the time dimension of the input dataset.
+   This enables analysis of individual time steps instead of climatological means.
+   **Note:** This parameter is mutually exclusive with ``seasons``. When using ``time_slices``, do not set ``seasons``.
+   Supported sets: ``lat_lon``, ``lat_lon_native``, ``polar``, ``zonal_mean_2d``, ``meridional_mean_2d``, ``zonal_mean_2d_stratosphere``.
 -  **sets**: A list of the sets to be run. Default is all sets:
-   ``['zonal_mean_xy', 'zonal_mean_2d', 'meridional_mean_2d', 'lat_lon', 'polar', 'area_mean_time_series', 'cosp_histogram', 'enso_diags', 'qbo', 'streamflow','diurnal_cycle']``.
+   ``['zonal_mean_xy', 'zonal_mean_2d', 'zonal_mean_2d_stratosphere', 'meridional_mean_2d', 'lat_lon', 'lat_lon_native', 'polar', 'area_mean_time_series', 'cosp_histogram', 'enso_diags', 'qbo', 'streamflow', 'diurnal_cycle', 'arm_diags', 'tc_analysis', 'annual_cycle_zonal_mean', 'lat_lon_land', 'lat_lon_river', 'aerosol_aeronet', 'aerosol_budget']``.
 -  **variables**: What variable(s) to use for this run. Ex: ``variables=["T", "PRECT"]``.
 
 .. _regridding: https://xcdat.readthedocs.io/en/latest/getting-started-guide/faqs.html#regridding
@@ -262,12 +269,30 @@ You can specify both ``test_end_yr`` and ``ref_end_yr`` or just ``end_yr``.
 -  **plot_log_plevs**: Log-scale the y-axis. Default ``False``.
 -  **plot_plevs**: Plot the pressure levels. Default ``False``.
 
+``'lat_lon_native'`` *(v3.1.0+)*:
+
+-  **test_grid_file**: *(Required)* Path to the grid file for test data in UGRID format (e.g., ``'/path/to/ne30pg2.nc'``).
+   The grid file defines the native grid structure used by UXarray for visualization.
+-  **ref_grid_file**: Path to the grid file for reference data in UGRID format (e.g., ``'/path/to/ne30pg2.nc'``).
+   Required for model vs model comparisons. Can be omitted for model-only runs.
+-  **antialiased**: Apply antialiasing to the plot. Default ``False``. Setting to ``True`` may improve visual quality but can impact performance.
+-  **time_slices**: Time indices for snapshot analysis (same as in core parameters). See ``time_slices`` description above.
+
+**Notes for lat_lon_native:**
+
+-  Native grid visualization requires UXarray (included in E3SM Unified environment)
+-  Grid files must be in UGRID format
+-  Regridding parameters (``regrid_tool``, ``regrid_method``) are ignored for this set
+-  Can use either ``seasons`` for climatology or ``time_slices`` for snapshot analysis (mutually exclusive)
 
 Other parameters
 ~~~~~~~~~~~~~~~~
 
 -  **dataset**: Default is ``''``.
--  **granulate**: Default is ``['variables', 'seasons', 'plevs', 'regions']``.
+-  **granulate**: Default is ``['variables', 'seasons', 'plevs', 'regions', 'time_slices']``.
+   This parameter controls how diagnostics are split into separate runs.
 -  **selectors**: Default is ``['sets', 'seasons']``. See :ref:`Using the selectors parameter <selector-ex>`.
 -  **viewer_descr**: Used to specify values in the viewer. Default ``{}``.
 -  **fail_on_incomplete**: Exit status will reflect failure if any parameter fails to complete. Default is ``False`` (e.g., a failing parameter will not create a failing exit code).
+-  **test_file**: *(v3.1.0+)* Specify the exact file name for test data. Useful for snapshot analysis with ``time_slices`` or when using specific data files.
+-  **ref_file**: *(v3.1.0+)* Specify the exact file name for reference data. Useful for snapshot analysis with ``time_slices`` or when using specific data files.

docs/source/examples.rst

@@ -93,6 +93,38 @@ on two different sets: ``zonal_mean_2d`` an ``lat_lon``.
 so you can compare different version of the data, or the same variable from different datasets.
 We are comparing CERES EBAF TOA version 2.8 and 4.0.
 
+8. Native Grid Visualization (v3.1.0)
+--------------------------------------
+`This example <https://github.com/E3SM-Project/e3sm_diags/tree/master/examples/ex8-native-grid-visualization>`__ demonstrates how to visualize model data on its native grid
+(e.g., cubed-sphere, unstructured grids) without regridding to a regular lat-lon grid.
+This feature uses UXarray to preserve native grid features and is particularly useful for high-resolution models with complex grid structures.
+The example shows model vs model comparison using snapshot analysis on native grids.
+
+**Key features:**
+
+- Visualize data on native grids without regridding
+- Preserve native grid features and characteristics
+- Support for cubed-sphere and unstructured grids
+- Uses UXarray for grid-aware operations
+
+9. Snapshot Analysis for Core Sets (v3.1.0)
+--------------------------------------------
+`This example <https://github.com/E3SM-Project/e3sm_diags/tree/master/examples/ex9-snapshot-analysis>`__ demonstrates time slice analysis on core diagnostic sets.
+Instead of computing climatological seasonal means, this analyzes individual time steps from model output using index-based time selection.
+
+This is useful for analyzing specific events, comparing model states at particular time points,
+or understanding temporal evolution without time averaging. The example shows how to use the ``time_slices`` parameter
+on multiple diagnostic sets (lat_lon, zonal_mean_2d, polar, meridional_mean_2d, zonal_mean_2d_stratosphere).
+
+**Key features:**
+
+- Index-based time selection (e.g., time_slices = ["0", "1", "2"])
+- Analyze individual time steps without temporal averaging
+- Event-based or process-oriented diagnostics
+- Works across multiple core diagnostic sets
+
+**Note:** ``time_slices`` and ``seasons`` parameters are mutually exclusive.
+
 Running the Examples
 ====================
 
@@ -117,7 +149,7 @@ The parameters file contains information related to the location
 of the data, what years to run the diagnostics on, what plots to create, and more.
 
 The configuration file provides information about the diagnostics you are running.
-This is used in Ex.4,5,7.
+This is used in Ex.4, 5, 7, 8, 9.
 
 Parameters for each example can be found in
 `this directory <https://github.com/E3SM-Project/e3sm_diags/tree/master/examples>`__.
@@ -134,7 +166,7 @@ Use the code below to run the diagnostics.
         salloc --nodes 1 --qos interactive --time 01:00:00 --constraint cpu --account=e3sm
         # Enter the E3SM Unified environment. For Perlmutter CPU, the command to do this is:
         source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_pm-cpu.sh
-        # Running Ex.1. For examples 4,5,7 append ``-d diags.cfg``.
+        # Running Ex.1. For examples 4, 5, 7, 8, 9 append ``-d diags.cfg``.
         python ex1.py --multiprocessing --num_workers=32
         # You may need to change permissions on your web directory to see the example output.
         chmod -R 755 <your web directory>
@@ -174,6 +206,8 @@ These were generated with the following script:
        # emacs ex5-model-vs-obs/ex5.py
        # emacs ex6-model-vs-obs-custom/ex6.py
        # emacs ex7-obs-vs-obs/ex7.py
+       # emacs ex8-native-grid-visualization/ex8.py
+       # emacs ex9-snapshot-analysis/ex9.py
 
        source /global/common/software/e3sm/anaconda_envs/load_latest_e3sm_unified_pm-cpu.sh
        cd ex1-model_ts-vs-model_ts
@@ -190,6 +224,10 @@ These were generated with the following script:
        python ex6.py --multiprocessing --num_workers=32
        cd ../ex7-obs-vs-obs
        python ex7.py --multiprocessing --num_workers=32 -d diags.cfg
+       cd ../ex8-native-grid-visualization
+       python ex8.py --multiprocessing --num_workers=32 -d diags.cfg
+       cd ../ex9-snapshot-analysis
+       python ex9.py --multiprocessing --num_workers=32 -d diags.cfg
        cd ../
 
        chmod -R 755 /global/cfs/cdirs/e3sm/www/forsyth/examples

examples/ex8-native-grid-visualization/README.md

@@ -0,0 +1,110 @@
+# Example 8: Native Grid Visualization
+
+This example demonstrates the **native grid visualization** feature introduced in **E3SM Diags v3.1.0**.
+
+## What This Example Does
+
+- Visualizes model data on native grids (e.g., cubed-sphere, unstructured grids)
+- Uses UXarray for grid-aware operations
+- Compares two models without regridding to a regular lat-lon grid
+- Preserves native grid features and characteristics
+
+## Key Features
+
+The native grid visualization capability:
+- Supports various native grid formats (cubed-sphere, unstructured, etc.)
+- Eliminates artifacts introduced by regridding
+- Enables comparison of models with different native grids
+- Particularly useful for high-resolution models
+
+## Key Parameters
+
+- `LatLonNativeParameter` - Required parameter class for native grid visualization
+- `test_grid_file` - Path to test model's grid file (UGRID format)
+- `ref_grid_file` - Path to reference model's grid file (optional for model-only runs)
+- `time_slices` - Use snapshot analysis instead of climatology (e.g., ["0"])
+- `antialiased` - Whether to apply antialiasing to the plot
+
+## Data Requirements
+
+This example uses test data located at LCRC:
+- Data path: `/lcrc/group/e3sm/public_html/e3sm_diags_test_data/native_grid`
+- Grid files: `/lcrc/group/e3sm/diagnostics/grids/`
+
+For your own data, ensure you have:
+1. Model output files on native grid
+2. Corresponding grid files in UGRID format
+
+## Running This Example
+
+### Using the Python Script
+
+```bash
+# Edit ex8.py to set your output directory
+# Update the `prefix` variable to point to your web directory
+
+# Run with default settings
+python ex8.py
+
+# Run with multiprocessing for better performance
+python ex8.py --multiprocessing --num_workers=32
+
+# Run with custom configuration file
+python ex8.py -d diags.cfg --multiprocessing --num_workers=32
+```
+
+### Using Command-Line Interface
+
+```bash
+e3sm_diags lat_lon_native \
+  --test_data_path /lcrc/group/e3sm/public_html/e3sm_diags_test_data/native_grid \
+  --test_file v3.LR.amip_0101.eam.h0.1989-12.nc \
+  --test_grid_file /lcrc/group/e3sm/diagnostics/grids/ne30pg2.nc \
+  --reference_data_path /lcrc/group/e3sm/public_html/e3sm_diags_test_data/native_grid \
+  --ref_file v3.LR.amip_0101.eam.h0.1989-12.nc \
+  --ref_grid_file /lcrc/group/e3sm/diagnostics/grids/ne30pg2.nc \
+  --results_dir /results/ex8_native_grid \
+  --case_id model_vs_model \
+  --time_slices 0 \
+  --run_type model_vs_model
+```
+
+## Configuration File
+
+The `diags.cfg` file allows you to customize:
+- Variables to plot (e.g., TGCLDLWP)
+- Regions of interest
+- Colormap settings
+- Contour levels for test, reference, and difference plots
+
+## Expected Output
+
+The diagnostic will generate:
+- Native grid visualizations for specified variables
+- Test model plot
+- Reference model plot
+- Difference plot (Test - Reference)
+- HTML viewer for browsing results
+
+Results will be saved in: `<your_directory>/ex8_native_grid/viewer/`
+
+## Notes
+
+- Native grid visualization requires UXarray library (included in E3SM Unified environment)
+- Grid files must be in UGRID format
+- This example uses `time_slices` for snapshot analysis; you can also use `seasons` for climatology
+- For model-only runs (no reference data), set `model_only = True` and omit ref_grid_file
+
+## Differences from Regular lat_lon Set
+
+Unlike the standard `lat_lon` set which regrids data to a regular lat-lon grid:
+- `lat_lon_native` preserves the original grid structure
+- No interpolation artifacts
+- Better representation of native grid features
+- Requires grid files in UGRID format
+
+## More Information
+
+For more details, see:
+- [E3SM Diags Documentation](https://e3sm-project.github.io/e3sm_diags)
+- [UXarray Documentation](https://uxarray.readthedocs.io/)

examples/ex8-native-grid-visualization/diags.cfg

@@ -0,0 +1,8 @@
+[#]
+sets = ["lat_lon_native"]
+case_id = "model_vs_model"
+variables = ["TGCLDLWP"]
+regions = ["global"]
+diff_colormap = "RdBu"
+contour_levels = [10, 25, 50, 75, 100, 125, 150, 175, 200, 225, 250]
+diff_levels = [-35, -30, -25, -20, -15, -10, -5, 5, 10, 15, 20, 25, 30, 35]

examples/ex8-native-grid-visualization/ex8.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Example 8: Native Grid Visualization
+
+This example demonstrates how to visualize model data on its native grid
+(e.g., cubed-sphere, unstructured grids) using UXarray, without regridding
+to a regular lat-lon grid.
+
+This preserves native grid features and is particularly useful for:
+- High-resolution models with complex grid structures
+- Comparing models with different native grids
+- Analyzing grid-dependent features
+
+This feature was introduced in E3SM Diags v3.1.0.
+"""
+
+import os
+
+from e3sm_diags.parameter.lat_lon_native_parameter import LatLonNativeParameter
+from e3sm_diags.run import runner
+
+# Create parameter object
+param = LatLonNativeParameter()
+
+# Location of the data
+param.test_data_path = "/lcrc/group/e3sm/public_html/e3sm_diags_test_data/native_grid"
+param.test_file = "v3.LR.amip_0101.eam.h0.1989-12.nc"
+
+param.reference_data_path = "/lcrc/group/e3sm/public_html/e3sm_diags_test_data/native_grid"
+param.ref_file = "v3.LR.amip_0101.eam.h0.1989-12.nc"
+
+# Short names for display
+param.short_test_name = "v3.LR.amip_0101"
+param.short_ref_name = "v3.HR.test4"
+
+# Native grid files
+# These specify the grid structure for native visualization
+param.test_grid_file = "/lcrc/group/e3sm/diagnostics/grids/ne30pg2.nc"
+param.ref_grid_file = "/lcrc/group/e3sm/diagnostics/grids/ne30pg2.nc"
+
+# Time selection: use snapshot instead of climatology
+# Use time_slices to analyze a specific time index
+param.time_slices = ["0"]  # First time step
+
+# Comparison settings
+param.case_id = "model_vs_model"
+param.run_type = "model_vs_model"
+
+# Antialiasing setting
+param.antialiased = False
+
+# Name of the folder where the results are stored.
+# Change `prefix` to use your directory.
+prefix = "/global/cfs/cdirs/e3sm/www/<your directory>/examples"
+param.results_dir = os.path.join(prefix, "ex8_native_grid")
+
+# Below are more optional arguments.
+
+# For running with multiprocessing.
+# param.multiprocessing = True
+# param.num_workers = 32
+
+# Run the diagnostic
+runner.sets_to_run = ["lat_lon_native"]
+runner.run_diags([param])