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

hydroanomaly-0.4.0.dist-info/METADATA

@@ -0,0 +1,405 @@
+Metadata-Version: 2.4
+Name: hydroanomaly
+Version: 0.4.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
+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: 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.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+hydroanomaly/__init__.py,sha256=5X78u2gwZFugrWfMtXv9bV4QNIj8yA36sJTSkk_qb4w,4884
+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/sentinel_data.py,sha256=C5T1ycyTcAGvR6KEukDHJe2kEDbFXgh0yVXi8QrjFXs,17870
+hydroanomaly/usgs_data.py,sha256=zUvfu3go-7cQuFtD8Hbm7pABpw_RPWuJxE66NhxYmIU,11631
+hydroanomaly-0.4.0.dist-info/licenses/LICENSE,sha256=OphKV48tcMv6ep-7j-8T6nycykPT0g8ZlMJ9zbGvdPs,1066
+hydroanomaly-0.4.0.dist-info/METADATA,sha256=6JGNAS0GWcMflIOidfmZEz71IqZmc_IJxybtdDmGz3o,11841
+hydroanomaly-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hydroanomaly-0.4.0.dist-info/top_level.txt,sha256=t-5Lc-eTLlkxIhR_N1Cpp6_YZafKS3xLLk9D2CtbE7o,13
+hydroanomaly-0.4.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,,