PBstats 0.1.0__py3-none-any.whl

PBstats/__init__.py

@@ -0,0 +1,5 @@
+from PBstats.core.data import Data
+from PBstats.core.pipeline import Pipeline, FunctionalPipeline
+
+__version__ = "0.1.0"
+__all__ = ["Data", "Pipeline", "FunctionalPipeline"]

PBstats/core/base.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+import numpy as np
+
+@dataclass
+class FFTResult:
+    freqs: np.ndarray        # frequency axis in Hz
+    magnitude: np.ndarray   # magnitude spectrum
+    phase: np.ndarray        # phase spectrum in radians
+    power: np.ndarray        # power spectrum (magnitude²)
+    fs: float                # sampling frequency used
+    label: str = ""
+
+    def peak_frequency(self) -> float:
+        """Return the frequency with highest magnitude."""
+        return float(self.freqs[np.argmax(self.magnitude)])
+
+    def band_power(self, low: float, high: float) -> float:
+        """Total power within a frequency band [low, high] Hz."""
+        mask = (self.freqs >= low) & (self.freqs <= high)
+        return float(self.power[mask].sum())
+
+    def dominant_bands(self, n: int = 3) -> list[tuple[float, float]]:
+        """Return the n frequencies with highest power."""
+        idx = np.argsort(self.magnitude)[::-1][:n]
+        return [(float(self.freqs[i]), float(self.magnitude[i])) for i in idx]
+
+
+@dataclass
+class HilbertResult:
+    analytic: np.ndarray     # complex analytic signal
+    envelope: np.ndarray     # amplitude envelope (instantaneous amplitude)
+    phase: np.ndarray        # instantaneous phase (radians)
+    frequency: np.ndarray    # instantaneous frequency (Hz)
+    fs: float
+    label: str = ""
+
+    def mean_envelope(self) -> float:
+        return float(self.envelope.mean())
+
+    def peak_envelope(self) -> float:
+        return float(self.envelope.max())
+
+
+@dataclass
+class WaveletResult:
+    coefficients: np.ndarray  # 2D array: (scales, time)
+    freqs: np.ndarray          # frequency axis
+    times: np.ndarray          # time axis
+    scales: np.ndarray
+    wavelet: str
+    label: str = ""
+
+    def scalogram(self) -> np.ndarray:
+        """Return power scalogram (|coefficients|²)."""
+        return np.abs(self.coefficients) ** 2
+
+
+@dataclass
+class STFTResult:
+    freqs: np.ndarray          # frequency axis
+    times: np.ndarray          # time axis
+    Zxx: np.ndarray            # complex STFT matrix
+    magnitude: np.ndarray      # |Zxx|
+    fs: float
+    label: str = ""
+
+    def spectrogram(self) -> np.ndarray:
+        """Power spectrogram in dB."""
+        power = np.abs(self.Zxx) ** 2
+        return 10 * np.log10(power + 1e-12)

PBstats/core/data.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+import numpy as np
+import pandas as pd
+from typing import Union, Optional
+
+from PBstats.preprocessing.cleaning      import CleaningMixin
+from PBstats.preprocessing.normalization import NormalizationMixin
+from PBstats.preprocessing.outliers      import OutlierMixin
+from PBstats.preprocessing.imputation    import ImputationMixin
+from PBstats.transforms.fft              import FFTMixin
+from PBstats.transforms.hilbert          import HilbertMixin
+from PBstats.transforms.wavelet          import WaveletMixin
+from PBstats.transforms.stft             import STFTMixin
+from PBstats.statistics.descriptive      import DescriptiveMixin
+from PBstats.statistics.hypothesis       import HypothesisMixin
+from PBstats.statistics.regression       import RegressionMixin
+from PBstats.statistics.correlation      import CorrelationMixin
+from PBstats.visualization.spectrum      import VisualizationMixin
+
+ArrayLike = Union[np.ndarray, pd.Series, pd.DataFrame, list]
+
+class Data(
+    CleaningMixin, NormalizationMixin, OutlierMixin, ImputationMixin,
+    FFTMixin, HilbertMixin, WaveletMixin, STFTMixin,
+    DescriptiveMixin, HypothesisMixin, RegressionMixin, CorrelationMixin,
+    VisualizationMixin,
+):
+    def __init__(
+        self,
+        data: ArrayLike,
+        fs: Optional[float] = None,
+        label: str = "",
+    ):
+        self._raw  = self._coerce(data)
+        self.data  = self._raw.copy()
+        self.fs    = fs
+        self.label = label
+        self._log: list[str] = []
+
+    def _coerce(self, data: ArrayLike) -> np.ndarray:
+        if isinstance(data, pd.DataFrame):
+            return data.to_numpy()
+        if isinstance(data, pd.Series):
+            return data.to_numpy()
+        return np.asarray(data, dtype=float)
+
+    def _record(self, step: str) -> None:
+        self._log.append(step)
+
+    def reset(self) -> "Data":
+        self.data = self._raw.copy()
+        self._log.clear()
+        return self
+
+    def history(self) -> list[str]:
+        return self._log.copy()
+
+    def to_numpy(self) -> np.ndarray:
+        return self.data.copy()
+
+    def to_series(self) -> pd.Series:
+        return pd.Series(self.data.flatten(), name=self.label)
+
+    def __repr__(self) -> str:
+        return (
+            f"Data(shape={self.data.shape}, fs={self.fs}, "
+            f"steps={len(self._log)})"
+        )

