| name | ameriflux-atmchem-info |
| description | Extract EPA/NADP tDEP atmospheric deposition and NADP precipitation chemistry rasters for an AmeriFlux or EcoSIM site. Use when deriving atmospheric chemistry inputs such as NH4, NO3, SO4, Ca, or precipitation pH for EcoSIM forcing workflows. |
AmeriFlux Atmospheric Chemistry Extractor
Use When
- You need tDEP atmospheric deposition data for a latitude/longitude and year range.
- You need NADP wet chemistry values for EcoSIM precipitation chemistry variables.
- You are preparing EcoSIM climate forcing inputs that include
PHRG, CN4RIG, CNORIG, CSORG, or CCARG.
Constraints
- NEVER use it to extract soil data.
Workflow
- Confirm whether the user needs tDEP fluxes or NADP wet chemistry.
- Locate the source rasters under
data/ first, then elsewhere in the repo if needed.
- Run the matching extractor with latitude, longitude, and the inclusive year range.
- Reject NoData, non-finite, negative concentration values, and pH values outside 0-14.
- Preserve units and derivation notes in the output JSON.
Overview
This tool extracts atmospheric deposition data from the EPA/NADP Total Deposition (tDEP) database. It processes high-resolution GeoTIFF files to retrieve chemical concentrations and precipitation totals for a specific geographic location (latitude/longitude) over a user-defined range of years.
The tool automatically handles the Albers Equal Area Conic projection used by tDEP and performs unit conversions to provide concentrations in $g/m^3$, matching the requirements for environmental models like EcoSIM.
Dependencies
The script requires a Python 3.12+ environment with the following libraries:
rasterio: For reading and sampling GeoTIFF data.pyproj: For coordinate transformation from WGS84 to the tDEP Albers projection.argparse: For command-line interface management.json: For structured data output.
Install dependencies via pip:
pip install rasterio pyproj
Data Structure Requirements
The script expects the tDEP database to be organized into year-specific sub-directories within a base folder. Each sub-directory must contain the .tif files for the desired chemical species.
Example tDEP Directory Tree:
data/tDEP/
├── tDEP-2012/
│ ├── nh4_ww.tif
│ ├── no3_ww.tif
│ └── precip_ww.tif
├── tDEP-2013/
│ ├── ...
Example NADP Directory Tree:
data/nadp_data_grids/
├── 2012/
│ ├── Ca_conc_2012/conc_ca_2012.tif
│ ├── Cl_conc_2012/conc_cl_2012.tif
│ └── K_conc_2012/conc_k_2012.tif
├── 2013/
│ ├── ...
Variable Mapping
for tDEP:
The following variables are extracted and mapped to internal keys:
| Template Variable | tDEP Prefix | Description |
|---|
CN4RIG | nh4_ww | Ammonium ($NH_4$) concentration |
CNORIG | no3_ww | Nitrate ($NO_3$) concentration |
CSORG | s_ww | Sulfate ($SO_4$) concentration |
CCARG | ca_ww | Calcium ($Ca$) concentration |
for NADP:
| Template Variable | NADP Prefix | Description |
|---|
PHRG | phlab | pH in precipitation |
CN4RIG | nh4 | Ammonium ($NH_4$) concentration |
CNORIG | no3 | Nitrate ($NO_3$) concentration |
CSORG | so4 | Sulfate ($SO_4$) concentration |
CCARG | ca | Calcium ($Ca$) concentration |
NADP extraction must reject NoData, non-finite, negative concentration values, and pH values outside 0-14. The pH raster phlab must be emitted under the raw key ph so the climate writer can derive PHRG.
When the EcoSIM climate forcing writer consumes NADP chemistry, valid annual gaps are filled by linear interpolation with nearest-edge filling. If no valid NADP pH is available for PHRG, set PHRG to 7 for every year and record that default in the derivation report.
Usage
Command Line Arguments
--input: The base path to the tDEP data directory.--output: Path where the resulting .json file will be saved.--longitude: Longitude in decimal degrees (WGS84).--latitude: Latitude in decimal degrees (WGS84).--year1: The starting year of the range (e.g., 2012).--year2: The ending year of the range (e.g., 2022).
Execution Example
To extract atmospheric chemistry data from tDEP for a site located at longitude -72.17 and latitude 42.54 from 2012 to 2022:
python .agents/skills/ameriflux-atmchem-info/extract_tdep_from_dir.py \
--input data/tDEP/ \
--output result/site_chem.json \
--longitude -72.17 \
--latitude 42.54 \
--year1 2012 \
--year2 2022
To extract atmospheric chemistry data from NADP for the same site and time range:
python .agents/skills/ameriflux-atmchem-info/extract_nadp_range.py \
--input data/nadp_data_grids/ \
--output result/site_chem.json \
--longitude -72.17 \
--latitude 42.54 \
--year1 2012 \
--year2 2022
Technical Details
Coordinate Transformation
tDEP data is natively stored in a custom Albers Equal Area projection. The script bypasses common ProjError issues by manually defining the PROJ string to ensure precise pixel sampling:
+proj=aea +lat_1=29.5 +lat_2=45.5 +lat_0=23 +lon_0=-96 +x_0=0 +y_0=0 +datum=NAD83 +units=m +no_defs
Unit Conversion
for tDEP:
The script converts wet deposition flux ($kg/ha$) into atmospheric concentration ($g/m^3$) using the annual precipitation ($P$):
$$Concentration = \frac{Flux_{kg/ha} \times 0.1}{P_{meters}}$$
for NADP:
The script converts concentration from $mg/L$ to $g/m^3$ using the formula:
$$Concentration = \frac{Conc_{mg/L}}{1000} \times 1000$$
