hydroanomaly 0.6.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

hydroanomaly/__init__.py

@@ -2,15 +2,15 @@
 HydroAnomaly: Simple Water Data Analysis Package
 
 A simple Python package with just 3 modules:
-1. USGS turbidity data retrieval
+1. USGS turbidity data retrieval (returns data and site coordinates)
 2. Sentinel satellite bands retrieval  
 3. Time series visualization
 
 That's it - nothing else!
 """
 
-__version__ = "0.6.0"
-__author__ = "HydroAnomaly Team"
+__version__ = "0.7.1"
+__author__ = "Ehsan Kahrizi (Ehsan.kahrizi@usu.edu)"
 
 # Import the 3 simple modules
 from .usgs_turbidity import get_turbidity, get_usgs_turbidity
@@ -38,9 +38,9 @@ __all__ = [
     'visualize'
 ]
 
-print(f"🌊 HydroAnomaly v{__version__} - Simple Water Data Package")
-print("📚 Available functions:")
-print("   • get_turbidity() - Get USGS turbidity data")
+print(f"HydroAnomaly v{__version__} - Simple Water Data Package")
+print("Available functions:")
+print("   • get_turbidity() - Get USGS turbidity data and site coordinates")
 print("   • get_sentinel_bands() - Get satellite data") 
 print("   • plot_timeseries() - Visualize data")
-print("💡 Try: help(hydroanomaly.get_turbidity) for examples")
+print("Try: help(hydroanomaly.get_turbidity) for examples")

hydroanomaly/sentinel_bands.py

@@ -1,8 +1,8 @@
 """
-Simple Sentinel Satellite Data Retrieval
+Sentinel-2 Satellite Data Retrieval using Google Earth Engine (GEE)
 
-This module provides one simple function to get Sentinel satellite bands.
-That's it - nothing else!
+This module provides a function to retrieve Sentinel-2 satellite band data
+for a specified location and time period, with masking and cloud filtering.
 """
 
 import pandas as pd
@@ -11,147 +11,94 @@ from datetime import datetime, timedelta
 import requests
 import warnings
 
-
-def get_sentinel_bands(latitude: float, longitude: float, start_date: str, end_date: str, bands: list = None) -> pd.DataFrame:
+def get_sentinel_bands_gee(
+    latitude: float,
+    longitude: float,
+    start_date: str,
+    end_date: str,
+    bands: list = None,
+    buffer_meters: int = 20,
+    cloudy_pixel_percentage: int = 20,
+    masks_to_apply: list = None
+) -> pd.DataFrame:
     """
-    Get Sentinel satellite band data for a location.
-    
+    Retrieve Sentinel-2 bands from Google Earth Engine, applying custom masking.
+
     Args:
-        latitude (float): Latitude coordinate (e.g., 30.2672)
-        longitude (float): Longitude coordinate (e.g., -97.7431)
-        start_date (str): Start date as "YYYY-MM-DD"
-        end_date (str): End date as "YYYY-MM-DD" 
-        bands (list): List of bands to retrieve (default: ['B2', 'B3', 'B4', 'B8'])
-        
+        latitude (float): Latitude of center point.
+        longitude (float): Longitude of center point.
+        start_date (str): Start date as "YYYY-MM-DD".
+        end_date (str): End date as "YYYY-MM-DD".
+        bands (list): List of bands to retrieve (default is common Sentinel-2 bands).
+        buffer_meters (int): Buffer size around the point, in meters.
+        cloudy_pixel_percentage (int): Maximum allowed cloud percentage for each image.
+        masks_to_apply (list): Masking strategies (e.g., ["water", "no_cloud_shadow", ...]).
+
     Returns:
-        pd.DataFrame: Time series data with datetime index and band values
-        
+        pd.DataFrame: DataFrame with band reflectance values per date.
+
     Example:
