API Reference

This section provides detailed documentation for all modules, classes, and functions in ATMOS-BUD.

API Documentation:

• Data Handling Module
  • Main Functions
  • Core Functions
  • Key Features
  • Preprocessing Pipeline
  • Usage Examples
  • Supported Data Sources
• Calculations Module
  • Main Functions
  • Core Functions
  • Key Features
  • Usage Examples
  • Mathematical Background
• Data Object Module
  • Main Classes
  • DataObject Class
  • Key Features
  • Main Methods
  • Data Structure
  • Usage Examples
• Domain Selection Module
  • Main Functions
  • Core Functions
  • Key Features
  • Domain Limit Dictionary Structure
  • Usage Examples
  • Configuration Files
  • Integration with Analysis Workflow
• Output Management Module
  • Main Functions
  • Key Features
  • Output Formats
  • Usage Examples
• Visualization Module
  • Key Features
  • Dependencies
  • Functions Overview
  • Integration Examples
  • Technical Notes
• Utilities Module
  • Main Functions
  • Core Functions
  • Key Features
  • Usage Examples
  • Error Handling and Validation
• Command Line Interface
  • Main Functions
  • Key Features
  • Command Structure
  • Configuration Files
  • Usage Examples
• ERA5 Data Module
  • Key Features
  • Dependencies
  • Authentication Setup
  • Functions Overview
  • Data Request Configuration
  • Integration Examples
  • Technical Notes

Core Modules

Data Handling

src.data_handling.load_data(infile, longitude_indexer, args, app_logger)

Loads data from a specified NetCDF file, handling both single files and multiple GFS files.

Parameters:

• infile (str) – Path to the input .nc file or a pattern matching multiple files.

• args – Parsed command-line arguments containing flags and options.

• app_logger (logging.Logger) – Logger for recording messages about script progress and issues.

Returns:

The loaded dataset.

Return type:

xr.Dataset

Raises:

• FileNotFoundError – If the input file or files specified by infile do not exist.

• Exception – For any other issues encountered during data loading.

src.data_handling.preprocess_data(data, df_namelist, args, app_logger)

Preprocesses the loaded data by sorting, slicing, and adjusting units as necessary.

Parameters:

• data (xr.Dataset) – The loaded dataset to preprocess.

• df_namelist (pd.DataFrame) – DataFrame containing namelist information such as variable names.

• args – Parsed command-line arguments containing flags and options.

• app_logger (logging.Logger) – Logger for recording messages about script progress and issues.

Returns:

The preprocessed dataset.

Return type:

xr.Dataset

Raises:

• ValueError – If critical namelist variables are missing or if data preprocessing encounters an issue.

• Exception – For any other issues encountered during data preprocessing.

Calculations

src.calculations.CalcZonalAverage(VariableData)

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)

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)

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.

Data Object

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)

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

extract_variables(input_data, namelist_df, args)

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)

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)

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()

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)

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)

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)

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)

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()

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()

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)

Domain Selection

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)

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)

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)

Displays a message on the plot title.

Parameters: - s: The message to display.

src.select_domain.fmt(x, pos)

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)

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)

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)

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)

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)

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)

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)

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.

Output Management

src.output_management.manage_output(args, infile, method)

Manages the output directories and file names for results and figures.

Parameters: - args: Parsed command-line arguments. - infile: The input file name. - method: The method used for calculations.

Returns: - Tuple containing paths for results subdirectory, figures subdirectory, and the output file name.

src.output_management.backup_file(source_path, destination_directory)

Copies a file to a destination directory for backup purposes.

Parameters: - source_path: Path to the source file. - destination_directory: Directory where the file will be copied.

src.output_management.save_results_netcdf(out_nc, results_subdirectory, outfile_name, app_logger)

Saves the calculation results to a NetCDF file.

Parameters: - MovingObj: The object containing calculation results. - stored_terms: List of terms to be saved. - results_subdirectory: Directory where results will be saved. - outfile_name: Base name for the output file. - app_logger: Logger for outputting information and error messages.

src.output_management.save_results_csv(results_df_dictionary, results_subdirectory, app_logger)

