hydroanomaly 0.2.0

A Python package for hydro anomaly detection

HydroAnomaly

A Python package for hydro anomaly detection and USGS water data retrieval.

Installation

pip install hydroanomaly

🆕 New Feature: 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())

Quick Start

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

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}")

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.