camels-attrs

Name	camels-attrs JSON
Version	1.0.1 JSON
	download
home_page	None
Summary	Extract CAMELS-like catchment attributes for any USGS gauge site in the USA
upload_time	2025-10-10 15:34:44
maintainer	None
docs_url	None
author	None
requires_python	>=3.8
license	MIT
keywords	hydrology camels catchment watershed usgs attributes
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # CAMELS Attrs

![CAMELS Attrs](assets/thumbnail.png)

[![PyPI version](https://badge.fury.io/py/camels-attrs.svg)](https://pypi.org/project/camels-attrs/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/camels-attrs)](https://pepy.tech/project/camels-attrs)

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

## Overview

This package provides a simple, reproducible way to extract comprehensive catchment attributes following the CAMELS (Catchment Attributes and Meteorology for Large-sample Studies) methodology. It automates the extraction of topographic, climatic, soil, vegetation, geological, and hydrological characteristics for any USGS-monitored watershed.
Additionally, it can fetch daily hydrometeorological forcing data (precipitation, temperature, solar radiation, wind speed, humidity) from the GridMET dataset for user-defined date ranges. The package also includes a new feature to create a comprehensive multi-panel watershed map that visualizes key attributes and spatial context.

## Features

### Static Catchment Attributes
- **Watershed Delineation**: Automated watershed boundary extraction using NLDI
- **Topographic Attributes**: Elevation, slope, and drainage area from 3DEP DEM
- **Climate Indices**: Precipitation, temperature, aridity, seasonality from GridMET
- **Soil Characteristics**: Texture, porosity, conductivity from gNATSGO and POLARIS
- **Vegetation Metrics**: LAI, NDVI/GVF, land cover from MODIS and NLCD
- **Geological Properties**: Lithology and permeability from GLiM and GLHYMPS
- **Hydrological Signatures**: Flow statistics, baseflow index, event characteristics

### Hydrometeorological Timeseries Data
- **Daily Forcing Data**: Precipitation, temperature (min/max/avg), solar radiation, wind speed, humidity
- **PET Calculations**: GridMET PET and Hargreaves-Samani PET
- **Monthly Aggregations**: Automatically compute monthly statistics
- **Water Balance**: Calculate annual water surplus and aridity indices

### Comprehensive Watershed Visualization (NEW!)
- **Multi-Panel Dashboard**: 20"×12" publication-ready watershed maps
- **DEM Elevation Background**: High-resolution terrain visualization
- **Stream Network Overlay**: NLDI-derived drainage network
- **Location Context**: USA map showing watershed location
- **Statistics Panel**: All key attributes displayed (topography, climate, vegetation, hydrology)
- **Analytical Charts**: Elevation profile, land cover pie chart, water balance comparison
- **Cartographic Elements**: Scale bar, north arrow, proper projections
- **Export Options**: High-DPI PNG/PDF for publications

## Installation

```bash
pip install camels-attrs
```

Or install from source:

```bash
git clone https://github.com/galib9690/camels-attrs.git
cd camels-attrs
pip install -e .
```

### Optional Dependencies

For geological attribute extraction (GLiM, GLHYMPS), you may need to install `pygeoglim` separately if it's not available on PyPI:

```bash
pip install git+https://github.com/galib9690/pygeoglim.git
```

If `pygeoglim` is not installed, the package will still work but will return default values for geological attributes.

## Quick Start

### Static Attributes Extraction

#### Python API

```python
from camels_attrs import CamelsExtractor

# Extract static attributes for a single gauge
extractor = CamelsExtractor('01031500')  # USGS gauge ID
attributes = extractor.extract_all()

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

# Or get as DataFrame
df = extractor.to_dataframe()
```

#### Command Line Interface

```bash
# Extract static attributes only
camels-extract 01031500 -o attributes.csv

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

# Custom date ranges for hydrological signatures
camels-extract 01031500 --hydro-start 2010-01-01 --hydro-end 2020-12-31
```

### Hydrometeorological Timeseries Data

#### Python API

```python
from camels_attrs import CamelsExtractor, fetch_forcing_data, get_monthly_summary

# Extract timeseries data using the extractor class
extractor = CamelsExtractor('01031500')
forcing_data = extractor.extract_timeseries('2020-01-01', '2020-12-31')

# Or use standalone functions
forcing_data = fetch_forcing_data(watershed_geometry, '2020-01-01', '2020-12-31')

# Calculate monthly aggregations
monthly_data = get_monthly_summary(forcing_data)

# Calculate water balance
from camels_attrs import calculate_water_balance
water_balance = calculate_water_balance(forcing_data)
```

#### Command Line Interface

```bash
# Extract both static attributes AND timeseries data
camels-extract 01031500 -o attributes.csv --timeseries

# Extract only timeseries data (skip static attributes)
camels-extract 01031500 -o forcing_data.csv --timeseries-only

# Include monthly aggregations in output
camels-extract 01031500 -o data.csv --timeseries --monthly

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

### Comprehensive Watershed Visualization (NEW!)

#### Python API

```python
from camels_attrs import CamelsExtractor

# Extract attributes
extractor = CamelsExtractor('01031500')
attributes = extractor.extract_all()

# Create comprehensive multi-panel watershed map
fig = extractor.create_comprehensive_map(
    save_path='watershed_comprehensive_map.png',
    show=True
)

# The map includes:
# - DEM elevation background with terrain colors
# - Watershed boundary (red) and stream network (blue)
# - Gauge location marker (yellow star)
# - USA context map showing watershed location
# - Statistics panel with all key attributes
# - Elevation profile bar chart
# - Land cover distribution pie chart
# - Climate water balance comparison
```

#### Standalone Visualization Function

```python
from camels_attrs import create_comprehensive_watershed_map

# Use the standalone function for custom workflows
fig = create_comprehensive_watershed_map(
    watershed_gdf=extractor.watershed_gdf,
    watershed_geom=extractor.watershed_geom,
    metadata=extractor.metadata,
    attributes=extractor.attributes,
    gauge_id='01031500',
    save_path='custom_map.png'
)
```

#### Visualization Features

- **6-Panel Dashboard** (20"×12" figure)
  - Large main map with DEM, streams, boundary
  - Location context (USA map)
  - Comprehensive statistics text panel
  - Elevation profile
  - Land cover pie chart
  - Climate water balance

- **Professional Elements**
  - Scale bar and north arrow
  - OpenStreetMap basemap overlay
  - High-DPI export (300 DPI)
  - Publication-ready styling

- **Use Cases**
  - Research papers and reports
  - Presentations and posters
  - Watershed characterization studies
  - Model setup documentation

### Advanced Usage Examples

#### Batch Processing Multiple Gauges

```python
from camels_attrs import extract_multiple_gauges

# Process multiple gauges
gauge_ids = ['01031500', '02177000', '06803530']
df = extract_multiple_gauges(gauge_ids)
df.to_csv('multiple_gauges_attributes.csv', index=False)
```

#### Custom PET Calculations

```python
# Extract timeseries with Hargreaves-Samani PET
extractor = CamelsExtractor('01031500')
forcing_data = extractor.extract_timeseries(
    '2020-01-01', '2020-12-31',
    include_hargreaves_pet=True
)
```

#### Climate Statistics from Timeseries

```python
from camels_attrs import calculate_forcing_statistics

# Calculate comprehensive climate statistics
stats = extractor.get_forcing_statistics(forcing_data)
print(f"Mean annual precipitation: {stats['mean_annual_precip_mm']:.1f} mm")
print(f"Aridity index: {stats['aridity_index']:.2f}")
```

## Hydrometeorological Timeseries Data

### Timeseries Variables

The package extracts daily hydrometeorological forcing data from GridMET:

| Variable | Description | Units | Source |
|----------|-------------|-------|--------|
| `date` | Date (YYYY-MM-DD) | - | - |
| `prcp_mm` | Daily precipitation | mm/day | GridMET |
| `tmin_C` | Minimum daily temperature | °C | GridMET |
| `tmax_C` | Maximum daily temperature | °C | GridMET |
| `tavg_C` | Average daily temperature | °C | Calculated |
| `srad_Wm2` | Shortwave solar radiation | W/m² | GridMET |
| `wind_ms` | Wind speed | m/s | GridMET |
| `sph_kgkg` | Specific humidity | kg/kg | GridMET |
| `pet_mm` | Potential evapotranspiration | mm/day | GridMET |
| `pet_hargreaves_mm` | PET (Hargreaves-Samani) | mm/day | Calculated |

### Timeseries Functions

#### Core Timeseries Functions

```python
from camels_attrs import (
    fetch_forcing_data,
    calculate_pet_hargreaves,
    get_monthly_summary,
    calculate_water_balance,
    calculate_forcing_statistics
)

# Fetch daily forcing data for a watershed
forcing_df = fetch_forcing_data(watershed_geometry, '2020-01-01', '2020-12-31')

# Calculate Hargreaves-Samani PET
forcing_with_hargreaves = calculate_pet_hargreaves(forcing_df, latitude)

# Get monthly aggregated statistics
monthly_stats = get_monthly_summary(forcing_df)

# Calculate annual water balance
water_balance = calculate_water_balance(forcing_df)

# Calculate comprehensive climate statistics
climate_stats = calculate_forcing_statistics(forcing_df)
```

#### Using the CamelsExtractor Class

```python
# Extract timeseries using the main extractor class
extractor = CamelsExtractor('01031500')

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

# Include Hargreaves-Samani PET calculation
forcing_data = extractor.extract_timeseries(
    '2020-01-01', '2020-12-31',
    include_hargreaves_pet=True
)

# Get climate statistics from timeseries
stats = extractor.get_forcing_statistics(forcing_data)
```

### Timeseries Applications

#### Hydrological Modeling Input

```python
# Prepare forcing data for hydrological models
forcing_data = extractor.extract_timeseries('2010-01-01', '2020-12-31')

# Calculate monthly aggregations for model spin-up
monthly_data = get_monthly_summary(forcing_data)

# Export in format suitable for models like SUMMA, VIC, or SWAT
monthly_data.to_csv('model_input_monthly.csv', index=False)
```

#### Climate Trend Analysis

```python
# Analyze long-term climate trends
forcing_data = fetch_forcing_data(watershed_geom, '2000-01-01', '2023-12-31')
stats = calculate_forcing_statistics(forcing_data)

# Calculate annual statistics
annual_precip = forcing_data.groupby(forcing_data['date'].dt.year)['prcp_mm'].sum()
annual_temp = forcing_data.groupby(forcing_data['date'].dt.year)['tavg_C'].mean()

# Trend analysis
print(f"Annual precipitation trend: {annual_precip.corr(range(len(annual_precip))):.3f}")
print(f"Annual temperature trend: {annual_temp.corr(range(len(annual_temp))):.3f}")
```

#### Water Balance Studies

```python
# Calculate catchment water balance
water_balance = calculate_water_balance(forcing_data)

print("Annual Water Balance:")
print(water_balance[['prcp_mm', 'pet_mm', 'water_surplus_mm']])

# Calculate aridity trends
aridity_trend = water_balance['aridity_index'].corr(range(len(water_balance)))
print(f"Aridity trend: {aridity_trend:.3f}")
```

## Extracted Attributes

The package extracts 70+ static attributes organized into categories:

### Metadata
- `gauge_id`, `gauge_name`, `gauge_lat`, `gauge_lon`, `huc_02`

### Topography
- `elev_mean`, `elev_min`, `elev_max`, `elev_std`
- `slope_mean`, `slope_std`
- `area_geospa_fabric`

### Climate (customizable date range)
- `p_mean`, `pet_mean`, `temp_mean`
- `aridity`, `p_seasonality`, `temp_seasonality`
- `frac_snow`
- `high_prec_freq`, `high_prec_dur`, `high_prec_timing`
- `low_prec_freq`, `low_prec_dur`, `low_prec_timing`

### Soil
- `soil_porosity`, `soil_depth_statsgo`, `max_water_content`
- `sand_frac`, `silt_frac`, `clay_frac`
- `soil_conductivity`

### Vegetation
- `lai_max`, `lai_min`, `lai_diff`
- `gvf_max`, `gvf_diff`, `gvf_mean`
- `frac_forest`, `frac_cropland`, `water_frac`
- `dom_land_cover`, `dom_land_cover_frac`
- `root_depth_50`, `root_depth_99`

### Geology
- `geol_1st_class`, `geol_2nd_class`
- `glim_1st_class_frac`, `glim_2nd_class_frac`
- `carbonate_rocks_frac`
- `geol_permeability`, `geol_porostiy`

### Hydrology (customizable date range)
- `q_mean`, `q_std`, `q5`, `q95`, `q_median`
- `baseflow_index`, `runoff_ratio`, `stream_elas`
- `slope_fdc`, `flow_variability`
- `high_q_freq`, `high_q_dur`
- `low_q_freq`, `low_q_dur`
- `zero_q_freq`
- `hfd_mean`, `half_flow_date_std`

## Requirements

- Python >=3.8
- numpy, pandas, geopandas
- xarray, rioxarray, rasterio
- pynhd, py3dep, pygridmet, pygeohydro
- pygeoglim, planetary-computer
- scipy, matplotlib

See `pyproject.toml` for complete dependency list.

## Data Sources

- **Watershed boundaries**: USGS NLDI
- **Topography**: USGS 3DEP
- **Climate**: GridMET
- **Soil**: gNATSGO, POLARIS
- **Vegetation**: MODIS (LAI, NDVI), NLCD
- **Geology**: GLiM, GLHYMPS
- **Streamflow**: USGS NWIS

## References

This package implements the methodology described in:

- 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

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.

## 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. Lyles School of Civil Engineering, Purdue University.
```

## Contact

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

## Acknowledgments

We acknowledge the support and resources provided by Purdue University and the hydrological research community.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "camels-attrs",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "Mohammad Galib <mgalib@purdue.edu>",
    "keywords": "hydrology, CAMELS, catchment, watershed, USGS, attributes",
    "author": null,
    "author_email": "Mohammad Galib <mgalib@purdue.edu>",
    "download_url": "https://files.pythonhosted.org/packages/14/f1/2f9c6ba331dfedd9e7ca0e5381709f04705f006a8eb9556a8f4f55bd89e4/camels_attrs-1.0.1.tar.gz",
    "platform": null,
    "description": "# CAMELS Attrs\n\n![CAMELS Attrs](assets/thumbnail.png)\n\n[![PyPI version](https://badge.fury.io/py/camels-attrs.svg)](https://pypi.org/project/camels-attrs/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n[![Downloads](https://static.pepy.tech/badge/camels-attrs)](https://pepy.tech/project/camels-attrs)\n\nA Python package for extracting CAMELS-like catchment attributes for any USGS gauge site in the United States.\n\n## Overview\n\nThis package provides a simple, reproducible way to extract comprehensive catchment attributes following the CAMELS (Catchment Attributes and Meteorology for Large-sample Studies) methodology. It automates the extraction of topographic, climatic, soil, vegetation, geological, and hydrological characteristics for any USGS-monitored watershed.\nAdditionally, it can fetch daily hydrometeorological forcing data (precipitation, temperature, solar radiation, wind speed, humidity) from the GridMET dataset for user-defined date ranges. The package also includes a new feature to create a comprehensive multi-panel watershed map that visualizes key attributes and spatial context.\n\n## Features\n\n### Static Catchment Attributes\n- **Watershed Delineation**: Automated watershed boundary extraction using NLDI\n- **Topographic Attributes**: Elevation, slope, and drainage area from 3DEP DEM\n- **Climate Indices**: Precipitation, temperature, aridity, seasonality from GridMET\n- **Soil Characteristics**: Texture, porosity, conductivity from gNATSGO and POLARIS\n- **Vegetation Metrics**: LAI, NDVI/GVF, land cover from MODIS and NLCD\n- **Geological Properties**: Lithology and permeability from GLiM and GLHYMPS\n- **Hydrological Signatures**: Flow statistics, baseflow index, event characteristics\n\n### Hydrometeorological Timeseries Data\n- **Daily Forcing Data**: Precipitation, temperature (min/max/avg), solar radiation, wind speed, humidity\n- **PET Calculations**: GridMET PET and Hargreaves-Samani PET\n- **Monthly Aggregations**: Automatically compute monthly statistics\n- **Water Balance**: Calculate annual water surplus and aridity indices\n\n### Comprehensive Watershed Visualization (NEW!)\n- **Multi-Panel Dashboard**: 20\"\u00d712\" publication-ready watershed maps\n- **DEM Elevation Background**: High-resolution terrain visualization\n- **Stream Network Overlay**: NLDI-derived drainage network\n- **Location Context**: USA map showing watershed location\n- **Statistics Panel**: All key attributes displayed (topography, climate, vegetation, hydrology)\n- **Analytical Charts**: Elevation profile, land cover pie chart, water balance comparison\n- **Cartographic Elements**: Scale bar, north arrow, proper projections\n- **Export Options**: High-DPI PNG/PDF for publications\n\n## Installation\n\n```bash\npip install camels-attrs\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/galib9690/camels-attrs.git\ncd camels-attrs\npip install -e .\n```\n\n### Optional Dependencies\n\nFor geological attribute extraction (GLiM, GLHYMPS), you may need to install `pygeoglim` separately if it's not available on PyPI:\n\n```bash\npip install git+https://github.com/galib9690/pygeoglim.git\n```\n\nIf `pygeoglim` is not installed, the package will still work but will return default values for geological attributes.\n\n## Quick Start\n\n### Static Attributes Extraction\n\n#### Python API\n\n```python\nfrom camels_attrs import CamelsExtractor\n\n# Extract static attributes for a single gauge\nextractor = CamelsExtractor('01031500')  # USGS gauge ID\nattributes = extractor.extract_all()\n\n# Save to CSV\nextractor.save('attributes.csv')\n\n# Or get as DataFrame\ndf = extractor.to_dataframe()\n```\n\n#### Command Line Interface\n\n```bash\n# Extract static attributes only\ncamels-extract 01031500 -o attributes.csv\n\n# Multiple gauges\ncamels-extract 01031500 02177000 06803530 -o combined.csv\n\n# Custom date ranges for hydrological signatures\ncamels-extract 01031500 --hydro-start 2010-01-01 --hydro-end 2020-12-31\n```\n\n### Hydrometeorological Timeseries Data\n\n#### Python API\n\n```python\nfrom camels_attrs import CamelsExtractor, fetch_forcing_data, get_monthly_summary\n\n# Extract timeseries data using the extractor class\nextractor = CamelsExtractor('01031500')\nforcing_data = extractor.extract_timeseries('2020-01-01', '2020-12-31')\n\n# Or use standalone functions\nforcing_data = fetch_forcing_data(watershed_geometry, '2020-01-01', '2020-12-31')\n\n# Calculate monthly aggregations\nmonthly_data = get_monthly_summary(forcing_data)\n\n# Calculate water balance\nfrom camels_attrs import calculate_water_balance\nwater_balance = calculate_water_balance(forcing_data)\n```\n\n#### Command Line Interface\n\n```bash\n# Extract both static attributes AND timeseries data\ncamels-extract 01031500 -o attributes.csv --timeseries\n\n# Extract only timeseries data (skip static attributes)\ncamels-extract 01031500 -o forcing_data.csv --timeseries-only\n\n# Include monthly aggregations in output\ncamels-extract 01031500 -o data.csv --timeseries --monthly\n\n# Custom date ranges for timeseries\ncamels-extract 01031500 --climate-start 2010-01-01 --climate-end 2020-12-31 --timeseries\n```\n\n### Comprehensive Watershed Visualization (NEW!)\n\n#### Python API\n\n```python\nfrom camels_attrs import CamelsExtractor\n\n# Extract attributes\nextractor = CamelsExtractor('01031500')\nattributes = extractor.extract_all()\n\n# Create comprehensive multi-panel watershed map\nfig = extractor.create_comprehensive_map(\n    save_path='watershed_comprehensive_map.png',\n    show=True\n)\n\n# The map includes:\n# - DEM elevation background with terrain colors\n# - Watershed boundary (red) and stream network (blue)\n# - Gauge location marker (yellow star)\n# - USA context map showing watershed location\n# - Statistics panel with all key attributes\n# - Elevation profile bar chart\n# - Land cover distribution pie chart\n# - Climate water balance comparison\n```\n\n#### Standalone Visualization Function\n\n```python\nfrom camels_attrs import create_comprehensive_watershed_map\n\n# Use the standalone function for custom workflows\nfig = create_comprehensive_watershed_map(\n    watershed_gdf=extractor.watershed_gdf,\n    watershed_geom=extractor.watershed_geom,\n    metadata=extractor.metadata,\n    attributes=extractor.attributes,\n    gauge_id='01031500',\n    save_path='custom_map.png'\n)\n```\n\n#### Visualization Features\n\n- **6-Panel Dashboard** (20\"\u00d712\" figure)\n  - Large main map with DEM, streams, boundary\n  - Location context (USA map)\n  - Comprehensive statistics text panel\n  - Elevation profile\n  - Land cover pie chart\n  - Climate water balance\n\n- **Professional Elements**\n  - Scale bar and north arrow\n  - OpenStreetMap basemap overlay\n  - High-DPI export (300 DPI)\n  - Publication-ready styling\n\n- **Use Cases**\n  - Research papers and reports\n  - Presentations and posters\n  - Watershed characterization studies\n  - Model setup documentation\n\n### Advanced Usage Examples\n\n#### Batch Processing Multiple Gauges\n\n```python\nfrom camels_attrs import extract_multiple_gauges\n\n# Process multiple gauges\ngauge_ids = ['01031500', '02177000', '06803530']\ndf = extract_multiple_gauges(gauge_ids)\ndf.to_csv('multiple_gauges_attributes.csv', index=False)\n```\n\n#### Custom PET Calculations\n\n```python\n# Extract timeseries with Hargreaves-Samani PET\nextractor = CamelsExtractor('01031500')\nforcing_data = extractor.extract_timeseries(\n    '2020-01-01', '2020-12-31',\n    include_hargreaves_pet=True\n)\n```\n\n#### Climate Statistics from Timeseries\n\n```python\nfrom camels_attrs import calculate_forcing_statistics\n\n# Calculate comprehensive climate statistics\nstats = extractor.get_forcing_statistics(forcing_data)\nprint(f\"Mean annual precipitation: {stats['mean_annual_precip_mm']:.1f} mm\")\nprint(f\"Aridity index: {stats['aridity_index']:.2f}\")\n```\n\n## Hydrometeorological Timeseries Data\n\n### Timeseries Variables\n\nThe package extracts daily hydrometeorological forcing data from GridMET:\n\n| Variable | Description | Units | Source |\n|----------|-------------|-------|--------|\n| `date` | Date (YYYY-MM-DD) | - | - |\n| `prcp_mm` | Daily precipitation | mm/day | GridMET |\n| `tmin_C` | Minimum daily temperature | \u00b0C | GridMET |\n| `tmax_C` | Maximum daily temperature | \u00b0C | GridMET |\n| `tavg_C` | Average daily temperature | \u00b0C | Calculated |\n| `srad_Wm2` | Shortwave solar radiation | W/m\u00b2 | GridMET |\n| `wind_ms` | Wind speed | m/s | GridMET |\n| `sph_kgkg` | Specific humidity | kg/kg | GridMET |\n| `pet_mm` | Potential evapotranspiration | mm/day | GridMET |\n| `pet_hargreaves_mm` | PET (Hargreaves-Samani) | mm/day | Calculated |\n\n### Timeseries Functions\n\n#### Core Timeseries Functions\n\n```python\nfrom camels_attrs import (\n    fetch_forcing_data,\n    calculate_pet_hargreaves,\n    get_monthly_summary,\n    calculate_water_balance,\n    calculate_forcing_statistics\n)\n\n# Fetch daily forcing data for a watershed\nforcing_df = fetch_forcing_data(watershed_geometry, '2020-01-01', '2020-12-31')\n\n# Calculate Hargreaves-Samani PET\nforcing_with_hargreaves = calculate_pet_hargreaves(forcing_df, latitude)\n\n# Get monthly aggregated statistics\nmonthly_stats = get_monthly_summary(forcing_df)\n\n# Calculate annual water balance\nwater_balance = calculate_water_balance(forcing_df)\n\n# Calculate comprehensive climate statistics\nclimate_stats = calculate_forcing_statistics(forcing_df)\n```\n\n#### Using the CamelsExtractor Class\n\n```python\n# Extract timeseries using the main extractor class\nextractor = CamelsExtractor('01031500')\n\n# Extract timeseries data\nforcing_data = extractor.extract_timeseries('2020-01-01', '2020-12-31')\n\n# Include Hargreaves-Samani PET calculation\nforcing_data = extractor.extract_timeseries(\n    '2020-01-01', '2020-12-31',\n    include_hargreaves_pet=True\n)\n\n# Get climate statistics from timeseries\nstats = extractor.get_forcing_statistics(forcing_data)\n```\n\n### Timeseries Applications\n\n#### Hydrological Modeling Input\n\n```python\n# Prepare forcing data for hydrological models\nforcing_data = extractor.extract_timeseries('2010-01-01', '2020-12-31')\n\n# Calculate monthly aggregations for model spin-up\nmonthly_data = get_monthly_summary(forcing_data)\n\n# Export in format suitable for models like SUMMA, VIC, or SWAT\nmonthly_data.to_csv('model_input_monthly.csv', index=False)\n```\n\n#### Climate Trend Analysis\n\n```python\n# Analyze long-term climate trends\nforcing_data = fetch_forcing_data(watershed_geom, '2000-01-01', '2023-12-31')\nstats = calculate_forcing_statistics(forcing_data)\n\n# Calculate annual statistics\nannual_precip = forcing_data.groupby(forcing_data['date'].dt.year)['prcp_mm'].sum()\nannual_temp = forcing_data.groupby(forcing_data['date'].dt.year)['tavg_C'].mean()\n\n# Trend analysis\nprint(f\"Annual precipitation trend: {annual_precip.corr(range(len(annual_precip))):.3f}\")\nprint(f\"Annual temperature trend: {annual_temp.corr(range(len(annual_temp))):.3f}\")\n```\n\n#### Water Balance Studies\n\n```python\n# Calculate catchment water balance\nwater_balance = calculate_water_balance(forcing_data)\n\nprint(\"Annual Water Balance:\")\nprint(water_balance[['prcp_mm', 'pet_mm', 'water_surplus_mm']])\n\n# Calculate aridity trends\naridity_trend = water_balance['aridity_index'].corr(range(len(water_balance)))\nprint(f\"Aridity trend: {aridity_trend:.3f}\")\n```\n\n## Extracted Attributes\n\nThe package extracts 70+ static attributes organized into categories:\n\n### Metadata\n- `gauge_id`, `gauge_name`, `gauge_lat`, `gauge_lon`, `huc_02`\n\n### Topography\n- `elev_mean`, `elev_min`, `elev_max`, `elev_std`\n- `slope_mean`, `slope_std`\n- `area_geospa_fabric`\n\n### Climate (customizable date range)\n- `p_mean`, `pet_mean`, `temp_mean`\n- `aridity`, `p_seasonality`, `temp_seasonality`\n- `frac_snow`\n- `high_prec_freq`, `high_prec_dur`, `high_prec_timing`\n- `low_prec_freq`, `low_prec_dur`, `low_prec_timing`\n\n### Soil\n- `soil_porosity`, `soil_depth_statsgo`, `max_water_content`\n- `sand_frac`, `silt_frac`, `clay_frac`\n- `soil_conductivity`\n\n### Vegetation\n- `lai_max`, `lai_min`, `lai_diff`\n- `gvf_max`, `gvf_diff`, `gvf_mean`\n- `frac_forest`, `frac_cropland`, `water_frac`\n- `dom_land_cover`, `dom_land_cover_frac`\n- `root_depth_50`, `root_depth_99`\n\n### Geology\n- `geol_1st_class`, `geol_2nd_class`\n- `glim_1st_class_frac`, `glim_2nd_class_frac`\n- `carbonate_rocks_frac`\n- `geol_permeability`, `geol_porostiy`\n\n### Hydrology (customizable date range)\n- `q_mean`, `q_std`, `q5`, `q95`, `q_median`\n- `baseflow_index`, `runoff_ratio`, `stream_elas`\n- `slope_fdc`, `flow_variability`\n- `high_q_freq`, `high_q_dur`\n- `low_q_freq`, `low_q_dur`\n- `zero_q_freq`\n- `hfd_mean`, `half_flow_date_std`\n\n## Requirements\n\n- Python >=3.8\n- numpy, pandas, geopandas\n- xarray, rioxarray, rasterio\n- pynhd, py3dep, pygridmet, pygeohydro\n- pygeoglim, planetary-computer\n- scipy, matplotlib\n\nSee `pyproject.toml` for complete dependency list.\n\n## Data Sources\n\n- **Watershed boundaries**: USGS NLDI\n- **Topography**: USGS 3DEP\n- **Climate**: GridMET\n- **Soil**: gNATSGO, POLARIS\n- **Vegetation**: MODIS (LAI, NDVI), NLCD\n- **Geology**: GLiM, GLHYMPS\n- **Streamflow**: USGS NWIS\n\n## References\n\nThis package implements the methodology described in:\n\n- Newman et al. (2015). Development of a large-sample watershed-scale hydrometeorological dataset. NCAR Technical Note\n- Addor et al. (2017). The CAMELS data set: catchment attributes and meteorology for large-sample studies. Hydrology and Earth System Sciences\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Citation\n\nIf you use this package in your research, please cite:\n\n```\nGalib, M. & Merwade, V. (2025). camels-attrs: A Python package for extracting \nCAMELS-like catchment attributes. Lyles School of Civil Engineering, Purdue University.\n```\n\n## Contact\n\nMohammad Galib - mgalib@purdue.edu  \nVenkatesh Merwade - vmerwade@purdue.edu\n\n## Acknowledgments\n\nWe acknowledge the support and resources provided by Purdue University and the hydrological research community.\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Extract CAMELS-like catchment attributes for any USGS gauge site in the USA",
    "version": "1.0.1",
    "project_urls": {
        "Bug Tracker": "https://github.com/galib9690/camels-attrs/issues",
        "Documentation": "https://github.com/galib9690/camels-attrs/blob/main/README.md",
        "Homepage": "https://github.com/galib9690/camels-attrs",
        "Repository": "https://github.com/galib9690/camels-attrs.git"
    },
    "split_keywords": [
        "hydrology",
        " camels",
        " catchment",
        " watershed",
        " usgs",
        " attributes"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "d93b5a37f44de2c492d8c4b710d93a959bbeeb6e5d257ed8da9fc002367418ae",
                "md5": "dbe7e1c5f95a413cd0ecca9c5d85ea45",
                "sha256": "573cd2a1597c0799957c2883a6175eff5db6170a88a35214195cd6d7bf2481af"
            },
            "downloads": -1,
            "filename": "camels_attrs-1.0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "dbe7e1c5f95a413cd0ecca9c5d85ea45",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 34283,
            "upload_time": "2025-10-10T15:34:43",
            "upload_time_iso_8601": "2025-10-10T15:34:43.510631Z",
            "url": "https://files.pythonhosted.org/packages/d9/3b/5a37f44de2c492d8c4b710d93a959bbeeb6e5d257ed8da9fc002367418ae/camels_attrs-1.0.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "14f12f9c6ba331dfedd9e7ca0e5381709f04705f006a8eb9556a8f4f55bd89e4",
                "md5": "871df9ca311fc42e2e6a6566d8afd2da",
                "sha256": "980fe12d7ede87fd3879964e7aefbfd3a30c4c15c7f8a51352a7486cc81e4586"
            },
            "downloads": -1,
            "filename": "camels_attrs-1.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "871df9ca311fc42e2e6a6566d8afd2da",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 33288,
            "upload_time": "2025-10-10T15:34:44",
            "upload_time_iso_8601": "2025-10-10T15:34:44.376420Z",
            "url": "https://files.pythonhosted.org/packages/14/f1/2f9c6ba331dfedd9e7ca0e5381709f04705f006a8eb9556a8f4f55bd89e4/camels_attrs-1.0.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-10 15:34:44",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "galib9690",
    "github_project": "camels-attrs",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "camels-attrs"
}