Domain Selection Module

The domain selection module provides comprehensive functions for defining and managing spatial domains for atmospheric budget analysis. It supports three main approaches: fixed domains, storm tracking, and interactive domain selection with visualization capabilities.

Main Functions

A module for selecting and visualizing meteorological data domains. Designed to assist in the analysis and interpretation of atmospheric phenomena.

Author: Danilo Couto de Souza Affiliation: Universidade de São Paulo (USP), Instituto de Astornomia, Ciências Atmosféricas e Geociências, São Paulo - Brazil Contact: danilo.oceano@gmail.com

src.select_domain.get_map_crs(args=None)[source]

Return the map projection.

If –keep_longitude is used, the input data may remain in 0–360 longitude. In this case, centering the map at 180 degrees avoids dateline-related plotting artifacts in Cartopy.

src.select_domain.coordXform(orig_crs, target_crs, x, y)[source]

Transforms coordinates from one CRS to another.

Parameters: - orig_crs: The original coordinate reference system. - target_crs: The target coordinate reference system. - x, y: The coordinates to transform.

Returns: - Transformed coordinates.

src.select_domain.tellme(s)[source]

Displays a message on the plot title.

Parameters: - s: The message to display.

src.select_domain.fmt(x, pos)[source]

Formats the colorbar labels.

Parameters: - x: The value to format. - pos: The position (unused, but required by FuncFormatter).

Returns: - Formatted label.

src.select_domain.draw_box(ax, limits, crs=cartopy.crs.PlateCarree)[source]

Draws a rectangular box on the plot based on specified limits.

Parameters: - ax: The matplotlib axes object. - limits: A dictionary with ‘min_lon’, ‘max_lon’, ‘min_lat’, ‘max_lat’ keys. - crs: The coordinate reference system for the plot.

src.select_domain.plot_zeta(ax, zeta, lat, lon, hgt=None, crs=cartopy.crs.PlateCarree)[source]

Plots the vorticity field and optionally the geopotential height.

Parameters: - ax: The matplotlib axes object for plotting. - zeta: The vorticity data array. - lat: Latitude coordinates. - lon: Longitude coordinates. - hgt: Optional geopotential height data array.

src.select_domain.map_decorators(ax)[source]

Adds coastlines and gridlines to the map.

Parameters: - ax: The matplotlib axes object for the map.

src.select_domain.plot_min_max_zeta(ax, zeta, lat, lon, limits, args)[source]

Plots the minimum or maximum zeta point within a specified domain.

Parameters: - ax: The matplotlib axes object for plotting. - zeta: The vorticity data array. - lat: Latitude coordinates. - lon: Longitude coordinates. - limits: A dictionary with ‘min_lon’, ‘max_lon’, ‘min_lat’, ‘max_lat’ keys specifying the domain. - args: A Namespace object containing command-line arguments.

src.select_domain.initial_domain(zeta, lat, lon, args=None)[source]

Interactively selects an initial spatial domain on a map.

Parameters: - zeta: The vorticity data array to be plotted for domain selection. - lat: Latitude coordinates for the plot. - lon: Longitude coordinates for the plot.

Returns: - limits: A dictionary containing the selected domain’s ‘min_lon’, ‘max_lon’, ‘min_lat’, ‘max_lat’.

src.select_domain.draw_box_map(u, v, zeta, hgt, lat, lon, timestr, args)[source]

Draws a map with streamlines and allows for the interactive selection of a domain.

Parameters: - u: Eastward wind component data array. - v: Northward wind component data array. - zeta: Vorticity data array. - hgt: Geopotential height data array. - lat: Latitude coordinates. - lon: Longitude coordinates. - timestr: The timestep as a string for display. - args: Command-line arguments.

Returns: - limits: A dictionary with the selected domain’s limits.

src.select_domain.get_domain_limits(args, *variables_at_plevel, track=None)[source]

Determines the domain limits based on track data or user selection.

Parameters: - args: Command-line arguments or options. - variables_at_plevel: A tuple containing meteorological variables at chosen pressure level. - track: Optional DataFrame containing track data for domain selection.

Returns: - current_domain_limits: A dictionary with the calculated domain limits.

Core Functions

Domain Definition

get_domain_limits() - Main function orchestrating domain selection based on analysis type

  • Handles fixed, tracking, and interactive domain selection modes

  • Integrates with track files for storm following analysis

  • Returns standardized domain limit dictionaries

  • Calculates central coordinates and domain dimensions

Interactive Domain Selection

draw_box_map() - Interactive map-based domain selection interface

  • Creates publication-quality meteorological maps

  • Overlays streamlines, vorticity, and geopotential height

  • Mouse-click interface for corner selection

  • Real-time domain visualization and validation

initial_domain() - Basic interactive domain selection

  • Simplified vorticity map display

  • Two-click rectangular domain selection

  • Coordinate transformation handling

  • User confirmation interface

Visualization Functions