Saves the calculation results to CSV files for each term.

Parameters: - results_df_dictionary: Dictionary of pandas DataFrames for each term. - results_subdirectory: Directory where results will be saved. - app_logger: Logger for outputting information and error messages.

src.output_management.save_output_track(output_track_attributes, args, results_subdirectory, figures_subdirectory, outfile_name, app_logger)

Saves track data to a CSV file and generates track and min/max zeta height plots.

Parameters: - output_track_attributes: Dictionary containing track attributes. - args: Command-line arguments or parameters specifying calculation options. - results_subdirectory: Directory where the track CSV will be saved. - figures_subdirectory: Directory where figures will be saved. - outfile_name: Base name for the output track file. - app_logger: Logger for outputting information and error messages.

Visualization

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)

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.

src.visualization.map_features(ax)

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.

src.visualization.Brazil_states(ax, facecolor='#a4ab98')

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.

src.visualization.plot_fixed_domain(limits, data_plevel, args, results_subdirectory, time, app_logger)

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.

src.visualization.plot_track(track, args, figures_directory, app_logger)

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.

src.visualization.plot_min_max_zeta_hgt(track_plotting, args, figs_dir, app_logger, max_ticks=10)

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.

src.visualization.hovmoller_mean_zeta(Zeta, figures_subdirectory, app_logger)

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.

Utilities

src.utils.initialize_logging(results_subdirectory, args)

Initializes the logging configuration for the application.

Parameters:

• results_subdirectory (str) – Directory path to save the log file.

• args (object) – The argparse object containing the command line arguments.

src.utils.convert_lon(input_data, longitude_indexer)

Convert longitudes from 0:360 range to -180:180

Parameters:

• xr (xarray.DataArray) – gridded data.

• longitude_indexer (str) – corrdinate indexer used for longitude.

Returns:

xr – gridded data with longitude converted to desired format.

Return type:

xarray.DataArray

src.utils.handle_track_file(input_data, times, longitude_indexer, latitude_indexer, app_logger)

Handles the track file by validating its time and spatial limits against the provided dataset.

Parameters:

• data (xr.Dataset) – A Xarray Dataset containing the data to compute the energy cycle.

• times (pd.DatetimeIndex) – The time series of the dataset.

• LonIndexer (str) – The name of the longitude coordinate in the dataset.

• LatIndexer (str) – The name of the latitude coordinate in the dataset.

• args (argparse.Namespace) – Arguments provided to the script.

• app_logger (logging.Logger) – Logger for logging messages.

Returns:

DataFrame containing the track information if the track file is valid.

Return type:

pd.DataFrame

Raises:

• FileNotFoundError – If the track file is not found.

• ValueError – If the time or spatial limits of the track file do not match the dataset.

src.utils.find_extremum_coordinates(ds_data, lat, lon, variable, args)

Finds the indices of the extremum values for a given variable.

Args: ds_data: An xarray DataArray containing the data to compute the energy cycle. lat: An xarray DataArray containing the latitudes of the data. lon: An xarray DataArray containing the longitudes of the data. variable: A string containing the name of the variable to find the indices for.

Returns: A tuple containing the indices of the extremum values for the specified variable.

src.utils.slice_domain(input_data, args, namelist_df)

Slices the input dataset according to the specified domain. The domain can be defined based on fixed boundaries, track information, or an interactively selected area.

Parameters: - input_data (xr.Dataset): The dataset containing meteorological variables. - args (argparse.Namespace): Parsed command-line arguments indicating the slicing method. - namelist_df (pd.DataFrame): DataFrame mapping variable names to their respective dataset labels.

Returns: - xr.Dataset: The sliced dataset within the specified domain.

src.utils.get_domain_extreme_values(itime, args, slices_plevel, track=None)

Retrieves or calculates extreme values (minimum/maximum vorticity, minimum geopotential height, and maximum wind speed) within a specified domain at chosen pressure level.

