bioepic-data/ecosim-agent / .agents/skills/nldas-gesdisc-point-download
nldas-gesdisc-point-download
VerifiedDownload NASA GES DISC NLDAS_FORA0125_H version 2.0 primary hourly forcing data for a point location. Use when Codex needs to retrieve NLDAS File A meteorological forcing from the GES DISC API or HTTPS archive for a longitude/latitude pair, including Earthdata username/password authentication, hourly URL generation, nearest-grid-point extraction, CSV output, or EcoSIM climate-forcing preprocessing.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.2 KB |
| agents/openai.yaml | config | 261 B |
| references/nldas_gesdisc_api.md | markdown | 4.8 KB |
| scripts/download_nldas_fora_point.py | script | 319 B |
| scripts/download_nldas_forb_point.py | script | 53.2 KB |
| scripts/download_nldas_giovanni_ecosim.py | script | 34.4 KB |
SKILL.md
View on GitHub---
name: nldas-gesdisc-point-download
description: Download NASA GES DISC NLDAS_FORA0125_H version 2.0 primary hourly forcing data for a point location. Use when Codex needs to retrieve NLDAS File A meteorological forcing from the GES DISC API or HTTPS archive for a longitude/latitude pair, including Earthdata username/password authentication, hourly URL generation, nearest-grid-point extraction, CSV output, or EcoSIM climate-forcing preprocessing.
---
# NLDAS GES DISC Point Download
## Overview
Use this skill to retrieve `NLDAS_FORA0125_H` version `2.0` primary hourly forcing ("File A") from NASA GES DISC for a single point. The user-provided location is always longitude first, latitude second. Output must contain only the requested location or the nearest native NLDAS grid point, never a spatial grid.
Prefer the bundled script for repeatable downloads and point extraction. By default, it uses GES DISC OPeNDAP constraint expressions to request only scalar values for the nearest NLDAS grid cell; it does not download full gridded NetCDF granules unless `--access-method https-granule` is explicitly selected. In this repository, use `.venv-cmip6/bin/python` when extracting values because it includes the NetCDF stack needed by the fallback granule path:
```bash
.venv-cmip6/bin/python .agents/skills/nldas-gesdisc-point-download/scripts/download_nldas_fora_point.py \
--lon -72.1715 \
--lat 42.5378 \
--auto-span complete-calendar-years \
--allow-large-download \
--output result/nldas/US-Ha1_nldas_fora_primary.csv
```
If credentials are not provided as command-line arguments, the script checks `USR_NLDAS` and `PASSWD_NLDAS`. A `.netrc` file is used only when explicitly passed with `--netrc-file`. Never write credentials to output files, manifests, logs, or shell snippets shown back to the user.
When `USR_NLDAS` and `PASSWD_NLDAS` are defined in `~/.bashrc` but are not visible in the current shell process, the script sources `~/.bashrc` and reads only those two variables into memory.
## Inputs
- `--lon`: longitude in decimal degrees, west negative. Must be in the NLDAS domain `[-125, -67]`.
- `--lat`: latitude in decimal degrees. Must be in the NLDAS domain `[25, 53]`.
- `--start`, `--end`: UTC timestamps. Accept `YYYY-MM-DD`, `YYYY-MM-DDTHH`, or `YYYY-MM-DDTHH:MM`. The script downloads all whole UTC hours from start through end, inclusive.
- `--auto-span complete-calendar-years`: infer the first complete UTC calendar year and last complete UTC calendar year from the GES DISC archive. Use this for EcoSIM annual forcing.
- `--auto-span available-years`: start at the first actual product hour and end at the last complete UTC calendar year. For `NLDAS_FORA0125_H`, this includes partial year 1979 starting at `1979-01-01T13:00Z`.
- `--variables`: optional native NLDAS variable list. Defaults to the EcoSIM climate-native set: `Tair`, `Wind_E`, `Wind_N`, `Rainf`, `Qair`, `SWdown`, `PSurf`.
- `--variable-set`: `ecosim-climate` by default; use `all-primary-file-a` only when the user explicitly asks for non-EcoSIM File A fields.
- `--username`, `--password`: optional Earthdata credentials that override `USR_NLDAS` and `PASSWD_NLDAS`.
- `--credential-profile`: bash profile to source for credentials, default `~/.bashrc`.
- `--access-method`: `opendap-point` by default for scalar point API access; use `https-granule` only when debugging or when the OPeNDAP service is unavailable.
- `--keep-raw`: keep full hourly NetCDF granules after point extraction. By default, newly downloaded raw granules are deleted after selected-location CSV extraction.
- `--allow-large-download`: required when a request exceeds the large-download threshold. Without it, the script writes a manifest with the inferred span and aborts before issuing many hourly API requests.
- `download_nldas_fora_point.py --allow-invalid` and `download_nldas_giovanni_ecosim.py --allow-invalid`: allow outputs even when validity checks flag out-of-range values. By default, validity failures make the command exit nonzero after writing the manifest or quality report.
## Data Source Facts
Load [references/nldas_gesdisc_api.md](references/nldas_gesdisc_api.md) when you need endpoint details, official links, file naming, authentication notes, or variable definitions.
Core facts:
- Collection: `NLDAS_FORA0125_H_2.0`.
- OPeNDAP point API base: `https://hydro1.gesdisc.eosdis.nasa.gov/opendap/NLDAS/NLDAS_FORA0125_H.2.0/`.
- HTTPS archive base: `https://hydro1.gesdisc.eosdis.nasa.gov/data/NLDAS/NLDAS_FORA0125_H.2.0/`.
- File pattern: `YYYY/DDD/NLDAS_FORA0125_H.AYYYYMMDD.HH00.020.nc`, where `DDD` is day of year.
- Spatial domain: west `-125`, east `-67`, south `25`, north `53`.
- Native temporal resolution: hourly UTC.
- Dataset summary: `https://disc.gsfc.nasa.gov/datasets/NLDAS_FORA0125_H_2.0/summary?keywords=NLDAS`.
- CMR reports the first product time as `1979-01-01T13:00:00Z`; the GES DISC archive currently has year folders through `2026`, so on `2026-06-26` the complete calendar-year span is `1980-01-01T00:00Z` through `2025-12-31T23:00Z`.
EcoSIM climate-native variables downloaded/extracted by default:
- `Tair`: maps to `TMPH` after K to degC conversion.
- `Wind_E`, `Wind_N`: map to `WINDH` as scalar wind speed.
- `Rainf`: maps to `RAINH`; native `kg m-2` hourly accumulation is numerically equivalent to mm water.
- `Qair`, `PSurf`: used to derive atmospheric vapor pressure for `DWPTH`.
- `SWdown`: maps to `SRADH`.
- `PSurf`: maps to `PATM` after Pa to kPa conversion.
EcoSIM annual auxiliary variables written by the Giovanni EcoSIM writer:
- `Z0G`, `IFLGW`, and `ZNOONG` are derived directly from site/grid assumptions and longitude.
- For US/NLDAS-domain grids, precipitation chemistry variables are added from the same NADP source used by US AmeriFlux workflows: `PHRG`, `CN4RIG`, `CNORIG`, `CSORG`, `CCARG`, and other supported template variables when source rasters exist.
- The Giovanni EcoSIM writer defaults to `--add-us-chemistry auto`, which adds NADP chemistry for coordinates in `[-125, -67]` longitude and `[25, 53]` latitude. Use `--add-us-chemistry never` to skip or `--add-us-chemistry always` to force.
- Use `--chemistry-input` to point to an alternate NADP raster directory and `--chemistry-output` to choose the intermediate extracted-chemistry JSON path.
Additional primary File A variables (include `LWdown` for complete EcoSIM
meteorological forcing; other entries only when explicitly requested):
- `LWdown`: downward longwave radiation, `W m-2`.
- `PotEvap`: potential evaporation, `kg m-2`.
- `CAPE`: convective available potential energy, `J kg-1`.
- `CRainf_frac`: fraction of total precipitation that is convective.
## Workflow
1. Confirm the user supplied longitude then latitude. If a value looks swapped, stop and ask for clarification because the grid-cell choice affects water and energy forcing.
2. Confirm the requested period and variables. Interpret all times as UTC unless the user explicitly says otherwise.
3. When the user asks for "first to last available year" for EcoSIM, use `--auto-span complete-calendar-years`; verify actual archive availability and exclude partial boundary years. Do not infer the latest complete year from the current date alone.
4. Ensure Earthdata credentials are available when GES DISC requires authentication. The standard repo workflow is to set `USR_NLDAS` and `PASSWD_NLDAS` in `~/.bashrc`; the script sources that file automatically when needed. The user may still pass `--username` and `--password` to override.
5. Run the script from the repository root.
6. Inspect the generated CSV and manifest:
- Check requested lon/lat and selected grid lon/lat.
- Check that every requested UTC hour is represented.
- Check that the variable set is `ecosim-climate` unless the user explicitly requested another set.
- Check units before converting to EcoSIM forcing names.
- Check the quality report's `validity_checks.all_passed` field before using the NetCDF in an EcoSIM run.
- For EcoSIM NetCDF outputs, check `annual_forcing.auxiliary_climate_variables` to confirm whether NADP chemistry was added, skipped, or default-filled.
## Output Rules
- Put outputs under `result/` unless the user provides another path.
- The EcoSIM climate NetCDF is named by the forcing years it contains, `<SITE_ID>_nldas_ecosim_climate_<first>-<last>.nc`.
- The default OPeNDAP access path writes only scalar point values for the selected nearest native NLDAS grid cell. The HTTPS archive fallback serves full hourly NetCDF granules; when that fallback is used, the script extracts the point and removes newly downloaded raw granules unless `--keep-raw` is supplied.
- Long automatic spans are request-heavy. For `1980-2025`, expect `403,248` hourly point API requests. The script refuses such runs unless `--allow-large-download` is explicitly supplied.
- Write a JSON manifest next to the CSV. Include source URLs, selected grid cell, variables, units, and download timestamps, but never include username or password.
- Preserve native units. Do not convert precipitation, pressure, or temperature for EcoSIM until a downstream conversion step is explicitly requested.
## EcoSIM Unit Cautions
- `Tair` is Kelvin; EcoSIM climate tools often expect degC for `TMPH`.
- `PSurf` is Pa; EcoSIM climate tools often use kPa for `PATM`.
- `Rainf` is hourly accumulated water mass per area (`kg m-2`), numerically equivalent to mm water depth for liquid water density. Do not treat it as a `kg m-2 s-1` rate unless the file metadata for a future product says so.
- `Wind_E` and `Wind_N` are vector components. Compute wind speed as `sqrt(Wind_E**2 + Wind_N**2)` only when the downstream workflow needs scalar speed.
## EcoSIM time registration and case handoff
For multi-year point requests, consult
[the access reference](references/nldas_gesdisc_api.md) for the Giovanni route
before scheduling hundreds of thousands of granule requests. Verify current
service behavior; retain source metadata, point caches and checksums. A matched
native-granule sample checks extraction identity, not accuracy at the tower.
Include `LWdown` explicitly when the downloader's seven-field default would
omit incident longwave needed by the model comparison. Download boundary-buffer
hours for the requested local-standard-time calendar and adjacent endpoint
averaging. The NASA NLDAS2 README and native metadata distinguish instantaneous
meteorology/radiation from backward hourly rain accumulations. An endpoint
average approximates a mean; rain stamped at t+1 belongs to [t,t+1). Do not
apply the historical ERA empirical shift to NLDAS or multiply hourly accumulated
rain by 3600. Retain complete local years after UTC conversion, including leap
days, with explicit clock/interval metadata.
Inspect the writer's output rather than inheriting example-site defaults:
requested site coordinates, native grid coordinates, site title, pressure/vapor
pressure units, wind reference height (native 10 m), and local mean solar noon.
Check whether EcoSIM adds the equation of time before embedding it in ZNOONG.
Label annual chemistry provenance and edge-year carry-forwards independently
of the meteorological coverage. Run the shared precipitation-budget audit and
`../ecosim-climate-readiness/SKILL.md` on the final file; broad hourly bounds
alone do not establish a plausible annual water input.
When tower bias adjustment is requested, use
[`ecosim-lange-bias-adjustment`](../ecosim-lange-bias-adjustment/SKILL.md).
Preserve the raw extraction; a corrected candidate needs its own held-out
evaluation, metadata and file identity.
## Validity Checks
The bundled point downloader and Giovanni EcoSIM downloader write explicit `validity_checks` to the manifest or quality report and fail by default when a variable is outside its accepted range.
Native NLDAS checks:
- `Tair`: `183.15` to `333.15 K` (`-90` to `60 degC`).
- `Wind_E`, `Wind_N`: `-75` to `75 m s^-1`.
- `Rainf`: `0` to `500 kg m^-2 h^-1`.
- `Qair`: `0` to `0.05 kg kg^-1`.
- `SWdown`: `0` to `1400 W m^-2`.
- `PSurf`: `50000` to `110000 Pa`.
- `LWdown`: `0` to `800 W m^-2`.
- `PotEvap`: `0` to `500 kg m^-2 h^-1`.
- `CAPE`: `0` to `10000 J kg^-1`.
- `CRainf_frac`: `0` to `1`.
EcoSIM checks:
- `TMPH`: `-90` to `60 degC`.
- `WINDH`: `0` to `75 m s^-1`.
- `RAINH`: `0` to `500 mm h^-1`.
- `DWPTH`: `0` to `15 kPa`.
- `SRADH`: `0` to `1400 W m^-2`.
- `PATM`: `50` to `110 kPa`.
Annual auxiliary checks:
- `Z0G`: positive measurement height, `0.01` to `100 m`.
- `IFLGW`: allowed flags `0` or `1`.
- `ZNOONG`: `0` to `24 hour`.
- `PHRG`: `0` to `14 pH`.
- Precipitation chemistry concentrations: non-negative.
NADP chemistry values must be finite and non-negative, with `PHRG` constrained to pH `0-14`. Annual gaps are filled by linear interpolation with nearest-edge filling. If no valid NADP pH is available, use neutral `PHRG=7` and record the fallback in the quality report. Do not silently apply NADP chemistry outside the US/NLDAS auxiliary domain.
## Validation
For any delivered extraction, report:
- Product short name and version.
- Requested longitude/latitude and selected grid-cell longitude/latitude.
- UTC start/end and number of hourly files.
- Variables extracted and their native units.
- Whether `validity_checks.all_passed` is true and which variables failed if false.
- Whether authentication was supplied via CLI arguments, `USR_NLDAS`/`PASSWD_NLDAS`, or not needed. Do not reveal credential values.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |