Weather Events Diagnostics API

The ufs_da_diagnostics.weather_events_marker module provides global synoptic‑scale diagnostics derived from FV3 background fields. It includes utilities for regridding, gradient computation, feature detection, and global plotting.

This page documents the full API for programmatic use.

High‑Level Workflow

The module performs the following steps:

  • Build a regular 1°×1° lat/lon grid

  • Regrid FV3 cubed‑sphere fields

  • Compute: - wind speed - vorticity - temperature gradients

  • Detect: - 500 hPa cyclone centers - 250 hPa jet streak ridges - 850 hPa baroclinic zones

  • Produce global diagnostic plots

Functions

Grid Utilities

ufs_da_diagnostics.weather_events_marker.build_latlon_grid(dlat=1.0, dlon=1.0)[source]

Build a regular global lat/lon grid.

Parameters

dlat, dlonfloat

Grid spacing in degrees.

Returns

Lon, Lat2D arrays

Target longitude/latitude meshgrid.

ufs_da_diagnostics.weather_events_marker.flatten_fv3(ds_lev, varname)[source]

Flatten FV3 cubed-sphere variable + lat/lon into 1D arrays.

ufs_da_diagnostics.weather_events_marker.regrid_fv3_to_latlon(ds_lev, varname, Lon_tgt, Lat_tgt)[source]

Regrid FV3 cubed-sphere field to regular lat/lon using nearest neighbor.

Diagnostics

ufs_da_diagnostics.weather_events_marker.compute_vort_and_gradT(Lon, Lat, U, V, T)[source]

Compute: - wind speed - relative vorticity (radian-based gradient) - temperature gradient magnitude

Notes

Using radian-based gradients produces smoother, more visually interpretable synoptic-scale fields.

ufs_da_diagnostics.weather_events_marker.compute_gradT_only(Lon, Lat, T)[source]

Compute |∇T| using radian-based gradients.

Feature Detection

ufs_da_diagnostics.weather_events_marker.detect_jet_ridge(wspd, threshold=45)[source]

Detect local maxima in wind speed above a threshold.

Parameters

wspd2D array

Wind speed field.

thresholdfloat

Minimum wind speed to consider part of the jet.

Returns

ridge2D boolean array

True where a local jet maximum is detected.

ufs_da_diagnostics.weather_events_marker.find_major_cyclone_centers(vort, wspd, size=41)[source]

Identify major cyclone centers using smoothed vorticity.

Logic

  • Use a percentile threshold to avoid noise.

  • Require moderate wind speed (≥20 m/s).

  • Require local vorticity maximum in a (size x size) window.

Plotting

ufs_da_diagnostics.weather_events_marker.plot_map(Lon, Lat, field, title, outname, cmap='coolwarm', levels=20, annotate_func=None, cbar_label=None)[source]

Generic global map plotter with: - filled contours - compact bottom colorbar - optional annotation callback

Command‑Line Interface

The module exposes a command‑line tool via:

ufsda-weather-events <background_file.nc>

The CLI entry point calls:

ufs_da_diagnostics.weather_events_marker.main()[source]