Visualization Module

The visualization module provides comprehensive plotting capabilities for atmospheric data visualization in ATMOS-BUD. It offers functions for creating maps, plotting system tracks, generating time series plots, and creating Hovmöller diagrams for atmospheric budget analysis.

Key Features

Map Visualization: Create publication-quality maps with meteorological overlays
Track Plotting: Visualize weather system trajectories with enhanced features
Time Series Analysis: Generate dual-axis plots for vorticity and geopotential height
Hovmöller Diagrams: Display time-pressure cross-sections of atmospheric variables
Cartographic Features: Integrated coastlines, boundaries, and geographic references

Dependencies

The module relies on several specialized libraries:

Cartopy: Geographic projections and map features
Matplotlib: Core plotting functionality
Pandas: Data handling and time series processing
NumPy: Numerical computations
cmocean: Oceanographic colormaps
sklearn: Data normalization utilities

Functions Overview

Map Features and Setup

src.visualization.map_features(ax)[source]

Adds coastline and border features to the matplotlib Axes.

Parameters: - ax (matplotlib.axes._subplots.AxesSubplot): The Axes object to add features to.

Returns: - ax (matplotlib.axes._subplots.AxesSubplot): The modified Axes object with added features.

Adds standard cartographic features to map plots including coastlines, land/ocean boundaries, and geographic reference lines.

Usage Example:

import matplotlib.pyplot as plt
import cartopy.crs as ccrs
from src.visualization import map_features

fig, ax = plt.subplots(subplot_kw=dict(projection=ccrs.PlateCarree()))
map_features(ax)

src.visualization.Brazil_states(ax, facecolor='#a4ab98')[source]

Adds Brazilian state boundaries and major cities to the plot.

Parameters: - ax (matplotlib.axes._subplots.AxesSubplot): The Axes object to add the features to. - facecolor (str): The color to use for land areas. Defaults to a grayish color.

Adds Brazilian state boundaries to map visualizations with customizable styling.

Usage Example:

from src.visualization import Brazil_states

# Add state boundaries without fill
Brazil_states(ax, facecolor='None')

Domain and Track Visualization

src.visualization.plot_fixed_domain(limits, data_plevel, args, results_subdirectory, time, app_logger)[source]

Creates and saves a plot of the specified domain with meteorological overlays.

Parameters: - limits (dict): Dictionary containing the ‘min_lon’, ‘max_lon’, ‘min_lat’, and ‘max_lat’ of the domain. - data_plevel (dict): Dictionary containing data at chosen pressure level for plotting. - args (Namespace): Namespace object containing command-line arguments. - results_subdirectory (str): Directory path to save the plot. - time (str): Timestamp or identifier for the plot filename. - app_logger (logging.Logger): Logger object for logging messages.

Raises: - Exception: If an error occurs during plotting or file saving.

Creates comprehensive domain visualization with meteorological overlays showing the analysis box, critical points (vorticity extrema, geopotential minima, wind maxima), and atmospheric context.

Key Features:

Analysis domain boundary highlighting
Critical point identification and labeling
Meteorological field overlays
Automatic timestamp formatting
Publication-ready styling

Usage Example:

from src.visualization import plot_fixed_domain

limits = {
    'min_lon': -60, 'max_lon': -30,
    'min_lat': -35, 'max_lat': -15
}

plot_fixed_domain(
    limits=limits,
    data_plevel=pressure_level_data,
    args=configuration_args,
    results_subdirectory='./results',
    time='202301011200',
    app_logger=logger
)

src.visualization.plot_track(track, args, figures_directory, app_logger)[source]

Plots the track of a weather system and saves the figure.

Parameters: - track (pandas.DataFrame): DataFrame containing the system’s track data including longitude (‘Lon’),

latitude (‘Lat’), and optionally ‘min_max_zeta_plevel’ and ‘max_wind_plevel’ for enhanced visualization.

args (argparse.Namespace): Command-line arguments or parameters specifying calculation options.
figures_directory (str): Directory path to save the plot.
app_logger (logging.Logger): Logger object for logging messages.

Raises: - Exception: If an error occurs during plotting or file saving.

Generates enhanced track visualizations with normalized wind speed markers and vorticity coloring. Automatically adjusts map extent and provides start/end point identification.

Key Features:

Adaptive figure sizing based on track extent
Enhanced visualization with wind speed and vorticity
Start (A) and end (Z) point markers
Automatic extent calculation with buffer zones
Integrated colorbar for vorticity values

Usage Example:

import pandas as pd
from src.visualization import plot_track

# Track DataFrame with required columns
track_data = pd.DataFrame({
    'Lon': [-45.2, -44.8, -44.1],
    'Lat': [-23.1, -22.8, -22.3],
    'min_zeta_850': [1.2e-5, 1.5e-5, 1.8e-5],
    'max_wind_850': [15.2, 18.4, 22.1]
})

plot_track(
    track=track_data,
    args=args,
    figures_directory='./figures',
    app_logger=logger
)

Time Series Analysis

src.visualization.plot_min_max_zeta_hgt(track_plotting, args, figs_dir, app_logger, max_ticks=10)[source]

Creates a dual-axis time series plot for min/max vorticity and minimum geopotential height at a specific pressure level.

Parameters: - track_plotting (pandas.DataFrame): DataFrame containing the time series data to be plotted. - args (argparse.Namespace): Command-line arguments containing the pressure level and min/max indicator. - figs_dir (str): Directory where the plot image will be saved. - max_ticks (int): Maximum number of ticks to display on the x-axis. - app_logger (logging.Logger): Logger object for logging messages.

The function saves the generated plot as a PNG file within the specified directory.

