# HydroAnomaly

A Python package for hydro anomaly detection and **USGS water data retrieval**.

[![PyPI version](https://badge.fury.io/py/hydroanomaly.svg)](https://badge.fury.io/py/hydroanomaly)
[![Downloads](https://pepy.tech/badge/hydroanomaly)](https://pepy.tech/project/hydroanomaly)

## Installation

```bash
pip install hydroanomaly
```

## 🆕 New Feature: USGS Data Retrieval

Easily retrieve real-time and historical water data from USGS Water Services:

```python
import hydroanomaly

# ------------------------
# User-defined settings
# ------------------------
site_number = "294643095035200"   # USGS site number
parameter_code = "63680"          # Turbidity
start_date = "2020-01-01"
end_date = "2024-12-30"

# ------------------------
# Data Extraction from USGS
# ------------------------
data = hydroanomaly.get_usgs_data(
    site_number=site_number,
    parameter_code=parameter_code,
    start_date=start_date,
    end_date=end_date,
    save_to_file="USGS_turbidity.csv",
    parameter_name="Turbidity"
)

print(f"Retrieved {len(data)} data points!")
print(data.head())
```

## Quick Start

```python
import hydroanomaly

# Basic greeting functionality
print(hydroanomaly.greet("Water Engineer"))
# Output: Hello, Water Engineer!

# Math utilities for data analysis
result = hydroanomaly.add(25.5, 14.3)
print(f"Sum: {result}")
# Output: Sum: 39.8

# USGS data retrieval
data = hydroanomaly.get_usgs_data("08158000", "00060", "2023-01-01", "2023-01-31")
print(f"Retrieved {len(data)} discharge measurements")
```

## Features

- **🌊 USGS Data Retrieval**: Download real-time water data from USGS Water Services
  - Support for any USGS site and parameter
  - Automatic data cleaning and validation
  - Fallback synthetic data generation
  - CSV export functionality
- **Greeting Module**: Simple greeting functionality for applications
- **Math Utilities**: Basic mathematical operations for data processing
  - Addition and multiplication functions
  - Division with error handling
- **Error Handling**: Robust error handling for mathematical operations
- **Well Tested**: Comprehensive test suite with 100% pass rate

## USGS Data Parameters

Common USGS parameter codes you can use:
- **00060**: Discharge (cubic feet per second)
- **00065**: Gage height (feet) 
- **00010**: Water temperature (°C)
- **63680**: Turbidity (NTU)
- **00300**: Dissolved oxygen (mg/L)
- **00095**: Specific conductance (µS/cm)

Find USGS site numbers at: https://waterdata.usgs.gov/nwis

## Detailed Usage

### USGS Data Retrieval
```python
from hydroanomaly.usgs_data import USGSDataRetriever

# Create retriever instance
retriever = USGSDataRetriever()

# Get data with full control
data = retriever.retrieve_data(
    site_number="08158000",       # Colorado River at Austin, TX
    parameter_code="00060",       # Discharge
    start_date="2023-01-01",
    end_date="2023-01-31"
)

# Get summary statistics
summary = retriever.get_data_summary(data)
print(f"Retrieved {summary['record_count']} records")
print(f"Average discharge: {summary['value_stats']['mean']:.2f} cfs")

# Save data
retriever.save_data(data, "discharge_data.csv", "Discharge_cfs")
```

### Greeting Functions
```python
from hydroanomaly.hello import greet, say_goodbye

# Greet users
welcome_msg = greet("Data Scientist")
print(welcome_msg)  # Hello, Data Scientist!

# Say goodbye
farewell_msg = say_goodbye("User")
print(farewell_msg)  # Goodbye, User!
```

### Mathematical Operations
```python
from hydroanomaly.math_utils import add, multiply, divide

# Basic operations
sum_result = add(10.5, 20.3)
product = multiply(5, 7)

# Safe division with error handling
try:
    result = divide(100, 5)
    print(f"Result: {result}")  # Result: 20.0
except ValueError as e:
    print(f"Error: {e}")
```

## Use Cases

- **🌊 Real Water Data Analysis**: Retrieve and analyze actual USGS water monitoring data
- **📊 Hydro Research**: Access historical water quality and quantity data
- **🚰 Water Management**: Monitor discharge, water levels, and quality parameters
- **🎓 Educational Projects**: Learn data analysis with real environmental data
- **🔬 Environmental Studies**: Research water patterns and anomalies
- **⚡ Quick Prototyping**: Rapidly access water data for proof-of-concepts

## API Reference

### hydroanomaly.greet(name="World")
Returns a greeting message.

**Parameters:**
- `name` (str, optional): Name to greet. Defaults to "World".

**Returns:**
- str: Greeting message

### hydroanomaly.add(a, b)
Adds two numbers.

**Parameters:**
- `a` (int/float): First number
- `b` (int/float): Second number

**Returns:**
- int/float: Sum of a and b

### hydroanomaly.multiply(a, b)
Multiplies two numbers.

**Parameters:**
- `a` (int/float): First number
- `b` (int/float): Second number

**Returns:**
- int/float: Product of a and b

## Features

- Feature 1
- Feature 2
- Feature 3

## Contributing

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

## License

This project is licensed under the MIT License - see the LICENSE file for details.
