hydroanomaly 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

hydroanomaly/__init__.py

@@ -12,5 +12,83 @@ __email__ = "your.email@example.com"
 from .hello import greet
 from .math_utils import add, multiply
 from .usgs_data import get_usgs_data, USGSDataRetriever
+from .plotting import plot_usgs_data, plot_multiple_gages, quick_plot, WaterDataPlotter
 
-__all__ = ["greet", "add", "multiply", "get_usgs_data", "USGSDataRetriever"]
+# Convenience functions for common use cases
+def get_discharge(gage_number, start_date, end_date, save_file=None):
+    """
+    Quick function to get discharge data from any USGS gage.
+    
+    Args:
+        gage_number (str): USGS gage number (e.g., "08158000")
+        start_date (str): Start date in YYYY-MM-DD format
+        end_date (str): End date in YYYY-MM-DD format
+        save_file (str, optional): Filename to save data
+    
+    Returns:
+        pandas.DataFrame: Discharge data
+        
+    Example:
+        >>> import hydroanomaly
+        >>> data = hydroanomaly.get_discharge("08158000", "2023-01-01", "2023-01-31")
+        >>> print(f"Got {len(data)} discharge measurements")
+    """
+    return get_usgs_data(
+        site_number=gage_number,
+        parameter_code="00060",  # Discharge
+        start_date=start_date,
+        end_date=end_date,
+        save_to_file=save_file,
+        parameter_name="Discharge_cfs"
+    )
+
+def get_water_level(gage_number, start_date, end_date, save_file=None):
+    """
+    Quick function to get water level data from any USGS gage.
+    
+    Args:
+        gage_number (str): USGS gage number (e.g., "08158000")
+        start_date (str): Start date in YYYY-MM-DD format
+        end_date (str): End date in YYYY-MM-DD format
+        save_file (str, optional): Filename to save data
+    
+    Returns:
+        pandas.DataFrame: Water level data
+    """
+    return get_usgs_data(
+        site_number=gage_number,
+        parameter_code="00065",  # Gage height
+        start_date=start_date,
+        end_date=end_date,
+        save_to_file=save_file,
+        parameter_name="WaterLevel_ft"
+    )
+
+def get_temperature(gage_number, start_date, end_date, save_file=None):
+    """
+    Quick function to get water temperature data from any USGS gage.
+    
+    Args:
+        gage_number (str): USGS gage number (e.g., "08158000")
+        start_date (str): Start date in YYYY-MM-DD format
+        end_date (str): End date in YYYY-MM-DD format
+        save_file (str, optional): Filename to save data
+    
+    Returns:
+        pandas.DataFrame: Temperature data
+    """
+    return get_usgs_data(
+        site_number=gage_number,
+        parameter_code="00010",  # Temperature
+        start_date=start_date,
+        end_date=end_date,
+        save_to_file=save_file,
+        parameter_name="Temperature_C"
+    )
+
+__all__ = [
+    "greet", "add", "multiply", 
+    "get_usgs_data", "USGSDataRetriever",
+    "get_discharge", "get_water_level", "get_temperature",
+    "plot_usgs_data", "plot_multiple_gages", "quick_plot", "WaterDataPlotter"
+]

hydroanomaly/plotting.py

