Increment Diagnostics API

The increment diagnostics subsystem provides tools for loading FV3-JEDI increment tiles, constructing global stitched fields, and computing zonal-mean cross sections.

This page documents the functions available in ufs_da_diagnostics.increment.increment_maps_tiles.

Modules

Increment Maps Diagnostics (FV3-JEDI)

This module generates horizontal increment maps and zonal-mean diagnostics from FV3-JEDI analysis increment files stored on the native 6‑tile cubed‑sphere grid. It supports:

• Single‑experiment increment maps

• Two‑experiment CTRL–EXP–DIFF comparison maps

• Zonal‑mean (latitude × level) diagnostics

• YAML‑driven configuration

• Command‑line execution via ufsda-inc-maps

All functions operate on FV3 native tile files of the form:

prefix.tile1.nc … prefix.tile6.nc

Outputs are written as PNG figures to the configured output directory.

ufs_da_diagnostics.increment.increment_maps_tiles.apply_amplification(vmin, vmax, amplify_cfg, is_diff=False)

Optionally compress colorbar range for weak increments.

Parameters

vmin, vmaxfloat

Original colorbar limits.

amplify_cfgdict or None

YAML block for amplification.

is_diffbool

Whether this is a DIFF field.

Returns

(vmin, vmax)tuple

Possibly amplified limits.

ufs_da_diagnostics.increment.increment_maps_tiles.apply_zoom(Lon, Lat, field, cfg)

Apply lat/lon bounding-box zoom if enabled in YAML.

Returns:

Lon, Lat, masked_field, extent_tuple or None

ufs_da_diagnostics.increment.increment_maps_tiles.build_global(prefix, grid_prefix, var, level)

Build a global lat/lon increment field from 6 FV3 tiles.

ufs_da_diagnostics.increment.increment_maps_tiles.compute_zonal_mean_full(prefix, grid_prefix, var)

Compute full vertical zonal‑mean cross‑section for a variable.

ufs_da_diagnostics.increment.increment_maps_tiles.get_map_limits(var, is_diff=False)

Return colorbar limits for increment maps.

ufs_da_diagnostics.increment.increment_maps_tiles.load_grid(grid_prefix, tile)

Load FV3 grid tile and compute cell‑centered lat/lon.

ufs_da_diagnostics.increment.increment_maps_tiles.load_pressure(level)

Return pressure (mbar) for a given FV3 vertical level.

ufs_da_diagnostics.increment.increment_maps_tiles.load_tile(prefix, tile, var, level)

Load a single FV3 cubed‑sphere tile increment field.

ufs_da_diagnostics.increment.increment_maps_tiles.main()

Main entry point for the increment‑maps diagnostic.

ufs_da_diagnostics.increment.increment_maps_tiles.plot_single(Lon, Lat, field, var, lev, exp_name, prefix, outname, cfg)

Plot a single global increment map for one experiment. Now supports YAML-driven zoom:

zoom:

enabled: true lat_min: 30 lat_max: 50 lon_min: -130 lon_max: -60

ufs_da_diagnostics.increment.increment_maps_tiles.plot_three(Lon, Lat, ctrl, exp, var, lev, ctrl_name, exp_name, outname, cfg)

Plot CTRL, EXP, and DIFF increment maps. Now supports YAML-driven zoom.

ufs_da_diagnostics.increment.increment_maps_tiles.plot_zonal_mean_colormap(lat, pressure, zm, var, exp_name, outname, cfg)

Plot a zonal‑mean (latitude × pressure) cross‑section for one experiment.

Amplification is applied if enabled in YAML.

ufs_da_diagnostics.increment.increment_maps_tiles.plot_zonal_mean_colormap_three(lat, pressure, zm_ctrl, zm_exp, var, ctrl_name, exp_name, outname, cfg)

Plot CTRL, EXP, and DIFF zonal‑mean cross‑sections.

Amplification is applied to CTRL and EXP. DIFF amplification optional (apply_to_diff).

ufs_da_diagnostics.increment.increment_maps_tiles.tapered_colorbar(fig, im, ax, label=None)

Create a tapered horizontal colorbar with adjusted layout.

Function Summary

load_tile	Load a single FV3 cubed‑sphere tile increment field.
load_grid	Load FV3 grid tile and compute cell‑centered lat/lon.
load_pressure	Return pressure (mbar) for a given FV3 vertical level.
build_global	Build a global lat/lon increment field from 6 FV3 tiles.
compute_zonal_mean_full	Compute full vertical zonal‑mean cross‑section for a variable.

Detailed API

Tile Loading

ufs_da_diagnostics.increment.increment_maps_tiles.load_tile(prefix, tile, var, level)

Load a single FV3 cubed‑sphere tile increment field.

ufs_da_diagnostics.increment.increment_maps_tiles.load_grid(grid_prefix, tile)

Load FV3 grid tile and compute cell‑centered lat/lon.

ufs_da_diagnostics.increment.increment_maps_tiles.load_pressure(level)

Return pressure (mbar) for a given FV3 vertical level.

Global Field Construction

ufs_da_diagnostics.increment.increment_maps_tiles.build_global(prefix, grid_prefix, var, level)

Build a global lat/lon increment field from 6 FV3 tiles.

Zonal Mean Diagnostics

ufs_da_diagnostics.increment.increment_maps_tiles.compute_zonal_mean_full(prefix, grid_prefix, var)

Compute full vertical zonal‑mean cross‑section for a variable.