Calculations Module

The calculations module contains the main computational functions for performing atmospheric budget analysis, including area averaging, zonal averaging, and the complete budget calculation workflow.

Main Functions

src.calculations.CalcZonalAverage(VariableData)[source]

Computates variable zonal average of some variable, for all z levels and time steps.

Source:

Brennan, F. E., & Vincent, D. G. (1980). Zonal and Eddy Components of the Synoptic-Scale Energy Budget during Intensification of Hurricane Carmen (1974), Monthly Weather Review, 108(7), 954-965. Retrieved Jan 25, 2022, from: https://journals.ametsoc.org/view/journals/mwre/108/7/1520-0493_1980_108_0954_zaecot_2_0_co_2.xml

Parameters:

VariableData (xarray.Dataset) – arrays containing data to be integrated. Requires dimension rlons (longitude in radians)

Returns:

zonal_ave – Arrays of zonal avreages for all longitudes from the passed Dataset

Return type:

xarray.Dataset

src.calculations.CalcAreaAverage(VariableData, ZonalAverage=False)[source]

Computates the Area Average of a function.

The default is to computate the zonal average and then a meridional average. If the input data is already some sort of zonal quantity (average or not), simply set longitude_indexer to None

Source:

Brennan, F. E., & Vincent, D. G. (1980). Zonal and Eddy Components of the Synoptic-Scale Energy Budget during Intensification of Hurricane Carmen (1974), Monthly Weather Review, 108(7), 954-965. Retrieved Jan 25, 2022, from: https://journals.ametsoc.org/view/journals/mwre/108/7/1520-0493_1980_108_0954_zaecot_2_0_co_2.xml

Parameters:

  • VariableData (xarray.Dataset) – arrays containing data to be integrated

  • ZonalAverage (string (optional)) – if passed, it will first compute zonal averages

Returns:

zonal_ave – Arrays of area avreages for all latitudes and longitudes from the passed Dataset

Return type:

xarray.Dataset

src.calculations.perform_calculations(input_data, namelist_df, dTdt, dZdt, dQdt, args, app_logger, *outputs)[source]

Performs meteorological calculations on input data and generates results and figures.

Parameters: - input_data (xr.Dataset): Dataset containing meteorological data from a NetCDF file. - namelist_df (pd.DataFrame): DataFrame mapping variable names. - dTdt, dZdt, dQdt: Data arrays representing temperature, vortcity and moisture tendencies, respectively. - args: Command-line arguments or parameters specifying calculation options. - app_logger (Logger): Logger for outputting information and error messages. - outputs (tuple): A tuple containing paths for results and figures directories, and the output file name.

The function processes each time step of the input data to calculate various meteorological terms, stores results in CSV files, and generates figures for analysis. It handles domain selection based on tracks, calculates area averages for specified terms, and plots diagnostic figures.

Core Functions

Statistical Operations

  • CalcZonalAverage() - Computes zonal averages for atmospheric variables

  • CalcAreaAverage() - Computes area averages with optional zonal averaging

  • perform_calculations() - Main function orchestrating the complete analysis workflow

Main Workflow Function

The perform_calculations() function is the central orchestrator that:

  • Processes meteorological data for each time step

  • Creates DataObject instances for budget term calculations

  • Handles domain selection (fixed, tracking, or interactive)

  • Computes area averages for all budget terms

  • Saves results in CSV and NetCDF formats

  • Generates diagnostic plots and visualizations

Key Features

Zonal Averaging

Computes longitudinal averages of atmospheric variables:

  • Maintains all vertical levels and time steps

  • Uses proper coordinate weighting

  • Based on Brennan & Vincent (1980) methodology

Area Averaging

Computes spatial averages over specified domains:

  • Optional zonal averaging preprocessing

  • Cosine latitude weighting for proper area integration

  • Handles both rectangular and irregular domains

Budget Term Processing

The main calculation workflow processes:

Thermodynamic Terms: * AdvHTemp - Horizontal temperature advection * AdvVTemp - Vertical temperature advection * Sigma - Sigma coordinate term * Omega - Vertical velocity effects * ResT - Thermodynamic residual (diabatic heating)

Vorticity Terms: * AdvHZeta - Horizontal vorticity advection * AdvVZeta - Vertical vorticity advection * ZetaDivH - Vorticity stretching term * fDivH - Coriolis stretching term * Tilting - Tilting term * vxBeta - Beta effect term * ResZ - Vorticity residual

Water Budget Terms: * dQdt - Moisture tendency * divQ - Moisture flux divergence * WaterBudgetResidual - Water budget residual

Domain Handling

Supports multiple domain selection methods:

  • Fixed domains - User-specified rectangular regions

  • Storm tracking - Dynamic domains following atmospheric features

  • Interactive selection - Manual domain specification

Time Series Processing

Processes complete time series with:

  • Automatic time step iteration

  • Consistent domain tracking across time

  • Progressive result accumulation

  • Memory-efficient data handling

Output Generation

Produces comprehensive output including:

  • CSV files - Time series of area-averaged budget terms

  • NetCDF files - Gridded results preserving spatial structure

  • Diagnostic plots - Domain maps, time series, vertical profiles

  • Track files - Storm center coordinates and characteristics

Usage Examples

Basic Usage

from src.calculations import perform_calculations, CalcAreaAverage

# Complete budget analysis workflow
perform_calculations(
    input_data=era5_dataset,
    namelist_df=variable_mapping,
    dTdt=temperature_tendency,
    dZdt=geopotential_tendency,
    dQdt=moisture_tendency,
    args=analysis_args,
    app_logger=logger,
    results_dir, figures_dir, output_filename
)

Area Averaging

from src.calculations import CalcAreaAverage, CalcZonalAverage

# Compute zonal average first
zonal_avg = CalcZonalAverage(temperature_data)

# Then area average
area_avg = CalcAreaAverage(temperature_data, ZonalAverage=True)

# Direct area average without zonal preprocessing
direct_avg = CalcAreaAverage(temperature_data, ZonalAverage=False)

Mathematical Background

The calculations are based on established atmospheric budget methodologies:

References: * Brennan, F. E., & Vincent, D. G. (1980). Zonal and Eddy Components of the Synoptic-Scale Energy Budget during Intensification of Hurricane Carmen (1974). Monthly Weather Review, 108(7), 954-965.

The module implements proper:

  • Spherical coordinate system handling

  • Area weighting for accurate spatial averaging

  • Pressure coordinate vertical integration

  • Conservation of physical units throughout calculations