downsampler 0.1.0__py3-none-any.whl

downsampler/fidelity/comparison.py

@@ -0,0 +1,343 @@
+"""Comparison engine for evaluating downsampling methods and cadences."""
+
+from dataclasses import dataclass, field
+from typing import Any
+import pandas as pd
+
+from downsampler.config import DownsampleConfig, AggregationMethod
+from downsampler.core import downsample
+from downsampler.fidelity.metrics import FidelityMetrics, compute_metrics, compute_reduction_ratio
+from downsampler.utils import parse_cadence
+
+
+@dataclass
+class ComparisonResult:
+    """Result of a single downsampling comparison.
+
+    Attributes:
+        method: The aggregation method used.
+        cadence: The target cadence.
+        metrics: Fidelity metrics for this result.
+        reduction_ratio: Data reduction ratio (original/downsampled rows).
+        config: The full configuration used.
+        downsampled: The downsampled DataFrame (optional, may be None if not stored).
+    """
+    method: AggregationMethod
+    cadence: pd.Timedelta
+    metrics: FidelityMetrics
+    reduction_ratio: float
+    config: DownsampleConfig
+    downsampled: pd.DataFrame | None = None
+
+    def to_dict(self) -> dict:
+        """Convert result to a dictionary."""
+        return {
+            'method': self.method.value,
+            'cadence': str(self.cadence),
+            'reduction_ratio': self.reduction_ratio,
+            **self.metrics.to_dict(),
+        }
+
+
+class FidelityComparison:
+    """Engine for comparing downsampling methods and cadences.
+
+    Example:
+        >>> original = pd.DataFrame(
+        ...     {'signal': np.sin(np.linspace(0, 10*np.pi, 10000))},
+        ...     index=pd.date_range('2024-01-01', periods=10000, freq='1s')
+        ... )
+        >>> comp = FidelityComparison(original, 'signal')
+        >>> results = comp.compare_methods('1min')
+        >>> for r in results:
+        ...     print(f"{r.method.value}: RMSE={r.metrics.rmse:.4f}")
+    """
+
+    def __init__(
+        self,
+        original_df: pd.DataFrame,
+        column: str,
+        peak_prominence: float | None = None
+    ):
+        """Initialize the comparison engine.
+
+        Args:
+            original_df: The original high-cadence DataFrame.
+            column: The column to use for comparisons.
+            peak_prominence: Minimum prominence for peak detection.
+        """
+        self.original_df = original_df
+        self.column = column
+        self.peak_prominence = peak_prominence
+        self._results: list[ComparisonResult] = []
+
+    def compare_methods(
+        self,
+        target_cadence: str | pd.Timedelta,
+        methods: list[AggregationMethod] | None = None,
+        lttb_target_column: str | None = None,
+        store_downsampled: bool = False
+    ) -> list[ComparisonResult]:
+        """Compare different downsampling methods at a fixed cadence.
+
+        Args:
+            target_cadence: Target cadence for all comparisons.
+            methods: List of methods to compare. If None, compares all methods.
+            lttb_target_column: Column to optimize for LTTB. Defaults to
+                the comparison column.
+            store_downsampled: Whether to store downsampled DataFrames in results.
+
+        Returns:
+            List of ComparisonResult objects.
+        """
+        target_cadence = parse_cadence(target_cadence)
+
+        if methods is None:
+            methods = list(AggregationMethod)
+
+        if lttb_target_column is None:
+            lttb_target_column = self.column
+
+        results = []
+        for method in methods:
+            config = DownsampleConfig(
+                method=method,
+                lttb_target_column=lttb_target_column if method == AggregationMethod.LTTB else None,
+            )
+
+            try:
+                downsampled = downsample(self.original_df, target_cadence, config)
+            except Exception as e:
+                # Log and skip failed methods
+                print(f"Warning: {method.value} failed: {e}")
+                continue
+
+            if len(downsampled) == 0:
+                continue
+
+            metrics = compute_metrics(
+                self.original_df,
+                downsampled,
+                self.column,
+                self.peak_prominence
+            )
+
+            reduction_ratio = compute_reduction_ratio(self.original_df, downsampled)
+
+            result = ComparisonResult(
+                method=method,
+                cadence=target_cadence,
+                metrics=metrics,
+                reduction_ratio=reduction_ratio,
+                config=config,
+                downsampled=downsampled if store_downsampled else None,
+            )
+            results.append(result)
+
+        self._results.extend(results)
+        return results
+
+    def compare_cadences(
+        self,
+        cadences: list[str | pd.Timedelta],
+        method: AggregationMethod = AggregationMethod.MEAN,
+        lttb_target_column: str | None = None,
+        store_downsampled: bool = False
+    ) -> list[ComparisonResult]:
+        """Compare different cadences using a fixed method.
+
+        Args:
+            cadences: List of target cadences to compare.
+            method: Downsampling method to use.
+            lttb_target_column: Column to optimize for LTTB.
+            store_downsampled: Whether to store downsampled DataFrames.
+
+        Returns:
+            List of ComparisonResult objects.
+        """
+        if lttb_target_column is None:
+            lttb_target_column = self.column
+
+        results = []
+        for cadence in cadences:
+            cadence = parse_cadence(cadence)
+
+            config = DownsampleConfig(
+                method=method,
+                lttb_target_column=lttb_target_column if method == AggregationMethod.LTTB else None,
+            )
+
+            try:
+                downsampled = downsample(self.original_df, cadence, config)
+            except Exception as e:
+                print(f"Warning: cadence {cadence} failed: {e}")
+                continue
+
+            if len(downsampled) == 0:
+                continue
+
+            metrics = compute_metrics(
+                self.original_df,
+                downsampled,
+                self.column,
+                self.peak_prominence
+            )
+
+            reduction_ratio = compute_reduction_ratio(self.original_df, downsampled)
+
+            result = ComparisonResult(
+                method=method,
+                cadence=cadence,
+                metrics=metrics,
+                reduction_ratio=reduction_ratio,
+                config=config,
+                downsampled=downsampled if store_downsampled else None,
+            )
+            results.append(result)
+
+        self._results.extend(results)
+        return results
+
+    def compare_grid(
+        self,
+        cadences: list[str | pd.Timedelta],
+        methods: list[AggregationMethod] | None = None,
+        lttb_target_column: str | None = None,
+        store_downsampled: bool = False
+    ) -> list[ComparisonResult]:
+        """Compare all combinations of cadences and methods.
+
+        Args:
+            cadences: List of target cadences.
+            methods: List of methods. If None, uses all methods.
+            lttb_target_column: Column to optimize for LTTB.
+            store_downsampled: Whether to store downsampled DataFrames.
+
+        Returns:
+            List of ComparisonResult objects.
+        """
+        if methods is None:
+            methods = list(AggregationMethod)
+
+        if lttb_target_column is None:
+            lttb_target_column = self.column
+
+        results = []
+        for cadence in cadences:
+            for method in methods:
+                cadence_parsed = parse_cadence(cadence)
+
+                config = DownsampleConfig(
+                    method=method,
+                    lttb_target_column=lttb_target_column if method == AggregationMethod.LTTB else None,
+                )
+
+                try:
+                    downsampled = downsample(self.original_df, cadence_parsed, config)
+                except Exception:
+                    continue
+
+                if len(downsampled) == 0:
+                    continue
+
+                metrics = compute_metrics(
+                    self.original_df,
+                    downsampled,
+                    self.column,
+                    self.peak_prominence
+                )
+
+                reduction_ratio = compute_reduction_ratio(self.original_df, downsampled)
+
+                result = ComparisonResult(
+                    method=method,
+                    cadence=cadence_parsed,
+                    metrics=metrics,
+                    reduction_ratio=reduction_ratio,
+                    config=config,
+                    downsampled=downsampled if store_downsampled else None,
+                )
+                results.append(result)
+
+        self._results.extend(results)
+        return results
+
+    def summary_table(self, results: list[ComparisonResult] | None = None) -> pd.DataFrame:
+        """Generate a summary table from comparison results.
+
+        Args:
+            results: List of results to summarize. If None, uses all
+                results from this comparison engine.
+
+        Returns:
+            DataFrame with metrics for each method/cadence combination.
+        """
+        if results is None:
+            results = self._results
+
+        if not results:
+            return pd.DataFrame()
+
+        rows = [r.to_dict() for r in results]
+        return pd.DataFrame(rows)
+
+    def recommend_settings(
+        self,
+        target_cadence: str | pd.Timedelta,
+        priority: str = "visual"
+    ) -> DownsampleConfig:
+        """Recommend downsampling settings based on comparison results.
+
+        Args:
+            target_cadence: Target cadence for the recommendation.
+            priority: Optimization priority:
+                - "visual": Minimize visual error (RMSE + peak_error)
+                - "peaks": Prioritize peak preservation
+                - "correlation": Maximize correlation
+                - "speed": Prefer simple aggregation methods
+
+        Returns:
+            Recommended DownsampleConfig.
+        """
+        target_cadence = parse_cadence(target_cadence)
+
+        # Run comparison if we don't have results for this cadence
+        relevant_results = [r for r in self._results if r.cadence == target_cadence]
+        if not relevant_results:
+            relevant_results = self.compare_methods(target_cadence)
+
+        if not relevant_results:
+            # Return default config if no results
+            return DownsampleConfig()
+
+        # Score each result based on priority
+        def score(r: ComparisonResult) -> float:
+            m = r.metrics
+            if priority == "visual":
+                # Lower is better for RMSE and peak_error
+                return m.rmse + 0.5 * m.peak_error
+            elif priority == "peaks":
+                # Closer to 1.0 is better for peak_count_ratio
+                return abs(1.0 - m.peak_count_ratio) + 0.1 * m.peak_error
+            elif priority == "correlation":
+                # Higher is better for pearson_r
+                return -m.pearson_r
+            elif priority == "speed":
+                # Prefer simple methods
+                method_penalty = {
+                    AggregationMethod.MEAN: 0,
+                    AggregationMethod.MIN: 0,
+                    AggregationMethod.MAX: 0,
+                    AggregationMethod.MEDIAN: 0.1,
+                    AggregationMethod.LTTB: 0.2,
+                }
+                return m.rmse + method_penalty.get(r.method, 0)
+            else:
+                return m.rmse
+
+        best = min(relevant_results, key=score)
+        return best.config
+
+    def clear_results(self):
+        """Clear stored comparison results."""
+        self._results = []

