# HydroAnomaly

A Python package for hydro anomaly detection, **USGS water data retrieval**, and **time series visualization**.

[![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)

## Features

- 🌊 **USGS Data Retrieval**: Get real-time and historical water data from USGS Water Services
- 📊 **Time Series Plotting**: Beautiful, professional visualizations for your water data
- 📈 **Multi-Parameter Analysis**: Compare multiple parameters or gages in one plot
- 📋 **Statistical Analysis**: Built-in statistics and distribution plots
- 🎯 **Easy to Use**: Simple functions for quick data exploration

## Installation

```bash
pip install hydroanomaly
```

## � 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())
```

## 📊 Time Series Plotting

Create beautiful visualizations of your water data:

```python
import hydroanomaly

# Get some data
data = hydroanomaly.get_discharge("08158000", "2023-01-01", "2023-01-31")

# Quick plot (simplest method)
hydroanomaly.quick_plot(data, "Colorado River Discharge")

# Professional plot with statistics
fig = hydroanomaly.plot_usgs_data(
    data=data,
    parameter_name="Discharge (cfs)",
    title="Colorado River at Austin - January 2023",
    save_path="discharge_plot.png"
)

# Compare multiple gages
austin_data = hydroanomaly.get_discharge("08158000", "2023-01-01", "2023-01-07")
nola_data = hydroanomaly.get_discharge("07374000", "2023-01-01", "2023-01-07")

gage_data = {
    "Colorado River (Austin)": austin_data,
    "Mississippi River (New Orleans)": nola_data
}

fig = hydroanomaly.plot_multiple_gages(
    data_dict=gage_data,
    parameter_name="Discharge (cfs)",
    title="River Discharge Comparison"
)
```

## Quick Start

```python
import hydroanomaly

# Get USGS data
data = hydroanomaly.get_discharge("08158000", "2023-01-01", "2023-01-31")
print(f"Retrieved {len(data)} discharge measurements")

# Plot the data
hydroanomaly.quick_plot(data, "Colorado River Discharge")

# 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
```

## 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
  - Convenient functions for common parameters (discharge, water level, temperature)
  - Fallback synthetic data generation
  - CSV export functionality

- **📊 Time Series Plotting**: Beautiful, professional visualizations
  - Single parameter plots with statistics
  - Multi-parameter comparison plots
  - Multiple gage comparison plots
  - Statistical analysis plots (histogram, box plot, etc.)
  - Automatic legend and formatting
  - Save plots in multiple formats (PNG, PDF, SVG)

- **📈 Data Analysis Tools**: Built-in utilities for water data
  - Mathematical operations for data processing
  - Statistical summaries and analysis
  - Data validation and quality checks

- **🎯 Easy to Use**: Simple, intuitive API
  - Quick plotting for rapid data exploration
  - One-line data retrieval functions
  - Comprehensive error handling
  - Well-documented with examples

- **🧪 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}")
```

### Time Series Plotting

```python
# Quick plotting for data exploration
data = hydroanomaly.get_discharge("08158000", "2023-01-01", "2023-01-07")
hydroanomaly.quick_plot(data, "Quick Discharge Check")

# Professional plots with full customization
from hydroanomaly.plotting import WaterDataPlotter

plotter = WaterDataPlotter()

# Single parameter with statistics
fig = plotter.plot_timeseries(
    data=data,
    parameter_name="Discharge (cfs)",
    title="Colorado River Discharge",
    color="blue",
    save_path="discharge_analysis.png"
)

# Multiple parameters from same gage
discharge = hydroanomaly.get_discharge("08158000", "2023-01-01", "2023-01-07")
level = hydroanomaly.get_water_level("08158000", "2023-01-01", "2023-01-07")

data_dict = {
    "Discharge (cfs)": discharge,
    "Water Level (ft)": level
}

fig = plotter.plot_multiple_parameters(
    data_dict=data_dict,
    title="Colorado River - Multiple Parameters"
)

# Statistical analysis plots
fig = plotter.plot_statistics(
    data=data,
    parameter_name="Discharge (cfs)",
    title="Discharge Statistics"
)
```

## 📚 Documentation & Examples

- **📖 [Plotting Guide](PLOTTING_GUIDE.md)**: Comprehensive plotting documentation with examples
- **🎯 [Examples](plotting_examples.py)**: Run `python plotting_examples.py` to see all features
- **🧪 [Tests](test_plotting.py)**: Verify functionality with `python test_plotting.py`

## Use Cases

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

## 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.get_discharge(gage_number, start_date, end_date)
Get discharge data from USGS.

**Parameters:**
- `gage_number` (str): USGS gage number
- `start_date` (str): Start date (YYYY-MM-DD)
- `end_date` (str): End date (YYYY-MM-DD)

**Returns:**
- pandas.DataFrame: Time series data with datetime and value columns

### hydroanomaly.get_water_level(gage_number, start_date, end_date)
Get water level data from USGS.

**Parameters:**
- `gage_number` (str): USGS gage number
- `start_date` (str): Start date (YYYY-MM-DD)
- `end_date` (str): End date (YYYY-MM-DD)

**Returns:**
- pandas.DataFrame: Time series data with datetime and value columns

### hydroanomaly.plot_usgs_data(data, parameter_name, title, save_path, color)
Create a professional plot of USGS time series data.

**Parameters:**
- `data` (DataFrame): USGS data with datetime and value columns
- `parameter_name` (str, optional): Name of parameter for y-axis label
- `title` (str, optional): Plot title
- `save_path` (str, optional): Path to save the plot
- `color` (str, optional): Line color

**Returns:**
- matplotlib.figure.Figure: The plot figure

### hydroanomaly.quick_plot(data, title)
Create a quick plot for data exploration.

**Parameters:**
- `data` (DataFrame): USGS data with datetime and value columns
- `title` (str, optional): Plot title

**Returns:**
- matplotlib.figure.Figure: The plot figure

### hydroanomaly.plot_multiple_gages(data_dict, parameter_name, title, save_path)
Compare the same parameter across multiple gages.

**Parameters:**
- `data_dict` (dict): Dictionary with gage names as keys and data as values
- `parameter_name` (str, optional): Name of parameter for y-axis label
- `title` (str, optional): Plot title
- `save_path` (str, optional): Path to save the plot

**Returns:**
- matplotlib.figure.Figure: The plot figure

### Mathematical Operations

### 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

## 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.

---

**HydroAnomaly** - Making water data analysis simple and beautiful! 🌊📊
