hydroanomaly 0.5.0

A Python package for hydro anomaly detection with simple USGS data retrieval

HydroAnomaly

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

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

pip install hydroanomaly

� USGS Data Retrieval

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

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:

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

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

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

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

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

# 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: Comprehensive plotting documentation with examples
• 🎯 Examples: Run python plotting_examples.py to see all features
• 🧪 Tests: 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! 🌊📊