PBstats/core/pipeline.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+import json
+import time
+import numpy as np
+from typing import Callable, Any
+from dataclasses import dataclass, field
+
+
+@dataclass
+class PipelineStep:
+    """One step in the pipeline — a method name + its kwargs."""
+    name: str                        # e.g. "remove_dc"
+    kwargs: dict = field(default_factory=dict)
+    duration_ms: float = 0.0        # filled after execution
+    records: str = ""               # filled from Data._log
+
+
+class Pipeline:
+    """
+    Define a preprocessing + transform workflow once.
+    Apply it to any number of Data objects reproducibly.
+
+    Usage
+    -----
+    pipe = (
+        Pipeline("ecg_clean")
+        .add("remove_missing", strategy="interpolate")
+        .add("remove_dc")
+        .add("remove_outliers", method="mad", threshold=3.0)
+        .add("standardize")
+        .add("hilbert")
+    )
+
+    result = pipe.run(Data(signal, fs=1000))
+    result2 = pipe.run(Data(new_signal, fs=1000))   # same steps, new data
+
+    pipe.save("ecg_pipeline.json")
+    pipe2 = Pipeline.load("ecg_pipeline.json")
+    """
+
+    def __init__(self, name: str = "pipeline"):
+        self.name  = name
+        self.steps: list[PipelineStep] = []
+        self._run_log: list[dict] = []     # history of all .run() calls
+
+    # ── building ────────────────────────────────────────────────────────────
+
+    def add(self, name: str, **kwargs) -> "Pipeline":
+        """
+        Add a step by method name.
+        The name must match a method on the Data class exactly.
+
+        Example
+        -------
+        pipe.add("remove_outliers", method="mad", threshold=3.5)
+        """
+        self.steps.append(PipelineStep(name=name, kwargs=kwargs))
+        return self
+
+    def __len__(self) -> int:
+        return len(self.steps)
+
+    def __repr__(self) -> str:
+        step_names = " → ".join(s.name for s in self.steps)
+        return f"Pipeline('{self.name}', steps=[{step_names}])"
+
+    # ── execution ───────────────────────────────────────────────────────────
+
+    def run(self, data_obj, verbose: bool = False) -> Any:
+        """
+        Execute all steps on a Data object in order.
+
+        Parameters
+        ----------
+        data_obj : a pallabstats.Data instance
+        verbose  : if True, print each step as it runs
+
+        Returns
+        -------
+        The same Data object after all transforms applied.
+        """
+        self._validate_steps(data_obj)
+
+        run_record = {
+            "pipeline": self.name,
+            "label": data_obj.label,
+            "steps": [],
+            "total_ms": 0.0,
+        }
+
+        for step in self.steps:
+            method = getattr(data_obj, step.name)
+
+            t_start = time.perf_counter()
+            method(**step.kwargs)
+            t_end   = time.perf_counter()
+
+            step.duration_ms = (t_end - t_start) * 1000
+
+            if verbose:
+                print(f"  [{step.duration_ms:6.2f} ms]  {step.name}({step.kwargs})")
+
+            run_record["steps"].append({
+                "step":        step.name,
+                "kwargs":      step.kwargs,
+                "duration_ms": round(step.duration_ms, 3),
+            })
+
+        run_record["total_ms"] = sum(
+            s["duration_ms"] for s in run_record["steps"]
+        )
+        self._run_log.append(run_record)
+
+        return data_obj
+
+    def _validate_steps(self, data_obj) -> None:
+        """Check all step names exist on the Data class before running."""
+        missing = [
+            s.name for s in self.steps
+            if not hasattr(data_obj, s.name)
+        ]
+        if missing:
+            raise AttributeError(
+                f"Pipeline '{self.name}' has steps not found on Data: {missing}\n"
+                f"Check spelling — available methods: "
+                f"{[m for m in dir(data_obj) if not m.startswith('_')]}"
+            )
+
+    # ── batch processing ─────────────────────────────────────────────────────
+
+    def run_batch(
+        self,
+        data_list: list,
+        verbose: bool = False,
+        on_error: str = "raise",
+    ) -> list:
+        """
+        Run the pipeline on a list of Data objects.
+
+        Parameters
+        ----------
+        data_list : list of Data instances
+        verbose   : print progress
+        on_error  : 'raise' — stop on first error (default)
+                    'skip'  — log error, continue with next sample
+                    'warn'  — print warning, continue
+
+        Returns
+        -------
+        List of processed Data objects (failed ones excluded if on_error != 'raise')
+        """
+        results = []
+        errors  = []
+
+        for i, d in enumerate(data_list):
+            label = getattr(d, "label", f"sample_{i}")
+            try:
+                if verbose:
+                    print(f"\nProcessing [{i+1}/{len(data_list)}]: {label}")
+                results.append(self.run(d, verbose=verbose))
+
+            except Exception as e:
+                msg = f"Error on '{label}': {type(e).__name__}: {e}"
+                errors.append({"label": label, "error": msg})
+
+                if on_error == "raise":
+                    raise
+                elif on_error == "warn":
+                    print(f"  WARNING — {msg}")
+                elif on_error == "skip":
+                    pass
+
+        if errors and on_error != "raise":
+            print(f"\nBatch complete: {len(results)} succeeded, "
+                  f"{len(errors)} failed.")
+
+        return results
+
+    # ── timing report ────────────────────────────────────────────────────────
+
+    def timing_report(self) -> dict:
+        """
+        Return per-step average timing across all .run() calls.
+        Useful for finding bottlenecks in long pipelines.
+        """
+        if not self._run_log:
+            return {}
+
+        step_times: dict[str, list[float]] = {}
+        for run in self._run_log:
+            for s in run["steps"]:
+                step_times.setdefault(s["step"], []).append(s["duration_ms"])
+
+        return {
+            step: {
+                "mean_ms": round(np.mean(times), 3),
+                "max_ms":  round(np.max(times), 3),
+                "n_runs":  len(times),
+            }
+            for step, times in step_times.items()
+        }
+
+    # ── persistence ──────────────────────────────────────────────────────────
+
+    def save(self, path: str) -> None:
+        """
+        Save pipeline definition to JSON.
+        This saves the step names and kwargs — not the data.
+        Load it later with Pipeline.load(path).
+        """
+        payload = {
+            "name":  self.name,
+            "steps": [
+                {"name": s.name, "kwargs": s.kwargs}
+                for s in self.steps
+            ],
+        }
+        with open(path, "w") as f:
+            json.dump(payload, f, indent=2)
+        print(f"Pipeline saved → {path}")
+
+    @classmethod
+    def load(cls, path: str) -> "Pipeline":
+        """Load a pipeline from a saved JSON file."""
+        with open(path) as f:
+            payload = json.load(f)
+
+        pipe = cls(name=payload["name"])
+        for step in payload["steps"]:
+            pipe.add(step["name"], **step["kwargs"])
+
+        print(f"Pipeline loaded: {pipe}")
+        return pipe
+
+    # ── introspection ────────────────────────────────────────────────────────
+
+    def summary(self) -> None:
+        """Print a readable summary of all pipeline steps."""
+        print(f"\nPipeline: '{self.name}'  ({len(self.steps)} steps)")
+        print("─" * 48)
+        for i, step in enumerate(self.steps, 1):
+            kwargs_str = ", ".join(f"{k}={v!r}" for k, v in step.kwargs.items())
+            print(f"  {i:2d}. {step.name}({kwargs_str})")
+        print("─" * 48)
+class FunctionalPipeline(Pipeline):
+    """
+    Extended pipeline that supports arbitrary callables as steps.
+
+    Useful when you need a custom transform that isn't a Data method yet.
+
+    Example
+    -------
+    def my_bandpass(data_obj):
+        from scipy.signal import butter, filtfilt
+        b, a = butter(4, [40, 60], btype='band', fs=data_obj.fs)
+        data_obj.data = filtfilt(b, a, data_obj.data)
+        data_obj._record("custom_bandpass(40-60Hz)")
+        return data_obj
+
+    pipe = (
+        FunctionalPipeline("custom")
+        .add("remove_dc")
+        .add_fn(my_bandpass, name="bandpass_40_60")
+        .add("standardize")
+    )
+    """
+
+    def __init__(self, name: str = "pipeline"):
+        super().__init__(name)
+        self._fn_registry: dict[str, Callable] = {}
+
+    def add_fn(self, fn: Callable, name: str = None) -> "FunctionalPipeline":
+        """Add an arbitrary callable as a pipeline step."""
+        step_name = name or fn.__name__
+        self._fn_registry[step_name] = fn
+        self.steps.append(PipelineStep(name=step_name, kwargs={}))
+        return self
+
+    def run(self, data_obj, verbose: bool = False):
+        self._validate_steps_fn(data_obj)
+
+        for step in self.steps:
+            t_start = time.perf_counter()
+
+            if step.name in self._fn_registry:
+                self._fn_registry[step.name](data_obj)
+            else:
+                getattr(data_obj, step.name)(**step.kwargs)
+
+            step.duration_ms = (time.perf_counter() - t_start) * 1000
+            if verbose:
+                print(f"  [{step.duration_ms:6.2f} ms]  {step.name}")
+
+        return data_obj
+
+    def _validate_steps_fn(self, data_obj) -> None:
+        missing = [
+            s.name for s in self.steps
+            if not hasattr(data_obj, s.name)
+            and s.name not in self._fn_registry
+        ]
+        if missing:
+            raise AttributeError(f"Steps not found: {missing}")