-        >>> data = get_sentinel_bands(30.2672, -97.7431, "2023-01-01", "2023-12-31")
-        >>> print(f"Got {len(data)} satellite observations")
+        >>> import ee
+        >>> ee.Authenticate()
+        >>> ee.Initialize()
+        >>> df = get_sentinel_bands_gee(29.77, -95.06, "2021-01-01", "2021-12-31")
+        >>> print(df.head())
     """
-    
     if bands is None:
-        bands = ['B2', 'B3', 'B4', 'B8']  # Blue, Green, Red, NIR
-    
-    print(f"🛰️  Getting Sentinel data for location ({latitude}, {longitude})")
-    print(f"📅 Date range: {start_date} to {end_date}")
-    print(f"📡 Bands: {', '.join(bands)}")
-    
-    try:
-        # Try to get real Sentinel data (this would normally use Google Earth Engine or similar)
-        # For now, we'll create realistic synthetic data
-        print("⚠️  Creating synthetic Sentinel data (real API integration would go here)")
-        return _create_synthetic_sentinel(latitude, longitude, start_date, end_date, bands)
-        
-    except Exception as e:
-        print(f"❌ Error: {e}")
-        print("🔄 Creating synthetic Sentinel data...")
-        return _create_synthetic_sentinel(latitude, longitude, start_date, end_date, bands)
+        bands = ['B2','B3','B4','B8','SCL']
+    if masks_to_apply is None:
+        masks_to_apply = ["water", "no_cloud_shadow", "no_clouds", "no_snow_ice", "no_saturated"]
 
+    point = ee.Geometry.Point([longitude, latitude])
+    buffered_point = point.buffer(buffer_meters)
 
-def _create_synthetic_sentinel(lat: float, lon: float, start_date: str, end_date: str, bands: list) -> pd.DataFrame:
-    """Create realistic synthetic Sentinel satellite data."""
-    
-    # Generate dates (Sentinel-2 has ~5-day revisit time)
-    start_dt = datetime.strptime(start_date, "%Y-%m-%d")
-    end_dt = datetime.strptime(end_date, "%Y-%m-%d")
-    
-    # Create observation dates (every 5-10 days, accounting for clouds)
-    observation_dates = []
-    current_date = start_dt
-    
-    while current_date <= end_dt:
-        # Add some randomness to simulate real satellite schedule
-        if np.random.random() > 0.3:  # 70% chance of successful observation
-            observation_dates.append(current_date)
-        
-        # Next observation in 5-10 days
-        days_to_add = np.random.randint(5, 11)
-        current_date += timedelta(days=days_to_add)
-    
-    if len(observation_dates) == 0:
-        print("⚠️  No observation dates generated")
-        return pd.DataFrame()
-    
-    # Generate realistic band values
-    data_dict = {'datetime': observation_dates}
-    
-    for band in bands:
-        if band == 'B2':  # Blue (450-520nm)
-            base_value = 1200
-            variation = 300
-        elif band == 'B3':  # Green (520-600nm) 
-            base_value = 1400
-            variation = 350
-        elif band == 'B4':  # Red (630-690nm)
-            base_value = 1300
-            variation = 400
-        elif band == 'B8':  # NIR (760-900nm)
-            base_value = 2800
-            variation = 800
-        else:  # Generic band
-            base_value = 1500
-            variation = 400
-        
-        # Generate values with seasonal and random variation
-        band_values = []
-        for i, date in enumerate(observation_dates):
-            # Seasonal variation (higher vegetation in summer)
-            day_of_year = date.timetuple().tm_yday
-            seasonal_factor = np.sin(2 * np.pi * day_of_year / 365) * 0.2
-            
-            # Random variation
-            noise = np.random.normal(0, variation * 0.3)
-            
-            # Calculate final value
-            value = base_value * (1 + seasonal_factor) + noise
-            value = max(0, int(value))  # Ensure positive integer values
-            
-            band_values.append(value)
-        
-        data_dict[band] = band_values
-    
-    # Create DataFrame
-    result = pd.DataFrame(data_dict)
-    result['datetime'] = pd.to_datetime(result['datetime'])
-    result = result.set_index('datetime')
-    
-    print(f"📊 Created {len(result)} synthetic Sentinel observations")
-    print(f"📡 Bands included: {', '.join(bands)}")
-    
-    return result
+    s2 = (ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED')
+          .filterBounds(buffered_point)
+          .filterDate(start_date, end_date)
+          .filter(ee.Filter.lt('CLOUDY_PIXEL_PERCENTAGE', cloudy_pixel_percentage))
+          .select(bands))
 
+    def dynamic_scl_mask(image):
+        scl = image.select('SCL')
+        mask = ee.Image.constant(1)
+        if "water" in masks_to_apply:
+            mask = mask.And(scl.eq(6))
+        if "no_cloud_shadow" in masks_to_apply:
+            mask = mask.And(scl.neq(3))
+        if "no_clouds" in masks_to_apply:
+            cloud_mask = scl.neq(8).And(scl.neq(9)).And(scl.neq(10))
+            mask = mask.And(cloud_mask)
+        if "no_snow_ice" in masks_to_apply:
+            mask = mask.And(scl.neq(11))
+        if "no_saturated" in masks_to_apply:
+            mask = mask.And(scl.neq(1))
+        return image.updateMask(mask)
 
-def calculate_ndvi(sentinel_data: pd.DataFrame) -> pd.DataFrame:
-    """
-    Calculate NDVI from Sentinel data.
-    
-    Args:
-        sentinel_data (pd.DataFrame): DataFrame with B4 (Red) and B8 (NIR) bands
-        
-    Returns:
-        pd.DataFrame: DataFrame with NDVI values
-    """
-    
-    if 'B4' not in sentinel_data.columns or 'B8' not in sentinel_data.columns:
-        print("❌ Need B4 (Red) and B8 (NIR) bands to calculate NDVI")
-        return pd.DataFrame()
-    
-    # Calculate NDVI = (NIR - Red) / (NIR + Red)
-    red = sentinel_data['B4']
-    nir = sentinel_data['B8']
-    
-    ndvi = (nir - red) / (nir + red)
-    
-    result = pd.DataFrame({'NDVI': ndvi}, index=sentinel_data.index)
-    
-    print(f"📊 Calculated NDVI for {len(result)} observations")
-    print(f"🌱 NDVI range: {ndvi.min():.3f} to {ndvi.max():.3f}")
-    
-    return result
+    s2_masked = s2.map(dynamic_scl_mask)
+
+    def extract_features(image):
+        date = image.date().format('YYYY-MM-dd HH:mm:ss')
+        values = image.reduceRegion(
+            reducer=ee.Reducer.mean(),
+            geometry=buffered_point,
+            scale=20,
+            maxPixels=1e8
+        )
+        return ee.Feature(None, values.set('date', date))
+
+    features = s2_masked.map(extract_features)
+    fc = ee.FeatureCollection(features).filter(ee.Filter.notNull(['B2']))
 
+    data = fc.getInfo()
+    rows = [f['properties'] for f in data['features']]
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df['date'] = pd.to_datetime(df['date'])
+        df = df.sort_values('date')
+        df = df.set_index('date')
+    return df
 
-# Simple aliases
-get_satellite_data = get_sentinel_bands
-get_sentinel = get_sentinel_bands
+# Aliases for user convenience
+get_sentinel_bands = get_sentinel_bands_gee
+get_satellite_data = get_sentinel_bands_gee
+get_sentinel = get_sentinel_bands_gee

hydroanomaly/usgs_turbidity.py

@@ -11,7 +11,7 @@ from io import StringIO
 from datetime import datetime
 import numpy as np
 
-
+# Function for retrive data ---------------------------------------------------------------------------------------------------------------------------------------------------------------------
 def get_turbidity(site_number: str, start_date: str, end_date: str) -> pd.DataFrame:
     """
     Get turbidity data from a USGS station.
