hydroanomaly 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

hydroanomaly/__init__.py

@@ -1,146 +1,46 @@
 """
-HydroAnomaly
+HydroAnomaly: Simple Water Data Analysis Package
 
-A Python package for hydro anomaly detection, USGS data retrieval, 
-time series visualization, and Sentinel satellite data analysis.
+A simple Python package with just 3 modules:
+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.5.0"
-__author__ = "Your Name"
-__email__ = "your.email@example.com"
+__version__ = "0.7.0"
+__author__ = "Ehsan Kahrizi (Ehsan.kahrizi@usu.edu)"
 
-# Import main modules for easy access
-from .hello import greet
-from .math_utils import add, multiply
-from .usgs_data import get_usgs_data, get_usgs_simple, USGSDataRetriever
-from .plotting import plot_usgs_data, plot_multiple_gages, quick_plot, WaterDataPlotter
+# Import the 3 simple modules
+from .usgs_turbidity import get_turbidity, get_usgs_turbidity
+from .sentinel_bands import get_sentinel_bands, get_satellite_data, get_sentinel, calculate_ndvi
+from .visualize import plot_timeseries, plot_turbidity, plot_sentinel, plot_comparison, plot, visualize
 
-# Base exports
+# Export everything
 __all__ = [
-    'greet',
-    'add', 'multiply',
-    'get_usgs_data', 'get_usgs_simple', 'USGSDataRetriever',
-    'plot_usgs_data', 'plot_multiple_gages', 'quick_plot', 'WaterDataPlotter',
-    'get_discharge', 'get_temperature', 'get_water_level'
+    # USGS turbidity functions
+    'get_turbidity',
+    'get_usgs_turbidity',
+    
+    # Sentinel functions
+    'get_sentinel_bands',
+    'get_satellite_data', 
+    'get_sentinel',
+    'calculate_ndvi',
+    
+    # Visualization functions
+    'plot_timeseries',
+    'plot_turbidity',
+    'plot_sentinel', 
+    'plot_comparison',
+    'plot',
+    'visualize'
 ]
 
-# Try to import Sentinel functionality (optional GEE dependency)
-try:
-    from .sentinel_data import (
-        SentinelDataRetriever, 
-        SentinelConfig, 
-        setup_gee_authentication, 
-        initialize_gee, 
-        get_water_area_time_series, 
-        detect_water_changes
-    )
-    _SENTINEL_AVAILABLE = True
-    
-    # Add Sentinel functions to exports
-    __all__.extend([
-        'SentinelDataRetriever',
-        'SentinelConfig', 
-        'setup_gee_authentication',
-        'initialize_gee',
-        'get_water_area_time_series',
-        'detect_water_changes'
-    ])
-    
-except ImportError as e:
-    print("⚠️  Sentinel data functionality not available.")
-    print("💡 To use Google Earth Engine features, install:")
-    print("   pip install earthengine-api")
-    print("   Then authenticate: earthengine authenticate")
-    _SENTINEL_AVAILABLE = False
-    
-    # Create placeholder functions for better error messages
-    def setup_gee_authentication(*args, **kwargs):
-        raise ImportError("Google Earth Engine not available. Install with: pip install earthengine-api")
-    
-    def initialize_gee(*args, **kwargs):
-        raise ImportError("Google Earth Engine not available. Install with: pip install earthengine-api")
-    
-    def get_water_area_time_series(*args, **kwargs):
-        raise ImportError("Google Earth Engine not available. Install with: pip install earthengine-api")
-    
-    def detect_water_changes(*args, **kwargs):
-        raise ImportError("Google Earth Engine not available. Install with: pip install earthengine-api")
-
-# 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"
-]
+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")

hydroanomaly/sentinel_bands.py

@@ -0,0 +1,104 @@
+"""
+Sentinel-2 Satellite Data Retrieval using Google Earth Engine (GEE)
+
+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
+import numpy as np
+from datetime import datetime, timedelta
+import requests
+import warnings
+
+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:
+    """
+    Retrieve Sentinel-2 bands from Google Earth Engine, applying custom masking.
+
+    Args:
+        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: DataFrame with band reflectance values per date.
+
+    Example:
+        >>> 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','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)
+
+    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)
+
+    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
+
+# 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

@@ -0,0 +1,177 @@
+"""
+Simple USGS Turbidity Data Retrieval
+
+This module provides one simple function to get turbidity data from USGS stations.
+That's it - nothing else!
+"""
+
+import pandas as pd
+import requests
+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.
+    
+    Args:
+        site_number (str): USGS site number (e.g., "294643095035200")
+        start_date (str): Start date as "YYYY-MM-DD" 
+        end_date (str): End date as "YYYY-MM-DD"
+        
+    Returns:
+        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
+    
+    
+    # --- 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")
+    
+    try:
+        # Get data from USGS
+        response = requests.get(url, timeout=30)
+        
+        if response.status_code != 200:
+            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 data found for the specified parameters or date range.")
+            return pd.DataFrame(), (lat, lon)
+        
+        print(f"Retrieved {len(data)} turbidity measurements")
+        return data, (lat, lon)
+        
+    except Exception as e:
+        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."""
+    
+    if "No sites found" in content or "No data" in content:
+        return pd.DataFrame()
+    
+    try:
+        # Read tab-separated data
+        data = pd.read_csv(StringIO(content), sep='\t', comment='#')
+        
+        # Clean up
+        data = data.dropna(axis=1, how='all')
+        data.columns = data.columns.str.strip()
+        
+        # Find datetime and turbidity columns
+        datetime_cols = [col for col in data.columns if 'datetime' in col.lower()]
+        turbidity_cols = [col for col in data.columns if '63680' in col]
+        
+        if not datetime_cols or not turbidity_cols:
+            return pd.DataFrame()
+        
+        # Extract relevant columns
+        result = data[[datetime_cols[0], turbidity_cols[0]]].copy()
+        result.columns = ['datetime', 'turbidity']
+        
+        # Convert data types
+        result['datetime'] = pd.to_datetime(result['datetime'], errors='coerce')
+        result['turbidity'] = pd.to_numeric(result['turbidity'], errors='coerce')
+        
+        # Remove missing data
+        result = result.dropna()
+        
+        # Set datetime as index
+        result = result.set_index('datetime')
+        
+        return result
+        
+    except Exception:
+        return pd.DataFrame()
+
+
+"""
+# Generate synthetic data if data not exist in USGS ---------------------------------------------------------------------------------------------------------------------------------------------------------------------
+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/visualize.py

@@ -0,0 +1,226 @@
+"""
+Simple Time Series Visualization
+
+This module provides simple functions to visualize time series data.
+That's it - nothing else!
+"""
+
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+import pandas as pd
+import numpy as np
+from datetime import datetime
+
+
+def plot_timeseries(data: pd.DataFrame, title: str = "Time Series Data", save_file: str = None) -> None:
+    """
+    Create a simple time series plot.
+    
+    Args:
+        data (pd.DataFrame): DataFrame with datetime index and numeric columns
+        title (str): Title for the plot
+        save_file (str): Optional filename to save the plot
+        
+    Example:
+        >>> plot_timeseries(turbidity_data, "Turbidity Over Time", "turbidity_plot.png")
+    """
+    
+    if data.empty:
+        print("❌ No data to plot")
+        return
+    
+    print(f"📊 Creating plot: {title}")
+    
+    # Create figure
+    plt.figure(figsize=(12, 6))
+    
+    # Plot each column
+    for column in data.columns:
+        if pd.api.types.is_numeric_dtype(data[column]):
+            plt.plot(data.index, data[column], label=column, linewidth=1.5, alpha=0.8)
+    
+    # Format plot
+    plt.title(title, fontsize=14, fontweight='bold', pad=20)
+    plt.xlabel('Date', fontsize=12)
+    plt.ylabel('Value', fontsize=12)
+    plt.grid(True, alpha=0.3)
+    
+    # Format x-axis dates
+    plt.gca().xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m'))
+    plt.gca().xaxis.set_major_locator(mdates.MonthLocator(interval=3))
+    plt.xticks(rotation=45)
+    
+    # Add legend if multiple columns
+    if len(data.columns) > 1:
+        plt.legend()
+    
+    plt.tight_layout()
+    
+    # Save if requested
+    if save_file:
+        plt.savefig(save_file, dpi=300, bbox_inches='tight')
+        print(f"💾 Plot saved as {save_file}")
+    
+    plt.show()
+    print("✅ Plot created successfully!")
+
+
+def plot_turbidity(turbidity_data: pd.DataFrame, save_file: str = None) -> None:
+    """
+    Create a turbidity-specific plot with appropriate formatting.
+    
+    Args:
+        turbidity_data (pd.DataFrame): DataFrame with turbidity values
+        save_file (str): Optional filename to save the plot
+    """
+    
+    if turbidity_data.empty:
+        print("❌ No turbidity data to plot")
+        return
+    
+    print("🌫️  Creating turbidity plot")
+    
+    plt.figure(figsize=(12, 6))
+    
+    # Plot turbidity
+    column_name = turbidity_data.columns[0]
+    plt.plot(turbidity_data.index, turbidity_data.iloc[:, 0], 
+             color='brown', linewidth=1.5, alpha=0.8)
+    
+    # Add threshold lines for water quality assessment
+    plt.axhline(y=10, color='orange', linestyle='--', alpha=0.7, label='Moderate (10 NTU)')
+    plt.axhline(y=25, color='red', linestyle='--', alpha=0.7, label='High (25 NTU)')
+    
+    # Format plot
+    plt.title('💧 Turbidity Time Series', fontsize=14, fontweight='bold', pad=20)
+    plt.xlabel('Date', fontsize=12)
+    plt.ylabel('Turbidity (NTU)', fontsize=12)
+    plt.grid(True, alpha=0.3)
+    
+    # Format x-axis
+    plt.gca().xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m'))
+    plt.xticks(rotation=45)
+    
+    plt.legend()
+    plt.tight_layout()
+    
+    # Save if requested
+    if save_file:
+        plt.savefig(save_file, dpi=300, bbox_inches='tight')
+        print(f"💾 Turbidity plot saved as {save_file}")
+    
+    plt.show()
+    print("✅ Turbidity plot created!")
+
+
+def plot_sentinel(sentinel_data: pd.DataFrame, save_file: str = None) -> None:
+    """
+    Create a Sentinel satellite data plot.
+    
+    Args:
+        sentinel_data (pd.DataFrame): DataFrame with Sentinel band values
+        save_file (str): Optional filename to save the plot
+    """
+    
+    if sentinel_data.empty:
+        print("❌ No Sentinel data to plot")
+        return
+    
+    print("🛰️  Creating Sentinel bands plot")
+    
+    plt.figure(figsize=(12, 8))
+    
+    # Define colors for different bands
+    band_colors = {
+        'B2': 'blue',    # Blue band
+        'B3': 'green',   # Green band  
+        'B4': 'red',     # Red band
+        'B8': 'darkred', # NIR band
+        'NDVI': 'darkgreen'
+    }
+    
+    # Plot each band
+    for column in sentinel_data.columns:
+        color = band_colors.get(column, 'black')
+        plt.plot(sentinel_data.index, sentinel_data[column], 
+                label=column, color=color, linewidth=2, marker='o', markersize=4)
+    
+    # Format plot
+    plt.title('🛰️ Sentinel Satellite Data', fontsize=14, fontweight='bold', pad=20)
+    plt.xlabel('Date', fontsize=12)
+    plt.ylabel('Digital Number / Index Value', fontsize=12)
+    plt.grid(True, alpha=0.3)
+    
+    # Format x-axis
+    plt.gca().xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m'))
+    plt.xticks(rotation=45)
+    
+    plt.legend()
+    plt.tight_layout()
+    
+    # Save if requested
+    if save_file:
+        plt.savefig(save_file, dpi=300, bbox_inches='tight')
+        print(f"💾 Sentinel plot saved as {save_file}")
+    
+    plt.show()
+    print("✅ Sentinel plot created!")
+
+
+def plot_comparison(data1: pd.DataFrame, data2: pd.DataFrame, 
+                   label1: str = "Dataset 1", label2: str = "Dataset 2",
+                   title: str = "Data Comparison", save_file: str = None) -> None:
+    """
+    Create a comparison plot of two time series datasets.
+    
+    Args:
+        data1 (pd.DataFrame): First dataset
+        data2 (pd.DataFrame): Second dataset
+        label1 (str): Label for first dataset
+        label2 (str): Label for second dataset
+        title (str): Plot title
+        save_file (str): Optional filename to save the plot
+    """
+    
+    if data1.empty and data2.empty:
+        print("❌ No data to plot")
+        return
+    
+    print(f"📊 Creating comparison plot: {title}")
+    
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(12, 10), sharex=True)
+    
+    # Plot first dataset
+    if not data1.empty:
+        ax1.plot(data1.index, data1.iloc[:, 0], color='blue', linewidth=1.5, alpha=0.8)
+        ax1.set_title(f'{label1}', fontsize=12, fontweight='bold')
+        ax1.set_ylabel('Value', fontsize=10)
+        ax1.grid(True, alpha=0.3)
+    
+    # Plot second dataset  
+    if not data2.empty:
+        ax2.plot(data2.index, data2.iloc[:, 0], color='red', linewidth=1.5, alpha=0.8)
+        ax2.set_title(f'{label2}', fontsize=12, fontweight='bold')
+        ax2.set_ylabel('Value', fontsize=10)
+        ax2.grid(True, alpha=0.3)
+    
+    # Format x-axis
+    ax2.xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m'))
+    plt.xticks(rotation=45)
+    ax2.set_xlabel('Date', fontsize=12)
+    
+    plt.suptitle(title, fontsize=14, fontweight='bold')
+    plt.tight_layout()
+    
+    # Save if requested
+    if save_file:
+        plt.savefig(save_file, dpi=300, bbox_inches='tight')
+        print(f"💾 Comparison plot saved as {save_file}")
+    
+    plt.show()
+    print("✅ Comparison plot created!")
+
+
+# Simple aliases
+plot = plot_timeseries
+visualize = plot_timeseries