PBstats/preprocessing/__init__.py

@@ -0,0 +1,10 @@
+from PBstats.preprocessing.cleaning import CleaningMixin
+from PBstats.preprocessing.normalization import NormalizationMixin
+from PBstats.preprocessing.outliers import OutlierMixin
+from PBstats.preprocessing.imputation import ImputationMixin
+__all__ = [
+    "CleaningMixin",
+    "NormalizationMixin",
+    "OutlierMixin",
+    "ImputationMixin",
+]

PBstats/preprocessing/cleaning.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+import numpy as np
+
+class CleaningMixin:
+    """
+    Methods: remove_missing, remove_dc, clip
+    Each mutates self.data, records the step, returns self.
+    """
+
+    def remove_missing(self, strategy: str = "interpolate") -> "CleaningMixin":
+        """
+        Replace NaN values in the signal.
+
+        Parameters
+        ----------
+        strategy : 'interpolate' — linear interpolation between neighbours
+                   'zero'        — replace with 0
+                   'mean'        — replace with signal mean
+                   'drop'        — remove NaN positions entirely
+        """
+        x = self.data.astype(float)
+
+        if strategy == "interpolate":
+            nan_mask = np.isnan(x)
+            if nan_mask.any():
+                indices = np.arange(len(x))
+                x[nan_mask] = np.interp(
+                    indices[nan_mask],
+                    indices[~nan_mask],
+                    x[~nan_mask]
+                )
+
+        elif strategy == "zero":
+            x = np.nan_to_num(x, nan=0.0)
+
+        elif strategy == "mean":
+            mean_val = np.nanmean(x)
+            x = np.where(np.isnan(x), mean_val, x)
+
+        elif strategy == "drop":
+            x = x[~np.isnan(x)]
+
+        else:
+            raise ValueError(f"Unknown strategy '{strategy}'. "
+                             f"Choose: interpolate, zero, mean, drop")
+
+        self.data = x
+        self._record(f"remove_missing(strategy={strategy})")
+        return self
+
+    def remove_dc(self) -> "CleaningMixin":
+        """
+        Subtract the mean (remove DC offset).
+        Essential for spectral analysis — DC shows up as a massive
+        spike at 0 Hz in FFT if not removed.
+        """
+        self.data = self.data - np.mean(self.data)
+        self._record("remove_dc()")
+        return self
+
+    def clip(self, low: float, high: float) -> "CleaningMixin":
+        """
+        Hard-clip values to [low, high].
+        Useful for removing sensor saturation artifacts.
+        """
+        self.data = np.clip(self.data, low, high)
+        self._record(f"clip(low={low}, high={high})")
+        return self

