CAMELS Attrs

A Python package for extracting CAMELS-like catchment attributes and hydrometeorological timeseries for any USGS gauge in the United States.

Key Capabilities

• Automated Attribute Extraction: Extract 60+ catchment attributes following CAMELS methodology
• Watershed Delineation: Automatic watershed boundary extraction for any USGS gauge
• Timeseries Data: Fetch daily hydrometeorological forcing data (precipitation, temperature, PET, etc.)
• Batch Processing: Process multiple gauges simultaneously
• Visualization: Create publication-ready watershed maps
• CLI & Python API: Use via command-line or integrate into Python workflows

Installation

pip install camels-attrs

Quick Start

Command Line

# Extract all attributes for a gauge
camels-extract 01031500 -o attributes.csv

# Extract multiple gauges
camels-extract 01031500 02177000 06803530 -o combined.csv

# Include timeseries data
camels-extract 01031500 --timeseries -o data.csv

# Custom date ranges
camels-extract 01031500 --climate-start 2010-01-01 --climate-end 2020-12-31

Python API

from camels_attrs import CamelsExtractor

# Single gauge extraction
extractor = CamelsExtractor('01031500')
attributes = extractor.extract_all()

# Save to file
extractor.save('attributes.csv')

# Extract timeseries
forcing_data = extractor.extract_timeseries(
    start_date='2010-01-01',
    end_date='2020-12-31'
)

# Create watershed map
extractor.create_comprehensive_map(save_path='watershed_map.png')

from camels_attrs import extract_multiple_gauges

# Batch processing
gauge_list = ['01031500', '02177000', '06803530']
df = extract_multiple_gauges(
    gauge_list,
    climate_start='2010-01-01',
    climate_end='2020-12-31'
)
df.to_csv('batch_attributes.csv')

Extracted Attributes (60+)

Data Sources

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# With coverage
pytest tests/ --cov=camels_attrs

Citation

If you use this package in your research, please cite:

Galib, M., & Merwade, V. (2025). camels-attrs: A Python Package for Extracting 
CAMELS-like Catchment Attributes (v1.0.2). Zenodo. 
https://doi.org/10.5281/zenodo.17315038

References

• Newman et al. (2015). Development of a large-sample watershed-scale hydrometeorological dataset. NCAR Technical Note
• Addor et al. (2017). The CAMELS data set: catchment attributes and meteorology for large-sample studies. Hydrology and Earth System Sciences, 21, 5293-5313

Contributing

Contributions are welcome! Please submit a Pull Request or open an Issue.

License

MIT License - see LICENSE file for details.

Contact

Mohammad Galib - mgalib@purdue.edu
Venkatesh Merwade - vmerwade@purdue.edu

Purdue University