Data Object Module

The data object module defines the main DataObject class for processing meteorological data and computing atmospheric budget terms including thermodynamic, vorticity, and water budget calculations.

Main Classes

class src.data_object.DataObject(input_data: xarray.Dataset, dTdt: xarray.DataArray, dZdt: xarray.DataArray, dQdt: xarray.DataArray, namelist_df: pandas.DataFrame, args: Namespace, app_logger: Logger)[source]

Bases: object

A class for processing meteorological data and computing terms of the Quasi-Geostrophic Equation. It calculates thermodynamic and vorticity terms, excluding Adiabatic Heating Term (Q), which is estimated as a residual. Note that: Q = J * Cp_d

input_data

The input dataset containing meteorological variables.

Type:: xr.Dataset

dTdt

Data array representing the temperature tendency.

Type:: xr.DataArray

dZdt

Data array representing the geopotential height tendency.

Type:: xr.DataArray

dQdt

Data array representing the moisture tendency.

Type:: xr.DataArray

namelist_df

DataFrame mapping variable names and units.

Type:: pd.DataFrame

args

Parsed command-line arguments.

Type:: argparse.Namespace

app_logger

Logger for outputting information and error messages.

Type:: logging.Logger

__init__(input_data: xarray.Dataset, dTdt: xarray.DataArray, dZdt: xarray.DataArray, dQdt: xarray.DataArray, namelist_df: pandas.DataFrame, args: Namespace, app_logger: Logger)[source]

extract_variables(input_data, namelist_df, args)[source]

Extracts variables from the input dataset using the mapping provided in the namelist DataFrame. Converts units, defines coordinates, and prepares variables for later computations.

Parameters: - input_data (xr.Dataset): Input dataset containing raw meteorological variables. - namelist_df (pd.DataFrame): DataFrame mapping standardized variable names to dataset variables and units. - args (argparse.Namespace): Command-line arguments with configuration options.

convert_units(var_name, namelist_df)[source]

Converts the units of a variable from the dataset based on definitions in the namelist DataFrame.

Parameters: - var_name (str): Standardized name of the variable to extract and convert. - namelist_df (pd.DataFrame): DataFrame with variable mappings and units.

Returns: - xarray.DataArray: The variable with appropriate physical units.

calculate_geopotential_height(namelist_df)[source]

Retrieves geopotential height if available, otherwise calculates it from geopotential.

Parameters: - namelist_df (pd.DataFrame): DataFrame containing variable mapping and unit definitions.

Returns: - xarray.DataArray: Geopotential height (in meters).

calculate_additional_properties()[source]

Computes grid spacing (dx, dy) in meters and Coriolis parameter (f) for each latitude. Also stores coordinate variables for future use.

Sets: - self.dx, self.dy (xarray.DataArray): Grid spacing in x and y directions. - self.f (xarray.DataArray): Coriolis parameter (1/s).

calculate_thermodynamic_terms(dTdt)[source]

Calculates the atmospheric thermodynamic budget terms: - Horizontal and vertical advection of temperature - Sigma term related to adiabatic processes - Residual of the thermodynamic equation - Estimated diabatic heating (Q) from the residual

The thermodynamic budget equation is:: dT/dt = - (u · ∇T) - ω * ∂T/∂p + (θ/T) * ∂θ/∂p * ω + Q/Cp_d
Where the residual is used to estimate:: Q = Cp_d * ResT

Parameters: - dTdt (xarray.DataArray): Time derivative of temperature (K/s)

Sets: - self.dTdt: input field - self.Theta: potential temperature (K) - self.AdvHTemp: horizontal advection of temperature (K/s) - self.AdvVTemp: vertical advection of temperature (K/s) - self.Sigma: static stability term (K/Pa) - self.ResT: residual of the thermodynamic equation (K/s) - self.AdiabaticHeating: estimated diabatic heating (W/kg)

calculate_vorticity_terms(dZdt)[source]

Calculates the atmospheric vorticity budget terms: - Horizontal and vertical advection of relative vorticity - Meridional advection of planetary vorticity (β effect) - Divergence-related terms (ζ·divV and f·divV) - Tilting term - Residual of the vorticity equation

The vorticity budget equation is:: dζ/dt = - (u · ∇ζ) - ω * ∂ζ/∂p - v * β - ζ * div(V) - f * div(V) + Tilting
The residual is calculated as:: ResZ = dZdt - [AdvHZeta + AdvVZeta + vxBeta + ZetaDivH + fDivH + Tilting]

Parameters: - dZdt (xarray.DataArray): Time derivative of relative vorticity (1/s²)

