Nocturnal Calculator

Automatic detection and quantification of Nocturnal Low-Level Jets (NLLJ) in South America using ERA5 reanalysis data.

Features

• ✅ Automatic optimization of pressure level combinations
• ✅ NLLJ index calculation following Braz et al. (2021)
• ✅ Seasonal climatology generation (DJF, MAM, JJA, SON)
• ✅ Publication-ready maps with Cartopy

Installation

# Clone repository
git clone https://github.com/yourusername/nllj-calculator.git
cd nllj-calculator

# Install dependencies
pip install -r requirements.txt

Requirements

• Python 3.7+
• numpy
• xarray
• matplotlib
• cartopy
• pandas

Quick Start

1. Download ERA5 data

If you don't have ERA5 data yet, see detailed instructions in data_download/README_DOWNLOAD.md.

Quick version:

# Configure CDS API (one time only)
nano ~/.cdsapirc  # Add your CDS credentials

# Download data
cd data_download
python download_era5.py

Files will be named: era5_southamerica_YYYY_MM.nc

2. Prepare ERA5 data

Organize your ERA5 monthly files as:

/data/era5_southamerica_YYYY_MM.nc

Each file must contain:

• Variables: u (zonal wind), v (meridional wind)
• Coordinates: latitude, longitude, pressure_level, valid_time
• Pressure levels: 1000, 950, 900, 850, 700, 650, 600, 550, 500 hPa
• Times: 00, 06, 12, 18 UTC

2. Run the calculator

from nllj_calculator import NLLJCalculator

# Initialize
calc = NLLJCalculator(data_dir='/path/to/your/data')

# Step 1: Find optimal pressure levels
results_df = calc.analyze_all_level_combinations(year=1980, month=1)

# Step 2: Calculate climatology
seasonal_clim = calc.calculate_climatology(year=1980)

# Step 3: Generate maps
from nllj_calculator import plot_seasonal_maps
plot_seasonal_maps(seasonal_clim, year=1980, 
                   level_lower=calc.level_lower, 
                   level_upper=calc.level_upper)

3. Command line usage

# Full analysis (includes level optimization)
python nllj_calculator.py

# Skip level analysis (use default 900-650 hPa)
python nllj_calculator.py --skip-analysis

Output Files

1. level_combination_results.csv - Statistical metrics for all tested pressure level combinations
2. level_combination_analysis.png - Four-panel analysis plot showing optimization results
3. nllj_climatology_YYYY_LLL-UUU.png - Seasonal maps with selected pressure levels

Methodology

The NLLJ index is calculated as:

NLLJ = λ × φ × √(X² + Y²)

where:

• X, Y: Wind shear differences between night (00 LT) and day (12 LT)
• λ: Binary parameter (1 if nocturnal acceleration exists, 0 otherwise)
• φ: Binary parameter (1 if vertical wind maximum exists, 0 otherwise)

See paper.md for detailed mathematical formulation.

Example Results

Typical NLLJ patterns over South America show:

• DJF (Summer): Strong jets over central South America
• JJA (Winter): Enhanced activity in subtropical regions
• Core regions: Eastern Andes foothills, Chaco lowlands

Citation

If you use this tool, please cite:

@article{Braz2021,
  author = {Braz, D. F. and Ambrizzi, T. and da Rocha, R. P. and 
            Algarra, I. and Nieto, R. and Gimeno, L.},
  title = {Assessing the Moisture Transports Associated With 
           Nocturnal Low-Level Jets in Continental South America},
  journal = {Frontiers in Environmental Science},
  volume = {9},
  pages = {657764},
  year = {2021},
  doi = {10.3389/fenvs.2021.657764}
}

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

License

MIT License - see LICENSE file

Contact

Dejanira F. Braz - [dejafbraz@gmail.com]

Acknowledgements

Based on methodology published in Braz et al. (2021), Frontiers in Environmental Science.