plot_zeta() - Vorticity field plotting with optional height contours plot_min_max_zeta() - Storm center identification and marking map_decorators() - Cartographic elements (coastlines, gridlines, labels) draw_box() - Domain boundary visualization

Utility Functions

coordXform() - Coordinate reference system transformations tellme() - User interaction messages fmt() - Coordinate axis formatting

Key Features

Domain Selection Methods

Fixed Domains * Read predefined boundaries from inputs/box_limits file * Consistent analysis regions across different datasets * Nearest neighbor coordinate matching for grid alignment

Storm Tracking * Dynamic domains following atmospheric features * Center coordinates from track files with timestamps * Configurable domain size (width/length) or default 15°×15° * Automatic domain translation for moving systems

Interactive Selection * Visual domain specification on meteorological maps * Real-time feedback with overlaid boundaries * Multiple variables displayed (vorticity, streamlines, heights) * User confirmation and revision capability

Coordinate System Handling

Transformation Support: * Automatic coordinate reference system detection * Plate Carrée projection for global datasets * Proper handling of longitude conventions (0-360° vs -180-180°) * Grid-aligned domain boundaries

Spatial Calculations: * Domain center coordinates * Width and length computation * Area and aspect ratio determination

Storm Center Detection

Vorticity Extrema Finding: * Minimum or maximum vorticity identification * Multiple extrema handling for complex systems * Visual marking of detected centers * Integration with tracking algorithms

Configurable Tracking: * User-specified vorticity type (min/max) * Pressure level selection for analysis * Geopotential height integration for verification

Interactive Interface

User Experience: * Clear instruction prompts * Timeout handling for automated workflows * Keyboard/mouse input flexibility * Visual feedback during selection

Map Quality: * High-resolution coastlines and boundaries * Professional colormap selection (cmocean) * Customizable map extent and projection * Streamline visualization for wind patterns

Domain Limit Dictionary Structure

All domain selection methods return standardized dictionaries:

domain_limits = {
    'min_lon': float,      # Western boundary (degrees)
    'max_lon': float,      # Eastern boundary (degrees)
    'min_lat': float,      # Southern boundary (degrees)
    'max_lat': float,      # Northern boundary (degrees)
    'central_lat': float,  # Domain center latitude
    'central_lon': float   # Domain center longitude
}

Usage Examples

Fixed Domain Analysis

from src.select_domain import get_domain_limits

# Configure arguments for fixed domain
args.fixed = True
args.track = False
args.choose = False

# Get domain limits from box_limits file
domain = get_domain_limits(
    args,
    u_wind, v_wind, vorticity, geopotential,
    latitude, longitude, timestamp
)

print(f"Domain: {domain['min_lon']:.1f}°W to {domain['max_lon']:.1f}°E")
print(f"        {domain['min_lat']:.1f}°S to {domain['max_lat']:.1f}°N")

Storm Tracking Analysis

import pandas as pd

# Load storm track data
track_df = pd.read_csv('storm_track.csv', index_col=0)

# Configure for tracking
args.track = True
args.track_vorticity = 'min'  # For cyclones

# Get dynamic domain following storm
domain = get_domain_limits(
    args,
    u_wind, v_wind, vorticity, geopotential,
    latitude, longitude, timestamp,
    track=track_df
)

Interactive Domain Selection

# Configure for interactive selection
args.choose = True

# Launch interactive map
domain = get_domain_limits(
    args,
    u_wind, v_wind, vorticity, geopotential,
    latitude, longitude, timestamp
)

# User will see map and select domain interactively
# Returns selected boundaries

Direct Interactive Functions

from src.select_domain import draw_box_map, initial_domain

# Basic domain selection
simple_domain = initial_domain(vorticity_data, lat, lon)

# Advanced interactive selection with full meteorological display
detailed_domain = draw_box_map(
    u_wind, v_wind, vorticity, geopotential,
    lat, lon, timestamp_str, args
)

Configuration Files

Fixed Domain Configuration

Create inputs/box_limits file:

min_lon;-60.0
max_lon;-30.0
min_lat;-40.0
max_lat;-20.0

Storm Track File Format

CSV file with temporal tracking data:

timestamp,Lat,Lon,width,length
2020-01-01 00:00:00,-25.0,-45.0,20.0,15.0
2020-01-01 06:00:00,-26.0,-44.0,20.0,15.0
2020-01-01 12:00:00,-27.0,-43.0,20.0,15.0

Integration with Analysis Workflow

The domain selection module integrates seamlessly with the main analysis pipeline:

  1. Domain Definition - Select appropriate method (fixed/track/choose)

  2. Coordinate Extraction - Get boundary coordinates and center

  3. Data Slicing - Extract relevant spatial subset

  4. Budget Calculations - Perform analysis on selected domain

  5. Results Output - Save domain information with results

All domain selection methods ensure: * Consistent coordinate systems * Grid-aligned boundaries * Proper metadata preservation * Integration with visualization tools