Metadata-Version: 2.4
Name: nex-gddp
Version: 0.1.0
Summary: Download NASA NEX-GDDP-CMIP6 climate projection data by variable, model, scenario, year, and spatial extent.
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# nex-gddp

Download [NASA NEX-GDDP-CMIP6](https://www.nccs.nasa.gov/services/data-collections/land-based-products/nex-gddp-cmip6) climate projection data with spatial and temporal filtering.

## Installation

```bash
pip install nex-gddp
```

Or install from source:

```bash
git clone https://github.com/your-username/nasa-nex-gddp-cmip6-download.git
cd nasa-nex-gddp-cmip6-download
pip install -e .
```

## Python API

```python
from nex_gddp import download

# Download daily minimum temperature for a single model and year
download(
    variables="tasmin",
    years=2030,
    models="ACCESS-CM2",
    scenarios="ssp245",
    bbox=(26.2, 36.3, 30.0, 39.4),  # west, south, east, north
)

# Download multiple variables, years, and models
download(
    variables=["tasmin", "tasmax", "pr"],
    years=range(2020, 2051),
    models=["ACCESS-CM2", "MIROC6", "CanESM5"],
    scenarios=["ssp245", "ssp585"],
    output_dir="./my_data",
    max_workers=5,
)

# Download all models (omit the models argument)
download(variables="pr", years=2025, scenarios="ssp245")
```

### Listing available options

```python
from nex_gddp import list_models, list_variables, list_scenarios

list_models()      # 34 CMIP6 models
list_variables()   # 9 variables
list_scenarios()   # historical + 4 SSP scenarios
```

## CLI

```bash
# Download data
nex-gddp download -v tasmin -y 2030 -m ACCESS-CM2 -s ssp245 -b 26.2,36.3,30.0,39.4

# Year ranges and multiple values
nex-gddp download -v tasmin tasmax pr -y 2020-2050 -m ACCESS-CM2 MIROC6 -s ssp245 ssp585

# Download all models for a variable
nex-gddp download -v pr -y 2025 -s ssp245

# List available models, variables, and scenarios
nex-gddp list-models
nex-gddp list-variables
nex-gddp list-scenarios
```

### CLI options

| Flag | Short | Description |
|------|-------|-------------|
| `--variable` | `-v` | Variable(s) to download (required) |
| `--years` | `-y` | Year or range: `2020`, `2020-2050`, `2020,2025,2030` (required) |
| `--models` | `-m` | Model name(s). Omit for all 34 models |
| `--scenario` | `-s` | SSP scenario(s) (default: `ssp245`) |
| `--bbox` | `-b` | Bounding box: `west,south,east,north` (omit for global) |
| `--output` | `-o` | Output directory (default: `./data`) |
| `--workers` | `-w` | Concurrent downloads (default: `5`) |

## Available data

### Variables

| Variable | Description |
|----------|-------------|
| `hurs` | Near-Surface Relative Humidity |
| `huss` | Near-Surface Specific Humidity |
| `pr` | Precipitation |
| `rlds` | Surface Downwelling Longwave Radiation |
| `rsds` | Surface Downwelling Shortwave Radiation |
| `sfcWind` | Near-Surface Wind Speed |
| `tas` | Daily Mean Near-Surface Air Temperature |
| `tasmax` | Daily Maximum Near-Surface Air Temperature |
| `tasmin` | Daily Minimum Near-Surface Air Temperature |

### Scenarios

| Scenario | Description |
|----------|-------------|
| `historical` | Historical (1950-2014) |
| `ssp126` | Low emissions |
| `ssp245` | Medium emissions |
| `ssp370` | Medium-high emissions |
| `ssp585` | High emissions |

### Models

34 CMIP6 models are available. Run `nex-gddp list-models` or `list_models()` to see the full list.

## Output structure

Files are saved as NetCDF with the following directory layout:

```
data/
  ACCESS-CM2/
    ssp245/
      tasmin/
        tasmin_ACCESS-CM2_r1i1p1f1_gn_2030.nc
```

## License

MIT