PBstats/preprocessing/imputation.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+import numpy as np
+
+class ImputationMixin:
+    """
+    Methods: impute
+    More sophisticated missing value handling for 2D (tabular) data.
+    For 1D signals, remove_missing() in CleaningMixin is sufficient.
+    """
+
+    def impute(self, method: str = "mean") -> "ImputationMixin":
+        """
+        Fill NaNs in a 2D array column-by-column.
+
+        Parameters
+        ----------
+        method : 'mean'   — fill with column mean
+                 'median' — fill with column median
+                 'ffill'  — forward-fill (carry last valid value forward)
+                 'bfill'  — backward-fill
+        """
+        if self.data.ndim == 1:
+            # Redirect 1D to the simpler cleaner
+            return self.remove_missing(
+                strategy="interpolate" if method in ("ffill","bfill") else method
+            )
+
+        x = self.data.astype(float)
+
+        for col in range(x.shape[1]):
+            column = x[:, col]
+            nan_mask = np.isnan(column)
+            if not nan_mask.any():
+                continue
+
+            if method == "mean":
+                column[nan_mask] = np.nanmean(column)
+            elif method == "median":
+                column[nan_mask] = np.nanmedian(column)
+            elif method == "ffill":
+                # Vectorized ffill: mask valid indices, then use ffill logic
+                mask = ~nan_mask
+                idx = np.where(mask, np.arange(len(column)), 0)
+                np.maximum.accumulate(idx, out=idx)
+                column[:] = column[idx]
+            elif method == "bfill":
+                # Vectorized bfill: reverse, ffill, reverse
+                mask = ~nan_mask
+                idx = np.where(mask, np.arange(len(column)), len(column) - 1)
+                # Reverse accumulation for bfill
+                idx = len(column) - 1 - np.maximum.accumulate((len(column) - 1 - idx)[::-1])[::-1]
+                column[:] = column[idx]
+            else:
+                raise ValueError(f"Unknown method '{method}'. "
+                                 f"Choose: mean, median, ffill, bfill")
+            x[:, col] = column
+
+        self.data = x
+        self._record(f"impute(method={method})")
+        return self