@@ -0,0 +1,389 @@
+"""
+Plotting Module for HydroAnomaly
+
+This module provides easy-to-use plotting functions for USGS water data time series.
+Creates professional-looking plots with minimal code.
+"""
+
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+import seaborn as sns
+import pandas as pd
+import numpy as np
+from datetime import datetime
+from typing import Optional, Tuple, List, Dict, Any
+import warnings
+
+# Set style
+plt.style.use('default')
+sns.set_palette("husl")
+
+
+class WaterDataPlotter:
+    """
+    A class for creating professional time series plots of water data.
+    
+    This class provides methods to create various types of plots including
+    basic time series, multi-parameter plots, and statistical visualizations.
+    """
+    
+    def __init__(self, style: str = 'seaborn-v0_8', figsize: Tuple[int, int] = (12, 6)):
+        """
+        Initialize the plotter with default settings.
+        
+        Args:
+            style (str): Matplotlib style to use
+            figsize (tuple): Default figure size (width, height)
+        """
+        self.default_figsize = figsize
+        self.colors = ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', 
+                      '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf']
+        
+        # Set plotting style
+        try:
+            plt.style.use(style)
+        except:
+            plt.style.use('default')
+            warnings.warn(f"Style '{style}' not available, using default")
+    
+    def plot_timeseries(
+        self,
+        data: pd.DataFrame,
+        parameter_name: str = "Value",
+        title: Optional[str] = None,
+        ylabel: Optional[str] = None,
+        color: str = '#1f77b4',
+        save_path: Optional[str] = None,
+        show_stats: bool = True,
+        figsize: Optional[Tuple[int, int]] = None
+    ) -> plt.Figure:
+        """
+        Create a basic time series plot.
+        
+        Args:
+            data (pd.DataFrame): Data with 'datetime' and 'value' columns
+            parameter_name (str): Name of the parameter being plotted
+            title (str, optional): Plot title
+            ylabel (str, optional): Y-axis label
+            color (str): Line color
+            save_path (str, optional): Path to save the plot
+            show_stats (bool): Whether to show statistics on the plot
+            figsize (tuple, optional): Figure size
+            
+        Returns:
+            matplotlib.figure.Figure: The created figure
+        """
+        if len(data) == 0:
+            raise ValueError("No data to plot")
+        
+        figsize = figsize or self.default_figsize
+        fig, ax = plt.subplots(figsize=figsize)
+        
+        # Plot the data
+        ax.plot(data['datetime'], data['value'], color=color, linewidth=1.5, alpha=0.8)
+        
+        # Customize the plot
+        if title is None:
+            title = f"{parameter_name} Time Series"
+        ax.set_title(title, fontsize=14, fontweight='bold', pad=20)
+        
+        if ylabel is None:
+            ylabel = parameter_name
+        ax.set_ylabel(ylabel, fontsize=12)
+        ax.set_xlabel('Date', fontsize=12)
+        
+        # Format dates on x-axis
+        self._format_date_axis(ax, data['datetime'])
+        
+        # Add grid
+        ax.grid(True, alpha=0.3, linestyle='--')
+        
+        # Add statistics if requested
+        if show_stats:
+            self._add_statistics_text(ax, data['value'], parameter_name)
+        
+        # Improve layout
+        plt.tight_layout()
+        
+        # Save if requested
+        if save_path:
+            plt.savefig(save_path, dpi=300, bbox_inches='tight')
+            print(f"📊 Plot saved to: {save_path}")
+        
+        return fig
+    
+    def plot_multiple_parameters(
+        self,
+        data_dict: Dict[str, pd.DataFrame],
+        title: str = "Multiple Parameters Time Series",
+        save_path: Optional[str] = None,
+        figsize: Optional[Tuple[int, int]] = None
+    ) -> plt.Figure:
+        """
+        Plot multiple parameters on separate subplots.
+        
+        Args:
+            data_dict (dict): Dictionary with parameter names as keys and DataFrames as values
+            title (str): Main plot title
+            save_path (str, optional): Path to save the plot
+            figsize (tuple, optional): Figure size
+            
+        Returns:
+            matplotlib.figure.Figure: The created figure
+        """
+        n_params = len(data_dict)
+        if n_params == 0:
+            raise ValueError("No data provided")
+        
+        figsize = figsize or (12, 4 * n_params)
+        fig, axes = plt.subplots(n_params, 1, figsize=figsize, sharex=True)
+        
+        if n_params == 1:
+            axes = [axes]
+        
+        colors = self.colors[:n_params]
+        
+        for i, (param_name, data) in enumerate(data_dict.items()):
+            if len(data) == 0:
+                continue
+                
+            ax = axes[i]
+            ax.plot(data['datetime'], data['value'], 
+                   color=colors[i], linewidth=1.5, alpha=0.8, label=param_name)
+            
+            ax.set_ylabel(param_name, fontsize=11)
+            ax.grid(True, alpha=0.3, linestyle='--')
+            ax.legend(loc='upper right')
+            
+            # Add basic stats
+            mean_val = data['value'].mean()
+            ax.axhline(y=mean_val, color=colors[i], linestyle=':', alpha=0.6, 
+                      label=f'Mean: {mean_val:.2f}')
+        
+        # Format the bottom subplot x-axis
+        if data_dict:
+            sample_data = next(iter(data_dict.values()))
+            self._format_date_axis(axes[-1], sample_data['datetime'])
+        
+        axes[-1].set_xlabel('Date', fontsize=12)
+        fig.suptitle(title, fontsize=14, fontweight='bold')
+        
+        plt.tight_layout()
+        
+        if save_path:
+            plt.savefig(save_path, dpi=300, bbox_inches='tight')
+            print(f"📊 Plot saved to: {save_path}")
+        
+        return fig
+    
+    def plot_comparison(
+        self,
+        data_list: List[Tuple[pd.DataFrame, str]],
+        title: str = "Data Comparison",
+        ylabel: str = "Value",
+        save_path: Optional[str] = None,
+        figsize: Optional[Tuple[int, int]] = None
+    ) -> plt.Figure:
+        """
+        Plot multiple datasets on the same axes for comparison.
+        
+        Args:
+            data_list (list): List of tuples (DataFrame, label)
+            title (str): Plot title
+            ylabel (str): Y-axis label
+            save_path (str, optional): Path to save the plot
+            figsize (tuple, optional): Figure size
+            
+        Returns:
+            matplotlib.figure.Figure: The created figure
+        """
+        if not data_list:
+            raise ValueError("No data provided")
+        
+        figsize = figsize or self.default_figsize
+        fig, ax = plt.subplots(figsize=figsize)
+        
+        colors = self.colors[:len(data_list)]
+        
+        for i, (data, label) in enumerate(data_list):
+            if len(data) == 0:
+                continue
+            
+            ax.plot(data['datetime'], data['value'], 
+                   color=colors[i], linewidth=1.5, alpha=0.8, label=label)
+        
+        ax.set_title(title, fontsize=14, fontweight='bold', pad=20)
+        ax.set_ylabel(ylabel, fontsize=12)
+        ax.set_xlabel('Date', fontsize=12)
+        ax.grid(True, alpha=0.3, linestyle='--')
+        ax.legend()
+        
+        # Format dates
+        if data_list and len(data_list[0][0]) > 0:
+            self._format_date_axis(ax, data_list[0][0]['datetime'])
+        
+        plt.tight_layout()
+        
+        if save_path:
+            plt.savefig(save_path, dpi=300, bbox_inches='tight')
+            print(f"📊 Plot saved to: {save_path}")
+        
+        return fig
+    
+    def plot_statistics(
+        self,
+        data: pd.DataFrame,
+        parameter_name: str = "Parameter",
+        save_path: Optional[str] = None
+    ) -> plt.Figure:
+        """
+        Create statistical plots (histogram and box plot).
+        
+        Args:
+            data (pd.DataFrame): Data with 'datetime' and 'value' columns
+            parameter_name (str): Name of the parameter
+            save_path (str, optional): Path to save the plot
+            
+        Returns:
+            matplotlib.figure.Figure: The created figure
+        """
+        if len(data) == 0:
+            raise ValueError("No data to plot")
+        
+        fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))
+        
+        # Histogram
+        ax1.hist(data['value'], bins=30, alpha=0.7, color=self.colors[0], edgecolor='black')
+        ax1.set_title(f'{parameter_name} Distribution', fontweight='bold')
+        ax1.set_xlabel(parameter_name)
+        ax1.set_ylabel('Frequency')
+        ax1.grid(True, alpha=0.3)
+        
+        # Add statistics to histogram
+        mean_val = data['value'].mean()
+        median_val = data['value'].median()
+        ax1.axvline(mean_val, color='red', linestyle='--', alpha=0.8, label=f'Mean: {mean_val:.2f}')
+        ax1.axvline(median_val, color='orange', linestyle='--', alpha=0.8, label=f'Median: {median_val:.2f}')
+        ax1.legend()
+        
+        # Box plot
+        box_data = ax2.boxplot(data['value'], patch_artist=True)
+        box_data['boxes'][0].set_facecolor(self.colors[1])
+        box_data['boxes'][0].set_alpha(0.7)
+        
+        ax2.set_title(f'{parameter_name} Box Plot', fontweight='bold')
+        ax2.set_ylabel(parameter_name)
+        ax2.grid(True, alpha=0.3)
+        
+        plt.tight_layout()
+        
+        if save_path:
+            plt.savefig(save_path, dpi=300, bbox_inches='tight')
+            print(f"📊 Plot saved to: {save_path}")
+        
+        return fig
+    
+    def _format_date_axis(self, ax, dates):
+        """Format the date axis based on the date range."""
+        date_range = (dates.max() - dates.min()).days
+        
+        if date_range <= 7:  # Less than a week
+            ax.xaxis.set_major_formatter(mdates.DateFormatter('%m/%d %H:%M'))
+            ax.xaxis.set_major_locator(mdates.HourLocator(interval=6))
+        elif date_range <= 31:  # Less than a month
+            ax.xaxis.set_major_formatter(mdates.DateFormatter('%m/%d'))
+            ax.xaxis.set_major_locator(mdates.DayLocator(interval=2))
+        elif date_range <= 365:  # Less than a year
+            ax.xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m'))
+            ax.xaxis.set_major_locator(mdates.MonthLocator())
+        else:  # More than a year
+            ax.xaxis.set_major_formatter(mdates.DateFormatter('%Y'))
+            ax.xaxis.set_major_locator(mdates.YearLocator())
+        
+        plt.setp(ax.xaxis.get_majorticklabels(), rotation=45, ha='right')
+    
+    def _add_statistics_text(self, ax, values, parameter_name):
+        """Add statistics text box to the plot."""
+        stats_text = (
+            f"Statistics:\n"
+            f"Mean: {values.mean():.2f}\n"
+            f"Median: {values.median():.2f}\n"
+            f"Min: {values.min():.2f}\n"
+            f"Max: {values.max():.2f}\n"
+            f"Std: {values.std():.2f}"
+        )
+        
+        # Position the text box
+        ax.text(0.02, 0.98, stats_text, transform=ax.transAxes, fontsize=9,
+                verticalalignment='top', bbox=dict(boxstyle='round', facecolor='wheat', alpha=0.8))
+
+
+# Convenience functions for easy plotting
+def plot_usgs_data(
+    data: pd.DataFrame,
+    parameter_name: str = "Value",
+    title: Optional[str] = None,
+    save_path: Optional[str] = None,
+    show_stats: bool = True
+) -> plt.Figure:
+    """
+    Quick function to plot USGS time series data.
+    
+    Args:
+        data (pd.DataFrame): Data with 'datetime' and 'value' columns
+        parameter_name (str): Name of the parameter being plotted
+        title (str, optional): Plot title
+        save_path (str, optional): Path to save the plot
+        show_stats (bool): Whether to show statistics on the plot
+        
+    Returns:
+        matplotlib.figure.Figure: The created figure
+        
+    Example:
+        >>> import hydroanomaly
+        >>> data = hydroanomaly.get_discharge("08158000", "2023-01-01", "2023-01-31")
+        >>> hydroanomaly.plot_usgs_data(data, "Discharge (cfs)", "Colorado River Discharge")
+    """
+    plotter = WaterDataPlotter()
+    return plotter.plot_timeseries(
+        data=data,
+        parameter_name=parameter_name,
+        title=title,
+        save_path=save_path,
+        show_stats=show_stats
+    )
+
+
+def plot_multiple_gages(
+    data_dict: Dict[str, pd.DataFrame],
+    title: str = "Multiple Gage Comparison",
+    parameter_name: str = "Value",
+    save_path: Optional[str] = None
+) -> plt.Figure:
+    """
+    Plot data from multiple gages for comparison.
+    
+    Args:
+        data_dict (dict): Dictionary with gage IDs as keys and DataFrames as values
+        title (str): Plot title
+        parameter_name (str): Y-axis label
+        save_path (str, optional): Path to save the plot
+        
+    Returns:
+        matplotlib.figure.Figure: The created figure
+    """
+    plotter = WaterDataPlotter()
+    data_list = [(data, f"Gage {gage_id}") for gage_id, data in data_dict.items()]
+    return plotter.plot_comparison(data_list, title, parameter_name, save_path)
+
+
+def quick_plot(data: pd.DataFrame, title: str = "USGS Data") -> None:
+    """
+    Create a quick plot and show it immediately.
+    
+    Args:
+        data (pd.DataFrame): Data to plot
+        title (str): Plot title
+    """
+    plot_usgs_data(data, title=title)
+    plt.show()