Parameters: - track (pd.DataFrame): Track data potentially containing extreme values. - itime (str or pd.Timestamp): The specific time step for which to retrieve or calculate extremes. - args (argparse.Namespace): Parsed command-line arguments indicating the slicing method. - slices_plevel (tuple): Tuple containing slices of vorticity, geopotential height, and wind speed at chosen pressure level.

Returns: - tuple: Containing minimum/maximum vorticity, minimum geopotential height, and maximum wind speed.

Command Line Interface

src.cli_interface.parse_arguments(custom_args=None)

Parses command-line arguments.

Parameters:

custom_args (list, optional) – A list of argument strings for debugging.

Returns:

Namespace object containing parsed arguments.

Return type:

args (Namespace)

ERA5 Data Download

ERA5 Data Download Module

This module provides functionality for downloading ERA5 atmospheric reanalysis data from the Copernicus Climate Data Store (CDS). It handles authentication, data requests, and automatic file management for ATMOS-BUD workflows.

Author: Danilo Couto de Souza Date: 2024

src.get_era5_data.download_era5_data(variables: List[str], pressure_levels: List[int], start_date: str, end_date: str, area: List[float], output_file: str, hours: List[str] | None = None, logger: Logger | None = None) → None

Downloads ERA5 reanalysis data from the Copernicus Climate Data Store using the modern CDSAPI.

This function provides a flexible interface for downloading ERA5 atmospheric data with configurable variables, pressure levels, time periods, and spatial domains. Uses the modern CDSAPI 0.7.6+ syntax with list-based parameters.

Parameters:

• variables (List[str]) – List of ERA5 variable names to download. Examples: - ‘temperature’ - ‘u_component_of_wind’ - ‘v_component_of_wind’ - ‘geopotential’ - ‘vorticity’ - ‘specific_humidity’

• pressure_levels (List[int]) – List of pressure levels in hPa. Examples: [1000, 925, 850, 700, 500, 300]

• start_date (str) – Start date in ‘YYYY-MM-DD’ format (e.g., ‘2023-01-01’)

• end_date (str) – End date in ‘YYYY-MM-DD’ format (e.g., ‘2023-01-31’)

• area (List[float]) – Spatial domain as [North, West, South, East] in decimal degrees. Example: [20, -80, -60, -20] for South America region

• output_file (str) – Output filename for the downloaded NetCDF file

• hours (Optional[List[str]], default None) – List of hours in ‘HH:MM’ format. If None, uses [‘00:00’, ‘06:00’, ‘12:00’, ‘18:00’]

• logger (Optional[logging.Logger], default None) – Logger object for progress tracking and error reporting

Returns:

Downloads file directly to specified output path

Return type:

None

Raises:

Exception – If download fails due to authentication, network, or API errors

Notes

• Requires valid CDS API credentials in ~/.cdsapirc

• Uses modern CDSAPI syntax (version 0.7.6+)

• Automatically handles date range conversion to required format

• Includes progress monitoring and comprehensive error handling

Examples

>>> # Basic usage for atmospheric budget analysis
>>> variables = ['temperature', 'u_component_of_wind', 'v_component_of_wind', 'geopotential']
>>> levels = [850, 700, 500, 300]
>>> download_era5_data(
...     variables=variables,
...     pressure_levels=levels,
...     start_date='2023-01-01',
...     end_date='2023-01-31',
...     area=[10, -80, -40, -30],
...     output_file='era5_january2023.nc'
... )

>>> # Custom time selection
>>> download_era5_data(
...     variables=['vorticity', 'geopotential'],
...     pressure_levels=[850],
...     start_date='2023-06-15',
...     end_date='2023-06-15',
...     area=[-10, -70, -30, -40],
...     output_file='era5_single_day.nc',
...     hours=['00:00', '12:00']
... )

src.get_era5_data.download_era5_data_legacy()

Legacy download function for backward compatibility.

Downloads specific ERA5 data for the 2005-08-08 to 2005-08-14 case study over the South America region. This function maintains compatibility with existing workflows while the main download_era5_data function provides more flexibility.

Returns:

Downloads data to ‘system-20050808_ERA5.nc’

Return type:

None

Notes

This function is maintained for backward compatibility. For new workflows, use the main download_era5_data function which provides more flexibility.