PBstats/preprocessing/normalization.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+import numpy as np
+
+class NormalizationMixin:
+    """
+    Methods: normalize, standardize, minmax, robust_scale
+    """
+
+    def normalize(self, method: str = "minmax") -> "NormalizationMixin":
+        """
+        Convenience wrapper — calls the right method by name.
+
+        Parameters
+        ----------
+        method : 'minmax'  — scale to [0, 1]
+                 'zscore'  — zero mean, unit variance
+                 'robust'  — median and IQR based (outlier-resistant)
+                 'l2'      — divide by L2 norm (unit vector)
+        """
+        dispatch = {
+            "minmax": self.minmax,
+            "zscore": self.standardize,
+            "robust": self.robust_scale,
+            "l2":     self._l2_norm,
+        }
+        if method not in dispatch:
+            raise ValueError(f"Unknown method '{method}'. "
+                             f"Choose: {list(dispatch)}")
+        return dispatch[method]()
+
+    def minmax(self) -> "NormalizationMixin":
+        """Scale to [0, 1]."""
+        x = self.data
+        xmin, xmax = x.min(), x.max()
+        if xmax == xmin:
+            self.data = np.zeros_like(x)
+        else:
+            self.data = (x - xmin) / (xmax - xmin)
+        self._record("minmax()")
+        return self
+
+    def standardize(self) -> "NormalizationMixin":
+        """Zero mean, unit variance (z-score normalization)."""
+        x = self.data
+        std = x.std()
+        if std == 0:
+            self.data = np.zeros_like(x)
+        else:
+            self.data = (x - x.mean()) / std
+        self._record("standardize()")
+        return self
+
+    def robust_scale(self) -> "NormalizationMixin":
+        """
+        Scale using median and IQR instead of mean and std.
+        Much better for biomedical data with spikes or outliers.
+        """
+        x = self.data
+        median = np.median(x)
+        q75, q25 = np.percentile(x, [75, 25])
+        iqr = q75 - q25
+        if iqr == 0:
+            self.data = np.zeros_like(x)
+        else:
+            self.data = (x - median) / iqr
+        self._record("robust_scale()")
+        return self
+
+    def _l2_norm(self) -> "NormalizationMixin":
+        """Divide by L2 norm — makes the signal a unit vector."""
+        norm = np.linalg.norm(self.data)
+        if norm == 0:
+            self.data = np.zeros_like(self.data)
+        else:
+            self.data = self.data / norm
+        self._record("l2_norm()")
+        return self