hydroanomaly-0.3.0.dist-info/METADATA

@@ -0,0 +1,400 @@
+Metadata-Version: 2.4
+Name: hydroanomaly
+Version: 0.3.0
+Summary: A Python package for hydro anomaly detection
+Home-page: https://github.com/yourusername/hydroanomaly
+Author: Your Name
+Author-email: Your Name <your.email@example.com>
+License-Expression: MIT
+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
+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: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# 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! 🌊📊

hydroanomaly-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+hydroanomaly/__init__.py,sha256=orCkJ2g57zR9o5RUekkh0eOUvhalQVbRro5Oxm-iYZk,2997
+hydroanomaly/hello.py,sha256=AhK7UKF_3TyZcWL4IDlZq_BXdKQzUP-is-jv59fgqk4,566
+hydroanomaly/math_utils.py,sha256=CDOGWAiRlb2PK5SNFysumnzp7_LbZ9aleHLR_3lsGrs,856
+hydroanomaly/plotting.py,sha256=YZW6-Sb_IrhbHKFeoh1d86Ef4Ev5Gpq55lEv8XX0v20,13504
+hydroanomaly/usgs_data.py,sha256=zUvfu3go-7cQuFtD8Hbm7pABpw_RPWuJxE66NhxYmIU,11631
+hydroanomaly-0.3.0.dist-info/licenses/LICENSE,sha256=OphKV48tcMv6ep-7j-8T6nycykPT0g8ZlMJ9zbGvdPs,1066
+hydroanomaly-0.3.0.dist-info/METADATA,sha256=3NDnQzVH84RCiRpHf1SyQf5OHDIGMsMTEa-tlI822p4,11680
+hydroanomaly-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hydroanomaly-0.3.0.dist-info/top_level.txt,sha256=t-5Lc-eTLlkxIhR_N1Cpp6_YZafKS3xLLk9D2CtbE7o,13
+hydroanomaly-0.3.0.dist-info/RECORD,,