downsampler/fidelity/metrics.py

@@ -0,0 +1,212 @@
+"""Statistical metrics for evaluating downsampling fidelity."""
+
+from dataclasses import dataclass
+import numpy as np
+import pandas as pd
+from scipy import stats
+from scipy.signal import find_peaks
+
+
+@dataclass
+class FidelityMetrics:
+    """Metrics for evaluating the fidelity of downsampled data.
+
+    Attributes:
+        mae: Mean Absolute Error between original and interpolated downsampled.
+        rmse: Root Mean Square Error.
+        max_error: Maximum absolute error.
+        pearson_r: Pearson correlation coefficient.
+        peak_error: Mean absolute error at detected peaks.
+        peak_count_ratio: Ratio of peaks preserved (downsampled / original).
+        coverage: Fraction of original points that could be compared.
+    """
+    mae: float
+    rmse: float
+    max_error: float
+    pearson_r: float
+    peak_error: float
+    peak_count_ratio: float
+    coverage: float
+
+    def to_dict(self) -> dict:
+        """Convert metrics to a dictionary."""
+        return {
+            'mae': self.mae,
+            'rmse': self.rmse,
+            'max_error': self.max_error,
+            'pearson_r': self.pearson_r,
+            'peak_error': self.peak_error,
+            'peak_count_ratio': self.peak_count_ratio,
+            'coverage': self.coverage,
+        }
+
+    def __str__(self) -> str:
+        """Format metrics as a readable string."""
+        return (
+            f"FidelityMetrics(\n"
+            f"  MAE: {self.mae:.6f}\n"
+            f"  RMSE: {self.rmse:.6f}\n"
+            f"  Max Error: {self.max_error:.6f}\n"
+            f"  Pearson r: {self.pearson_r:.4f}\n"
+            f"  Peak Error: {self.peak_error:.6f}\n"
+            f"  Peak Count Ratio: {self.peak_count_ratio:.2%}\n"
+            f"  Coverage: {self.coverage:.2%}\n"
+            f")"
+        )
+
+
+def compute_metrics(
+    original: pd.DataFrame,
+    downsampled: pd.DataFrame,
+    column: str,
+    peak_prominence: float | None = None
+) -> FidelityMetrics:
+    """Compute fidelity metrics comparing original and downsampled data.
+
+    The downsampled data is interpolated back to the original timestamps
+    for comparison.
+
+    Args:
+        original: Original high-cadence DataFrame.
+        downsampled: Downsampled DataFrame.
+        column: Column name to compare.
+        peak_prominence: Minimum prominence for peak detection.
+            If None, auto-calculated as 10% of data range.
+
+    Returns:
+        FidelityMetrics containing various comparison metrics.
+
+    Example:
+        >>> original = pd.DataFrame(
+        ...     {'value': np.sin(np.linspace(0, 10*np.pi, 1000))},
+        ...     index=pd.date_range('2024-01-01', periods=1000, freq='1s')
+        ... )
+        >>> downsampled = original.resample('10s').mean()
+        >>> metrics = compute_metrics(original, downsampled, 'value')
+        >>> metrics.pearson_r > 0.9
+        True
+    """
+    # Get original values
+    orig_values = original[column].dropna()
+    if len(orig_values) == 0:
+        return _empty_metrics()
+
+    # Interpolate downsampled to original timestamps
+    ds_values = downsampled[column].dropna()
+    if len(ds_values) < 2:
+        return _empty_metrics()
+
+    # Create interpolated values at original timestamps
+    orig_times_numeric = (orig_values.index - orig_values.index[0]) / pd.Timedelta('1s')
+    ds_times_numeric = (ds_values.index - orig_values.index[0]) / pd.Timedelta('1s')
+
+    # Only interpolate within the range of downsampled data
+    mask = (orig_values.index >= ds_values.index[0]) & (orig_values.index <= ds_values.index[-1])
+    orig_in_range = orig_values[mask]
+    orig_times_in_range = orig_times_numeric[mask]
+
+    if len(orig_in_range) == 0:
+        return _empty_metrics()
+
+    interpolated = np.interp(
+        orig_times_in_range.values,
+        ds_times_numeric.values,
+        ds_values.values
+    )
+
+    # Compute basic metrics
+    errors = orig_in_range.values - interpolated
+    mae = np.mean(np.abs(errors))
+    rmse = np.sqrt(np.mean(errors**2))
+    max_error = np.max(np.abs(errors))
+
+    # Pearson correlation
+    if len(orig_in_range) > 1 and np.std(orig_in_range.values) > 0 and np.std(interpolated) > 0:
+        pearson_r, _ = stats.pearsonr(orig_in_range.values, interpolated)
+    else:
+        pearson_r = 1.0 if np.allclose(orig_in_range.values, interpolated) else 0.0
+
+    # Peak analysis
+    if peak_prominence is None:
+        data_range = np.max(orig_values.values) - np.min(orig_values.values)
+        peak_prominence = 0.1 * data_range if data_range > 0 else 0.1
+
+    orig_peaks, _ = find_peaks(orig_values.values, prominence=peak_prominence)
+    ds_peaks, _ = find_peaks(ds_values.values, prominence=peak_prominence)
+
+    # Peak count ratio
+    if len(orig_peaks) > 0:
+        peak_count_ratio = len(ds_peaks) / len(orig_peaks)
+    else:
+        peak_count_ratio = 1.0 if len(ds_peaks) == 0 else float('inf')
+
+    # Peak error (error at original peak locations)
+    if len(orig_peaks) > 0:
+        peak_times_numeric = orig_times_numeric.values[orig_peaks]
+        peak_interpolated = np.interp(peak_times_numeric, ds_times_numeric.values, ds_values.values)
+        peak_errors = orig_values.values[orig_peaks] - peak_interpolated
+        peak_error = np.mean(np.abs(peak_errors))
+    else:
+        peak_error = 0.0
+
+    # Coverage
+    coverage = len(orig_in_range) / len(orig_values)
+
+    return FidelityMetrics(
+        mae=mae,
+        rmse=rmse,
+        max_error=max_error,
+        pearson_r=pearson_r,
+        peak_error=peak_error,
+        peak_count_ratio=peak_count_ratio,
+        coverage=coverage,
+    )
+
+
+def _empty_metrics() -> FidelityMetrics:
+    """Return empty/NaN metrics when comparison isn't possible."""
+    return FidelityMetrics(
+        mae=np.nan,
+        rmse=np.nan,
+        max_error=np.nan,
+        pearson_r=np.nan,
+        peak_error=np.nan,
+        peak_count_ratio=np.nan,
+        coverage=0.0,
+    )
+
+
+def compute_reduction_ratio(
+    original: pd.DataFrame,
+    downsampled: pd.DataFrame
+) -> float:
+    """Compute the data reduction ratio.
+
+    Args:
+        original: Original DataFrame.
+        downsampled: Downsampled DataFrame.
+
+    Returns:
+        Ratio of original rows to downsampled rows.
+    """
+    if len(downsampled) == 0:
+        return float('inf')
+    return len(original) / len(downsampled)
+
+
+def compute_storage_savings(
+    original: pd.DataFrame,
+    downsampled: pd.DataFrame
+) -> float:
+    """Compute storage savings as a percentage.
+
+    Args:
+        original: Original DataFrame.
+        downsampled: Downsampled DataFrame.
+
+    Returns:
+        Percentage of storage saved (0-100).
+    """
+    if len(original) == 0:
+        return 0.0
+    return 100 * (1 - len(downsampled) / len(original))