Creates dual-axis time series plots showing the evolution of vorticity extrema and geopotential height minima at specified pressure levels.

Key Features:

Dual-axis plotting for different variable scales
Automatic date formatting and tick management
Combined legend handling
Publication-quality styling
Configurable maximum tick count

Usage Example:

from src.visualization import plot_min_max_zeta_hgt

# Time series DataFrame with datetime index
track_plotting = pd.DataFrame({
    'min_zeta_850': vorticity_values,
    'min_hgt_850': geopotential_values
}, index=datetime_index)

plot_min_max_zeta_hgt(
    track_plotting=track_plotting,
    args=args,
    figs_dir='./figures',
    app_logger=logger,
    max_ticks=10
)

Hovmöller Diagrams

src.visualization.hovmoller_mean_zeta(Zeta, figures_subdirectory, app_logger)[source]

Creates and saves a Hovmöller diagram of mean relative vorticity for each pressure level over time within the system domain. Centered at zero (white).

Parameters: - Zeta (pandas.DataFrame): DataFrame with index as pressure levels (Pa) and columns as timestamps (datetime),

containing mean vorticity (1/s) for each level and time.

figures_subdirectory (str): Directory path to save the Hovmöller plot.
app_logger (logging.Logger): Logger object for logging messages.

Raises: - Exception: If an error occurs during plotting or file saving.

Generates Hovmöller diagrams displaying time-pressure cross-sections of mean relative vorticity within the system domain, with symmetric scaling centered at zero.

Key Features:

Symmetric color scaling centered at zero
Automatic missing data handling
Pressure level inversion for proper atmospheric display
Publication-ready formatting with proper units
Automatic timestamp formatting

Usage Example:

from src.visualization import hovmoller_mean_zeta
import pandas as pd

# DataFrame with pressure levels (Pa) as index, time as columns
zeta_data = pd.DataFrame(
    data=vorticity_array,  # Shape: (pressure_levels, time_steps)
    index=pressure_levels,  # In Pa
    columns=datetime_array
)

hovmoller_mean_zeta(
    Zeta=zeta_data,
    figures_subdirectory='./figures',
    app_logger=logger
)

Integration Examples

Complete Visualization Workflow

"""
Complete visualization workflow for atmospheric budget analysis
"""
import logging
import pandas as pd
from src.visualization import (
    plot_fixed_domain, plot_track,
    plot_min_max_zeta_hgt, hovmoller_mean_zeta
)

# Setup logging
logger = logging.getLogger(__name__)

# 1. Domain visualization
domain_limits = {
    'min_lon': -65, 'max_lon': -35,
    'min_lat': -35, 'max_lat': -10
}

plot_fixed_domain(
    limits=domain_limits,
    data_plevel=analysis_data,
    args=config_args,
    results_subdirectory='./results/case_study',
    time='202301151800',
    app_logger=logger
)

# 2. Track visualization
track_df = pd.read_csv('system_track.csv')
plot_track(
    track=track_df,
    args=config_args,
    figures_directory='./results/figures',
    app_logger=logger
)

# 3. Time series analysis
timeseries_data = pd.read_csv('track_evolution.csv', index_col=0, parse_dates=True)
plot_min_max_zeta_hgt(
    track_plotting=timeseries_data,
    args=config_args,
    figs_dir='./results/figures',
    app_logger=logger
)

# 4. Hovmöller diagram
vorticity_field = pd.read_pickle('hovmoller_data.pkl')
hovmoller_mean_zeta(
    Zeta=vorticity_field,
    figures_subdirectory='./results/figures',
    app_logger=logger
)

Multi-Level Analysis Visualization

"""
Generate visualizations for multiple pressure levels
"""
pressure_levels = [850, 700, 500, 300]

for level in pressure_levels:
    # Update configuration for current level
    args.level = level

    # Generate domain plot for this level
    plot_fixed_domain(
        limits=analysis_domain,
        data_plevel=data_by_level[level],
        args=args,
        results_subdirectory=f'./results/level_{level}hPa',
        time=current_timestamp,
        app_logger=logger
    )

    # Generate time series for this level
    level_timeseries = track_data[[f'min_zeta_{level}', f'min_hgt_{level}']]
    plot_min_max_zeta_hgt(
        track_plotting=level_timeseries,
        args=args,
        figs_dir=f'./results/level_{level}hPa/figures',
        app_logger=logger
    )

Technical Notes

Color Schemes

The module uses scientifically appropriate color schemes:

cmocean.cm.balance: For symmetric data (vorticity) centered at zero
cmocean.cm.deep_r: For depth-related or intensity data
Standard matplotlib: For basic geographic features

Figure Management

All functions include proper figure management:

Automatic figure closing to prevent memory leaks
Tight layout adjustment for publication quality
Exception handling with informative error messages
Comprehensive logging of operations and outputs

Data Requirements

Functions expect specific data structures:

Pandas DataFrames: For time series and track data
Dictionary structures: For pressure level data
Proper datetime indexing: For time-based visualizations
Geographic coordinates: In decimal degrees (longitude/latitude)

Output Management

Automatic directory creation as needed
Standardized filename conventions
High-resolution PNG output suitable for publication
Comprehensive logging of all generated files

Created on Wed Jan 11 16:54:18 2023

Created by:: Danilo Couto de Souza 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.visualization.get_cartopy_crs(args)[source]

Return data and map coordinate reference systems.

data_crs is always PlateCarree because the data are stored as regular latitude/longitude coordinates.

map_crs changes only when –keep_longitude is used. In that case, the map is centered at 180° to correctly display data kept in 0–360 longitude.