ameriflux-atmchem-info

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

1. Confirm whether the user needs tDEP fluxes or NADP wet chemistry.
2. Locate the source rasters under data/ first, then elsewhere in the repo if needed.
3. Run the matching extractor with latitude, longitude, and the inclusive year range.
4. Reject NoData, non-finite, negative concentration values, and pH values outside 0-14.
5. 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$$