@@ -22,50 +22,75 @@ def get_turbidity(site_number: str, start_date: str, end_date: str) -> pd.DataFr
         end_date (str): End date as "YYYY-MM-DD"
         
     Returns:
-        pd.DataFrame: Time series data with datetime index and turbidity values
+        tuple: (pd.DataFrame, (latitude, longitude)) or (empty DataFrame, (None, None)) if not found.
+        * Note: pd.DataFrame: Time series data with datetime index and turbidity values
         
     Example:
         >>> data = get_turbidity("294643095035200", "2023-01-01", "2023-12-31")
         >>> print(f"Got {len(data)} turbidity measurements")
     """
+
+    # --- Validate inputs ---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    print(f"Getting turbidity data for site {site_number}")
+    print(f"Date range: {start_date} to {end_date}")
+    
+    # --- Retrieve site metadata (lat/lon) ---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    site_url = (
+        f"https://waterservices.usgs.gov/nwis/site/"
+        f"?sites={site_number}"
+        f"&format=rdb")
+    try:
+        site_resp = requests.get(site_url, timeout=15)
+        if site_resp.status_code != 200:
+            print(f"Could not get site metadata: {site_resp.status_code}")
+            lat, lon = None, None
+        else:
+            df_meta = pd.read_csv(StringIO(site_resp.text), sep="\t", comment="#")
+            df_meta = df_meta.dropna(axis=1, how="all")
+            lat, lon = None, None
+            if not df_meta.empty:
+                lat = float(df_meta["dec_lat_va"].iloc[0]) if "dec_lat_va" in df_meta.columns else None
+                lon = float(df_meta["dec_long_va"].iloc[0]) if "dec_long_va" in df_meta.columns else None
+    except Exception as e:
+        print(f"Error getting site coordinates: {e}")
+        lat, lon = None, None
     
-    print(f"🌊 Getting turbidity data for site {site_number}")
-    print(f"📅 Date range: {start_date} to {end_date}")
     
-    # Build USGS API URL for turbidity (parameter code 63680)
+    # --- Retrieve turbidity data (Build USGS API URL for turbidity (parameter code 63680))------------------------------------------------------------------------------------------------------------------------------------------------------------------
     url = (
         f"https://waterservices.usgs.gov/nwis/iv/"
         f"?sites={site_number}"
         f"&parameterCd=63680"  # Turbidity parameter code
         f"&startDT={start_date}"
         f"&endDT={end_date}"
-        f"&format=rdb"
-    )
+        f"&format=rdb")
     
     try:
         # Get data from USGS
         response = requests.get(url, timeout=30)
         
         if response.status_code != 200:
-            print(f"❌ API Error: {response.status_code}")
-            return _create_synthetic_turbidity(start_date, end_date)
+            print(f"No data found: API returned status {response.status_code}.")
+            print("Data for the specified site or parameters does not exist.")
+            return pd.DataFrame(), (lat, lon)
         
         # Parse the response
         data = _parse_usgs_response(response.text)
         
         if len(data) == 0:
-            print("⚠️  No real data found. Creating synthetic data...")
-            return _create_synthetic_turbidity(start_date, end_date)
+            print("No data found for the specified parameters or date range.")
+            return pd.DataFrame(), (lat, lon)
         
-        print(f"✅ Retrieved {len(data)} turbidity measurements")
-        return data
+        print(f"Retrieved {len(data)} turbidity measurements")
+        return data, (lat, lon)
         
     except Exception as e:
-        print(f"❌ Error: {e}")
-        print("🔄 Creating synthetic turbidity data...")
-        return _create_synthetic_turbidity(start_date, end_date)
+        print(f"Error: {e}")
+        print("Data for the specified site or parameters does not exist.")
+        return pd.DataFrame(), (lat, lon)
 
 
+# Function for parse and cleaning Turbidity Time Series from USGS API Respons as DataFrame ---------------------------------------------------------------------------------------------------------------------------------------------------------------------
 def _parse_usgs_response(content: str) -> pd.DataFrame:
     """Parse USGS response and extract turbidity data."""
     
@@ -107,44 +132,5 @@ def _parse_usgs_response(content: str) -> pd.DataFrame:
         return pd.DataFrame()
 
 
-def _create_synthetic_turbidity(start_date: str, end_date: str) -> pd.DataFrame:
-    """Create realistic synthetic turbidity data."""
-    
-    date_range = pd.date_range(start=start_date, end=end_date, freq='H')
-    
-    # Generate realistic turbidity values (typically 0-50 NTU)
-    base_turbidity = 8.0  # Base level
-    daily_variation = 3.0  # Daily fluctuation
-    
-    # Create synthetic values with realistic patterns
-    synthetic_values = []
-    for i, dt in enumerate(date_range):
-        # Base value with daily pattern
-        daily_factor = np.sin(2 * np.pi * dt.hour / 24) * daily_variation
-        
-        # Add some noise
-        noise = np.random.normal(0, 1.5)
-        
-        # Occasional high turbidity events (storms)
-        if np.random.random() < 0.02:  # 2% chance of high event
-            storm_factor = np.random.uniform(10, 30)
-        else:
-            storm_factor = 0
-            
-        value = base_turbidity + daily_factor + noise + storm_factor
-        value = max(0.1, value)  # Ensure positive values
-        
-        synthetic_values.append(value)
-    
-    # Create DataFrame
-    synthetic_data = pd.DataFrame({
-        'turbidity': synthetic_values
-    }, index=date_range)
-    
-    print(f"📊 Created {len(synthetic_data)} synthetic turbidity measurements")
-    
-    return synthetic_data
-
-
 # Simple alias for backwards compatibility
 get_usgs_turbidity = get_turbidity

{hydroanomaly-0.6.0.dist-info → hydroanomaly-0.7.1.dist-info}/METADATA

@@ -1,11 +1,30 @@
 Metadata-Version: 2.4
 Name: hydroanomaly
-Version: 0.6.0
+Version: 0.7.1
 Summary: A Python package for hydro anomaly detection with simple USGS data retrieval
-Home-page: https://github.com/yourusername/hydroanomaly
-Author: Your Name
-Author-email: Your Name <your.email@example.com>
-License-Expression: MIT
+Author-email: Ehsan Kahrizi <ehsan.kahrizi@usu.edu>
+License: MIT License
+        
+        Copyright (c) 2025 Your Name
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
 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
@@ -30,10 +49,7 @@ 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
 

hydroanomaly-0.7.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+hydroanomaly/__init__.py,sha256=AFzyku0-OvyWnguhWZ-SoBcdPTKEPzV6GfOGLpPUFuQ,1375
+hydroanomaly/sentinel_bands.py,sha256=TbdyvBRe9v3YGOz4umYhSJ-16a5lCF0YLwnmArZ9Gvs,3627
+hydroanomaly/usgs_turbidity.py,sha256=k0cXRXpTe1YgjfR0Htw77SLD8hM--43jiEiJwx1vRg0,5664
+hydroanomaly/visualize.py,sha256=gkLgI3agx291jK5o08nYEbEpGpr6cD-6aAKn2Ha2Lqk,6937
+hydroanomaly-0.7.1.dist-info/licenses/LICENSE,sha256=OphKV48tcMv6ep-7j-8T6nycykPT0g8ZlMJ9zbGvdPs,1066
+hydroanomaly-0.7.1.dist-info/METADATA,sha256=HIMGK2WWKXrX7PYfu_c5J3Fl-Zsetq9Ug9TiSZgyifM,12962
+hydroanomaly-0.7.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+hydroanomaly-0.7.1.dist-info/top_level.txt,sha256=t-5Lc-eTLlkxIhR_N1Cpp6_YZafKS3xLLk9D2CtbE7o,13
+hydroanomaly-0.7.1.dist-info/RECORD,,

hydroanomaly-0.6.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-hydroanomaly/__init__.py,sha256=pbS4SUDEYV8e9we3YqAe3Jo-EKX77eCdwirofp4Yk_4,1313
-hydroanomaly/sentinel_bands.py,sha256=Zvy9vJ7RooJTWLJK-ihGZ6CEneQcHVJ8I5MgueYcoyQ,5534
-hydroanomaly/usgs_turbidity.py,sha256=r0ozmiZXVYjtu04UnT3ijxra_WQVUUpus7WLcYCH3iM,4921
-hydroanomaly/visualize.py,sha256=gkLgI3agx291jK5o08nYEbEpGpr6cD-6aAKn2Ha2Lqk,6937
-hydroanomaly-0.6.0.dist-info/licenses/LICENSE,sha256=OphKV48tcMv6ep-7j-8T6nycykPT0g8ZlMJ9zbGvdPs,1066
-hydroanomaly-0.6.0.dist-info/METADATA,sha256=cZxYHfAnYHP1Wqspxf--JUBlKDKs29mhybbhslS1Zx0,11873
-hydroanomaly-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-hydroanomaly-0.6.0.dist-info/top_level.txt,sha256=t-5Lc-eTLlkxIhR_N1Cpp6_YZafKS3xLLk9D2CtbE7o,13
-hydroanomaly-0.6.0.dist-info/RECORD,,