Metadata-Version: 2.4
Name: pygeoglim
Version: 1.0.0
Summary: Fast access to GLiM and GLHYMPS geology attributes for watersheds
Author: Mohammad Galib
Author-email: Mohammad Galib <mgalib@purdue.edu>
License: MIT
Project-URL: Homepage, https://github.com/galib9690/pygeoglim
Project-URL: Repository, https://github.com/galib9690/pygeoglim.git
Project-URL: Issues, https://github.com/galib9690/pygeoglim/issues
Project-URL: Documentation, https://github.com/galib9690/pygeoglim#readme
Keywords: geology,hydrology,watershed,GLiM,GLHYMPS,geospatial
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: geopandas>=0.12.0
Requires-Dist: shapely>=1.8.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# pygeoglim

Fast Python package for extracting **geology attributes** (GLiM lithology + GLHYMPS hydrogeology) from Hugging Face datasets for any watershed or region.

## 🚀 Performance

- **Individual watersheds**: 1-5 seconds ⚡
- **Regional analysis**: 10-30 seconds
- **Large areas**: 1-2 minutes
- **Direct from Hugging Face**: No local downloads needed

## 📦 Installation

### From PyPI (Recommended)
```bash
pip install pygeoglim
```

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

### For Development
```bash
git clone https://github.com/galib9690/pygeoglim.git
cd pygeoglim
pip install -e .
```

## 🔧 Quick Start

```python
from pygeoglim import load_geometry, glim_attributes, glhymps_attributes

# Example 1: Using bounding box
geom = load_geometry(bbox=[-85.5, 39.5, -85.0, 40.0])

# Get GLiM lithology attributes
glim_attrs = glim_attributes(geom)
print("GLiM attributes:", glim_attrs)

# Get GLHYMPS hydrogeology attributes  
glhymps_attrs = glhymps_attributes(geom)
print("GLHYMPS attributes:", glhymps_attrs)

# Example 2: Using shapefile
geom = load_geometry(shapefile="path/to/watershed.shp")
attrs = {**glim_attributes(geom), **glhymps_attributes(geom)}
```

## 📊 Output Attributes

### GLiM Lithology
- `geol_1st_class`: Dominant lithology class
- `glim_1st_class_frac`: Fraction of dominant class
- `geol_2nd_class`: Second most common class
- `glim_2nd_class_frac`: Fraction of second class
- `carbonate_rocks_frac`: Fraction of carbonate rocks

### GLHYMPS Hydrogeology
- `geol_permeability`: Area-weighted permeability (m²)
- `geol_porosity`: Area-weighted porosity (fraction)

## 🌍 Data Sources

- **GLiM**: Global Lithological Map from Hugging Face Hub
- **GLHYMPS**: Global Hydrogeology Maps from Hugging Face Hub (Parquet format)
- **Coverage**: Continental United States (CONUS)

## 🔄 Recent Updates

- ✅ Reverted to reliable .gpkg format for GLHYMPS data
- ✅ Simplified data loading with direct mask-based filtering
- ✅ Updated column mappings for actual dataset structure (`logK_Ice_x`, `Porosity_x`)
- ✅ Streamlined error handling

## 📋 Requirements

- Python >= 3.8
- geopandas >= 0.12.0
- shapely >= 1.8.0
- numpy >= 1.20.0
- pandas >= 1.3.0

## 🐛 Troubleshooting

If you encounter issues with GLHYMPS data loading, the package includes automatic fallback mechanisms and error reporting to help diagnose problems.