Sets: - self.Zeta: relative vorticity (1/s) - self.dZdt: input field - self.AdvHZeta: horizontal advection of vorticity (1/s²) - self.AdvVZeta: vertical advection of vorticity (1/s²) - self.Beta: meridional gradient of Coriolis parameter (1/m/s) - self.vxBeta: meridional advection of planetary vorticity (1/s²) - self.DivH: horizontal divergence of the wind (1/s) - self.ZetaDivH: term ζ·div(V) (1/s²) - self.fDivH: term f·div(V) (1/s²) - self.Tilting: tilting term (1/s²) - self.ResZ: residual of the vorticity budget (1/s²)

calculate_water_budget_terms(dQdt)[source]

Calculates the atmospheric water budget terms: - Time derivative of specific humidity (dQdt) - Horizontal divergence of moisture flux (divQ) - Residual of the water vapor budget (WaterBudgetResidual)

The water vapor budget equation is:: dW/dt + div(Q) = P - E

Parameters: - dQdt (xarray.DataArray): Time derivative of specific humidity (kg/kg/s)

Sets: - self.dQdt: input field - self.dQdt_integrated: vertically integrated dQdt (kg/m^2/s) - self.divQ: horizontal divergence of moisture flux (1/s) - self.divQ_integrated: vertically integrated div(Q) (kg/m^2/s) - self.WaterBudgetResidual: dQdt_integrated + divQ_integrated (kg/m^2/s)

calculate_horizontal_advection(field)[source]

Calculates horizontal advection for a given field.

Parameters: - field (xarray.DataArray): The field for which to calculate the advection (e.g., temperature, vorticity, moisture).

Returns: - xarray.DataArray: The horizontal advection of the given field.

tilting_term()[source]

Calculates the tilting term in the vorticity budget equation, related to the vertical shear of horizontal wind and horizontal gradients of Omega.

Returns: - xarray.DataArray: Tilting contribution (1/s²)

calculate_divQ()[source]

Calculates the horizontal divergence of the moisture flux (q * V), which corresponds to the divergence of the vertically integrated water vapor transport in the water vapor budget equation.

Mathematically:: div(Q) = d(q*u)/dx + d(q*v)/dy

Returns: - xarray.DataArray: Horizontal divergence of moisture flux (1/s)

DataObject Class

The DataObject class is the core component for processing meteorological data and computing terms of atmospheric budget equations. It calculates thermodynamic and vorticity terms, with diabatic heating estimated as a residual.

Key Features

Variable extraction and unit conversion from input datasets
Thermodynamic budget calculations including temperature advection and diabatic heating
Vorticity budget computations with geostrophic and ageostrophic components
Water budget analysis with moisture transport and storage terms
Coordinate system handling for latitude, longitude, pressure levels, and time
Physical constant calculations (Coriolis parameter, grid spacing, etc.)

Main Methods

Variable Processing

extract_variables(): Extracts and processes variables from input dataset
convert_units(): Handles unit conversions using MetPy
calculate_geopotential_height(): Computes geopotential height from geopotential
calculate_additional_properties(): Calculates grid spacing and Coriolis parameter

Budget Calculations

calculate_thermodynamic_terms(): Computes temperature budget terms
calculate_vorticity_terms(): Computes vorticity budget terms
calculate_water_budget_terms(): Computes moisture budget terms

Data Structure

The DataObject contains:

Input Variables: * Temperature, humidity, wind components (u, v) * Vertical velocity (omega), geopotential height * Coordinate arrays (lat, lon, pressure, time)

Calculated Terms: * Budget equation components for each variable * Residual terms and diabatic heating estimates * Grid properties (dx, dy, Coriolis parameter)

Metadata: * Variable mappings from namelist * Unit conversions and physical constants * Processing parameters and logging

Usage Examples

from src.data_object import DataObject
import xarray as xr
import pandas as pd

# Load input data and tendencies
input_data = xr.open_dataset('era5_data.nc')
dTdt = calculate_temperature_tendency(input_data)
dZdt = calculate_geopotential_tendency(input_data)
dQdt = calculate_humidity_tendency(input_data)

# Load variable mapping
namelist_df = pd.read_csv('namelist.csv', index_col=0)

# Create DataObject instance
data_obj = DataObject(
    input_data=input_data,
    dTdt=dTdt,
    dZdt=dZdt,
    dQdt=dQdt,
    namelist_df=namelist_df,
    args=args,
    app_logger=logger
)

# Access calculated budget terms
horizontal_temp_adv = data_obj.HorizontalAdvT
diabatic_heating = data_obj.ResT * Cp_d  # Q = Cp_d * ResT
vorticity_advection = data_obj.HorizontalAdvZ