hydroanomaly 0.2.0__tar.gz → 0.3.0__tar.gz

hydroanomaly-0.3.0/PKG-INFO

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