hydroanomaly-0.2.0.dist-info/METADATA

@@ -1,227 +0,0 @@
-Metadata-Version: 2.4
-Name: hydroanomaly
-Version: 0.2.0
-Summary: A Python package for hydro anomaly detection
-Home-page: https://github.com/yourusername/hydroanomaly
-Author: Your Name
-Author-email: Your Name <your.email@example.com>
-License-Expression: MIT
-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
-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: author
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-python
-
-# 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.

hydroanomaly-0.2.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-hydroanomaly/__init__.py,sha256=i3F0lmj7Jia0je1ArZhx4OsK-nnPCulQSz5WoCpZ3MI,413
-hydroanomaly/hello.py,sha256=AhK7UKF_3TyZcWL4IDlZq_BXdKQzUP-is-jv59fgqk4,566
-hydroanomaly/math_utils.py,sha256=CDOGWAiRlb2PK5SNFysumnzp7_LbZ9aleHLR_3lsGrs,856
-hydroanomaly/usgs_data.py,sha256=zUvfu3go-7cQuFtD8Hbm7pABpw_RPWuJxE66NhxYmIU,11631
-hydroanomaly-0.2.0.dist-info/licenses/LICENSE,sha256=OphKV48tcMv6ep-7j-8T6nycykPT0g8ZlMJ9zbGvdPs,1066
-hydroanomaly-0.2.0.dist-info/METADATA,sha256=7VORMpDk286u6ElwB890-ISI9FlynP21CXk-dSR-8sM,6140
-hydroanomaly-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-hydroanomaly-0.2.0.dist-info/top_level.txt,sha256=t-5Lc-eTLlkxIhR_N1Cpp6_YZafKS3xLLk9D2CtbE7o,13
-hydroanomaly-0.2.0.dist-info/RECORD,,