Metadata-Version: 2.4
Name: hydroanomaly
Version: 0.7.3
Summary: A Python package for hydro anomaly detection with simple USGS data retrieval
Author-email: Ehsan Kahrizi <ehsan.kahrizi@usu.edu>
License: MIT License
        
        Copyright (c) 2025 Your Name
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/yourusername/hydroanomaly
Project-URL: Bug Reports, https://github.com/yourusername/hydroanomaly/issues
Project-URL: Source, https://github.com/yourusername/hydroanomaly
Keywords: python,package,hydro,anomaly,detection
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: requests>=2.25.1
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: earthengine-api>=0.1.300
Requires-Dist: geemap>=0.20.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Dynamic: license-file

# 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! 🌊📊
