Metadata-Version: 2.4
Name: gri-tropo-data
Version: 0.2.3
Summary: ERA5 data pipeline for generating tropospheric refractivity datasets
Project-URL: Homepage, https://geosolresearch.com
Project-URL: Repository, https://gitlab.com/geosol-foss/python/gri-tropo-data
Project-URL: Issues, https://gitlab.com/geosol-foss/python/gri-tropo-data/-/issues
Project-URL: Changelog, https://gitlab.com/geosol-foss/python/gri-tropo-data/-/releases
Author-email: GeoSol Research Inc <contact@geosolresearch.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ERA5,data-pipeline,refractivity,troposphere
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.12
Requires-Dist: ecmwf-datastores-client>=0.4.1
Requires-Dist: gri-utils>=0.3.3
Requires-Dist: netcdf4>=1.7.3
Requires-Dist: numpy>=2.3.3
Requires-Dist: xarray>=2025.11.0
Description-Content-Type: text/markdown

[![GeoSol Research Logo](https://geosolresearch.com/logos/foss_logo.png "GeoSol Research")](https://geosolresearch.com)

# Tropo Data (Troposphere Data Processing)

ERA5 data download and processing tools for generating tropospheric refractivity datasets used by [gri-tropo](https://gitlab.com/geosol-foss/python/gri-tropo). Requires Python 3.12+.

## Overview

This package provides scripts for:

- **Downloading ERA5 reanalysis data** from the Copernicus Climate Data Store (CDS)
- **Processing surface data** to calculate surface refractivity (n_sur)
- **Processing pressure-level data** to calculate reference heights (ref_ht)

The output NPZ files are consumed by the `gri-tropo` library for tropospheric correction calculations.

## Installation

```bash
# Clone and setup
git clone https://gitlab.com/geosol-foss/python/gri-tropo-data.git
cd gri-tropo-data
uv sync

# Activate environment
source .venv/bin/activate
```

## Usage

### 1. Download ERA5 Data

Download ERA5 surface and pressure-level data for a specific date:

```bash
python -m gri_tropo_data.download_era5 2025 03 15
```

**Output:**

- `./data/era5_raw/era5_surface_2025_03_15.nc` - Surface meteorological data
- `./data/era5_raw/era5_pressure_2025_03_15.nc` - Pressure-level data

**Note:** Requires CDS API credentials. Register at the [Copernicus Climate Data Store](https://cds.climate.copernicus.eu/) and configure your `~/.cdsapirc` file with your UID and API key. See [setup instructions](gri_tropo_data/download_era5.py) in the script header.

### 2. Process Surface Refractivity Data

Process all unprocessed ERA5 surface data to generate n_sur files:

```bash
python -m gri_tropo_data.update_nsur
```

**Output:**

- `./data/n_sur/n_sur_2025_03_15.npz` - Surface refractivity data

### 3. Process Reference Height Data

Process all unprocessed ERA5 pressure-level data to generate ref_ht files:

```bash
python -m gri_tropo_data.update_refht
```

**Output:**

- `./data/ref_ht/ref_ht_2025_03_15.npz` - Reference height data

## Data Formats

### Downloaded ERA5 Data

**Surface Data (Single-Level):**

- Variables: 2m temperature, surface pressure, 2m dewpoint temperature
- Temporal resolution: Hourly (24 snapshots per day)
- Spatial resolution: 1 x 1 degree global grid

**Pressure-Level Data:**

- Variables: Temperature, geopotential, specific humidity
- Pressure levels: 1000, 925, 850, 700, 500, 300 hPa
- Temporal resolution: Hourly (24 snapshots per day)
- Spatial resolution: 1 x 1 degree global grid

### Processed NPZ Files

**n_sur files** - Shape: `(181, 360, 24)` for `(latitude, longitude, hour)`

- Surface refractivity in N-units
- Hourly data for a single day

**ref_ht files** - Shape: `(181, 360)` for `(latitude, longitude)`

- Reference height in meters (scale height of exponential refractivity decay)
- Daily average data

**Indexing scheme:**

- Latitudes: indices 0-90 for 0 to 90 degrees N, indices 91-180 for -90 to -1 degrees S
- Longitudes: indices 0-359 for 0 to 359 degrees E
- Hours (n_sur only): indices 0-23 for UTC hours

See [detailed format documentation](gri_tropo_data/README.md) for more information.

## Configuration

All scripts default to `./data/` for input/output but can be configured by modifying the paths in the scripts.


## Other Projects

Current list of other [GRI FOSS Projects](https://gitlab.com/geosol-foss/python/gri-tropo-data/-/blob/main/.docs_other_projects.md) we are building and maintaining.

## License

MIT License. See [LICENSE](https://gitlab.com/geosol-foss/python/gri-tropo-data/-/blob/main/LICENSE) for details.
