featuregraph-smoothing-core 1.0.0__py3-none-any.whl

featuregraph_smoothing_core/__init__.py

@@ -0,0 +1,10 @@
+from featuregraph_smoothing_core import datasets
+from featuregraph_smoothing_core import validation
+from featuregraph_smoothing_core.plot import (
+    plot,
+    plot_annotated_oscillation,
+    plot_oscillation_panel,
+    add_construction_legend,
+)
+
+__all__ = ["datasets", "validation", "plot", "plot_annotated_oscillation", "plot_oscillation_panel", "add_construction_legend"]

featuregraph_smoothing_core/behaviors/oscillation.py

@@ -0,0 +1,101 @@
+from dataclasses import dataclass
+from featuregraph_smoothing_core.operators.states import rising_state, falling_state
+from featuregraph_smoothing_core.operators.events import enter_state, exit_state, event_id, event_index
+from featuregraph_smoothing_core.operators.measures import smooth, smooth_grouped
+
+import pandas as pd
+import numpy as np
+
+@dataclass
+class OscillationConfig:
+    signal: str
+    eps: float = 0
+    lag: int = 1
+    smooth_window: int = 100
+
+    @property
+    def smooth(self):
+        return f'{self.signal}_smooth'
+
+    @property
+    def rising_col(self):
+        return f'{self.signal}_rising'
+
+    @property
+    def falling_col(self):
+        return f'{self.signal}_falling'
+
+    @property
+    def enter_rising_col(self):
+        return f'enter_{self.signal}_rising'
+
+    @property
+    def exit_rising_col(self):
+        return f'exit_{self.signal}_rising'
+
+    @property
+    def peak_event_id_col(self):
+        return f'{self.signal}_peak_event_id'
+
+    @property
+    def trough_event_id_col(self):
+        return f'{self.signal}_trough_event_id'
+
+    @property
+    def peak_index_col(self):
+        return f'{self.signal}_peak_index'
+
+    @property
+    def trough_index_col(self):
+        return f'{self.signal}_trough_index'
+
+    def add_primitives(self, df: pd.DataFrame, group=None):
+        df = df.copy()
+        df[self.smooth] = smooth_grouped(df, self.signal, window=self.smooth_window, group=group)
+        df[self.rising_col] = rising_state(df[self.smooth])
+        df[self.falling_col] = falling_state(df[self.smooth])
+        df[self.exit_rising_col] = exit_state(df[self.rising_col], group=df[group] if group else None)
+        df[self.enter_rising_col] = enter_state(df[self.rising_col], group=df[group] if group else None)
+        df[self.peak_event_id_col] = event_id(df, self.exit_rising_col, group=group)
+        df[self.trough_event_id_col] = event_id(df, self.enter_rising_col, group=group)
+        df[self.peak_index_col] = event_index(df, self.exit_rising_col, group=group)
+        df[self.trough_index_col] = event_index(df, self.enter_rising_col, group=group)
+        return df
+
+    def summarize(self, df: pd.DataFrame, group=None):
+        summarydf = df.groupby(group).agg(
+            start_index=(self.trough_index_col, 'first'),
+            rising_duration=(self.rising_col, 'sum'),
+            falling_duration=(self.falling_col, 'sum'),
+            peak_index=(self.peak_index_col, 'last'),
+            trough_index=(self.trough_index_col, 'first'),
+            max_raw_signal=(self.signal, 'max'),
+            max_smooth_signal=(self.smooth, 'max'),
+            min_raw_signal=(self.signal, 'min'),
+            min_smooth_signal=(self.smooth, 'min'),
+        )
+
+        summarydf['end_index'] = summarydf.groupby(level=0)['start_index'].shift(-1)
+        summarydf['is_complete'] = summarydf['start_index'].notna() & summarydf['end_index'].notna()
+        summarydf['duration'] = summarydf['rising_duration'] + summarydf['falling_duration']
+
+        if not group:
+            summarydf['period'] = summarydf['peak_index'].diff()
+        else:
+            summarydf['period'] = summarydf.groupby(group[0])['peak_index'].diff()
+
+        net_change_raw = (summarydf['max_raw_signal'] - summarydf['min_raw_signal'])
+        net_change_smooth = (summarydf['max_smooth_signal'] - summarydf['min_smooth_signal'])
+
+        summarydf['amplitude_raw'] =  net_change_raw / 2
+        summarydf['amplitude_smooth'] = net_change_smooth / 2
+
+        summarydf['raw_rising_mean_rate'] = (net_change_raw / summarydf['rising_duration']).where(summarydf['rising_duration'] > 0)
+        summarydf['raw_falling_mean_rate'] = (net_change_raw / summarydf['falling_duration']).where(summarydf['falling_duration'] > 0)
+
+        summarydf['smooth_rising_mean_rate'] = (net_change_smooth / summarydf['rising_duration']).where(summarydf['rising_duration'] > 0)
+        summarydf['smooth_falling_mean_rate'] = (net_change_smooth / summarydf['falling_duration']).where(summarydf['falling_duration'] > 0)
+
+        summarydf["temporal_symmetry"] = (1 - (summarydf['rising_duration'] - summarydf['falling_duration']).abs() / summarydf['duration']).where(summarydf['duration'] > 0)
+
+        return summarydf

featuregraph_smoothing_core/datasets/__init__.py

@@ -0,0 +1,3 @@
+from featuregraph_smoothing_core.datasets._bidmc import bidmc, bidmc_breaths
+
+__all__ = ["bidmc", "bidmc_breaths"]

featuregraph_smoothing_core/datasets/_bidmc.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import pandas as pd
+
+from featuregraph_smoothing_core.utils._bidmc import (
+    load_bidmc_breaths,
+    load_bidmc_subject,
+)
+from featuregraph_smoothing_core.utils._rename_map import bidmc_map
+
+
+def bidmc(
+    subject: int = 1,
+    *,
+    refresh: bool = False,
+) -> pd.DataFrame:
+    """
+    Load one BIDMC subject.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Physiological waveform observations with standardized
+        FeatureGraph column names.
+    """
+    return (
+        load_bidmc_subject(
+            subject,
+            refresh=refresh,
+        )
+        .rename(columns=bidmc_map)
+    )
+
+
+def bidmc_breaths(
+    subject: int = 1,
+    *,
+    refresh: bool = False,
+) -> pd.DataFrame:
+    """Load the two BIDMC breath-annotation columns for one subject."""
+    return load_bidmc_breaths(
+        subject,
+        refresh=refresh,
+    )

featuregraph_smoothing_core/operators/events.py

@@ -0,0 +1,27 @@
+import pandas as pd
+import numpy as np
+
+def enter_state(state, group=None):
+    x = state.astype(int)
+    if group is None:
+        return x.diff().eq(1)
+    return x.groupby(group).diff().eq(1)
+
+
+def exit_state(state, group=None):
+    x = state.astype(int)
+    if group is None:
+        return x.diff().eq(-1)
+    return x.groupby(group).diff().eq(-1)
+
+
+def event_id(df, enter_col, group=None):
+    if group is None:
+        return df[enter_col].cumsum()
+    return df.groupby(group)[enter_col].cumsum()
+
+def event_index(df, event_col, group=None):
+    event_positions = pd.Series(np.where(df[event_col], df.index, np.nan), index=df.index)
+    if group is None:
+        return event_positions.ffill()
+    return event_positions.groupby(df[group]).ffill()

featuregraph_smoothing_core/operators/measures.py

@@ -0,0 +1,13 @@
+def smooth(signal, window):
+    return (
+        signal.rolling(center=True, window=window).median().rolling(center=True, window=window).mean()
+    )
+
+def smooth_grouped(df, signal_col, window, group):
+    return df.groupby(group)[signal_col].transform(lambda s: smooth(s, window))
+
+def group_transform(df, signal, op, group):
+    return df.groupby(group)[signal].transform(op)
+
+def group_map(df, signal, op, group, offset=0):
+    return df[group].map(df.groupby(group)[signal].agg(op).shift(offset))

featuregraph_smoothing_core/operators/states.py

@@ -0,0 +1,30 @@
+def positive_state(quantity, eps=0):
+    return quantity.gt(eps)
+
+
+def negative_state(quantity, eps=0):
+    return quantity.lt(-eps)
+
+
+def inactive_state(quantity, eps=0):
+    return quantity.abs().le(eps)
+
+
+def rising_state(series, lag=1, eps=0):
+    return positive_state(series.diff(lag), eps)
+
+
+def falling_state(series, lag=1, eps=0):
+    return negative_state(series.diff(lag), eps)
+
+
+def stable_state(series, lag=1, eps=0):
+    return inactive_state(series.diff(lag), eps)
+
+
+def accumulating_state(contribution, eps=0):
+    return positive_state(contribution, eps)
+
+
+def depleting_state(contribution, eps=0):
+    return negative_state(contribution, eps)

featuregraph_smoothing_core/plot.py

@@ -0,0 +1,460 @@
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import pandas as pd
+
+def plot(
+    df: pd.DataFrame,
+    rows: list[list[str]],
+    *,
+    figsize: tuple[float, float] | None = None,
+    sharex: bool = True,
+    linewidth: float = 2,
+    grid_alpha: float = 0.3,
+):
+    """
+    Plot groups of DataFrame columns on stacked axes.
+
+    Each inner list in `rows` defines the columns plotted on one axis.
+
+    Example
+    -------
+    plot(
+        df,
+        [
+            ["respiration"],
+            ["respiration_amplitude"],
+            ["respiration_period", "respiration_previous_period"],
+        ],
+    )
+    """
+    if not rows:
+        raise ValueError("rows must contain at least one list of column names")
+
+    missing = [
+        column
+        for columns in rows
+        for column in columns
+        if column not in df.columns
+    ]
+    if missing:
+        raise KeyError(f"Columns not found in DataFrame: {missing}")
+
+    nrows = len(rows)
+
+    if figsize is None:
+        figsize = (16, max(3, 2.2 * nrows))
+
+    fig, axes = plt.subplots(
+        nrows=nrows,
+        ncols=1,
+        figsize=figsize,
+        sharex=sharex,
+        constrained_layout=True,
+        squeeze=False,
+    )
+
+    axes = axes[:, 0]
+
+    for ax, columns in zip(axes, rows):
+        for column in columns:
+            ax.plot(
+                df.index,
+                df[column],
+                label=column,
+                linewidth=linewidth,
+            )
+
+        ax.legend(loc="upper right")
+        ax.set_ylabel("\n".join(columns))
+        ax.grid(alpha=grid_alpha)
+
+    axes[-1].set_xlabel(df.index.name or "Time")
+
+    return fig, axes
+
+
+def plot_annotated_oscillation(
+    df,
+    summarydf,
+    signal,
+    oscillation_id,
+    smoothed_signal=None,
+    title=None,
+):
+    """
+    Plot one oscillation object with its intrinsic measurements annotated.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Sample-level DataFrame.
+    summarydf : pandas.DataFrame
+        One-row-per-oscillation object table.
+    signal : str
+        Name of the observed signal column.
+    oscillation_id : int
+        Oscillation object to plot.
+    smoothed_signal : str, optional
+        Smoothed signal column used for construction.
+    title : str, optional
+        Plot title.
+    """
+    row = summarydf.loc[
+        summarydf["oscillation_id"] == oscillation_id
+    ].iloc[0]
+
+    start_index = int(row["start_index"])
+    peak_index = int(row["peak_index"])
+    end_index = int(row["end_index"])
+
+    y_column = smoothed_signal or signal
+    segment = df.loc[start_index:end_index]
+
+    start_value = df.loc[start_index, y_column]
+    peak_value = df.loc[peak_index, y_column]
+    end_value = df.loc[end_index, y_column]
+
+    baseline = (start_value + end_value) / 2
+    amplitude = row["amplitude"]
+
+    fig, ax = plt.subplots(figsize=(8, 4.5))
+
+    if smoothed_signal is not None:
+        ax.plot(
+            segment.index,
+            segment[signal],
+            linewidth=1,
+            alpha=0.45,
+            label="Observed signal",
+        )
+
+    ax.plot(
+        segment.index,
+        segment[y_column],
+        linewidth=2,
+        label="Oscillation signal",
+    )
+
+    ax.axvspan(
+        start_index,
+        peak_index,
+        alpha=0.10,
+        label="Rising phase",
+    )
+
+    ax.axvspan(
+        peak_index,
+        end_index,
+        alpha=0.10,
+        label="Falling phase",
+    )
+
+    ax.scatter(
+        [start_index, peak_index, end_index],
+        [start_value, peak_value, end_value],
+        s=60,
+        zorder=3,
+    )
+
+    ax.vlines(
+        peak_index,
+        baseline,
+        peak_value,
+        linewidth=1.5,
+    )
+
+    ax.annotate(
+        f"Amplitude = {amplitude:.3f}",
+        xy=(peak_index, (baseline + peak_value) / 2),
+        xytext=(8, 0),
+        textcoords="offset points",
+        va="center",
+    )
+
+    ax.annotate(
+        f"Rise = {row['rise_duration']:.0f}",
+        xy=((start_index + peak_index) / 2, start_value),
+        xytext=(0, -28),
+        textcoords="offset points",
+        ha="center",
+    )
+
+    ax.annotate(
+        f"Fall = {row['fall_duration']:.0f}",
+        xy=((peak_index + end_index) / 2, end_value),
+        xytext=(0, -28),
+        textcoords="offset points",
+        ha="center",
+    )
+
+    ax.annotate(
+        f"Period = {row['period']:.0f}",
+        xy=((start_index + end_index) / 2, min(start_value, end_value)),
+        xytext=(0, -52),
+        textcoords="offset points",
+        ha="center",
+    )
+
+    ax.text(
+        0.02,
+        0.95,
+        (
+            f"O{oscillation_id}\n"
+            f"Duration = {row['duration']:.0f}\n"
+            f"Symmetry = {row['temporal_symmetry']:.3f}"
+        ),
+        transform=ax.transAxes,
+        va="top",
+    )
+
+    ax.set_title(title or f"Oscillation object O{oscillation_id}")
+    ax.set_xlabel("Time index")
+    ax.set_ylabel(signal)
+    ax.grid(alpha=0.3)
+    ax.legend(loc="upper right")
+
+    return fig, ax
+
+
+def plot_oscillation_panel(
+    ax,
+    df,
+    summarydf,
+    signal,
+    object_ids,
+    *,
+    smoothed_signal=None,
+    title=None,
+    ylabel=None,
+):
+    """
+    Plot observed data, the construction signal, transition points,
+    rising/falling phases, and oscillation-object identifiers.
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        Axis on which to draw the plot.
+    df : pandas.DataFrame
+        Sample-level DataFrame indexed by time or sample number.
+    summarydf : pandas.DataFrame
+        One-row-per-oscillation table containing:
+        oscillation_id, start_index, peak_index, and end_index.
+    signal : str
+        Observed signal column.
+    object_ids : iterable
+        Oscillation IDs to include.
+    smoothed_signal : str, optional
+        Signal used to construct the oscillations. When omitted, `signal`
+        is used for both the observed and construction signals.
+    title : str, optional
+        Panel title.
+    ylabel : str, optional
+        Y-axis label.
+    """
+    objects = (
+        summarydf.loc[
+            summarydf["oscillation_id"].isin(object_ids),
+            [
+                "oscillation_id",
+                "start_index",
+                "peak_index",
+                "end_index",
+            ],
+        ]
+        .dropna()
+        .sort_values("start_index")
+        .copy()
+    )
+
+    # Keep only complete oscillation objects.
+    objects = objects.loc[
+        (objects["start_index"] < objects["peak_index"])
+        & (objects["peak_index"] < objects["end_index"])
+    ]
+
+    if objects.empty:
+        raise ValueError("No complete oscillation objects were selected.")
+
+    start = objects["start_index"].min()
+    end = objects["end_index"].max()
+
+    segment = df.loc[start:end]
+    construction_signal = smoothed_signal or signal
+
+    # Default matplotlib color cycle, rather than hard-coded colors.
+    cycle = plt.rcParams["axes.prop_cycle"].by_key()["color"]
+    observed_color = cycle[0]
+    construction_color = cycle[1]
+    rising_color = cycle[2]
+    falling_color = cycle[3]
+
+    # Observed signal.
+    ax.plot(
+        segment.index,
+        segment[signal],
+        linewidth=1.0,
+        alpha=0.55 if smoothed_signal else 1.0,
+        label="Observed signal",
+        color=observed_color,
+    )
+
+    # Smoothed/construction signal, when different from the observation.
+    if smoothed_signal is not None:
+        ax.plot(
+            segment.index,
+            segment[construction_signal],
+            linewidth=2.0,
+            label="Smoothed signal",
+            color=construction_color,
+        )
+
+    y = segment[construction_signal]
+    y_min = y.min()
+    y_max = y.max()
+    y_range = y_max - y_min
+
+    label_y = y_min + 0.06 * y_range
+
+    for _, obj in objects.iterrows():
+        object_id = int(obj["oscillation_id"])
+        start_index = obj["start_index"]
+        peak_index = obj["peak_index"]
+        end_index = obj["end_index"]
+
+        start_value = df.loc[start_index, construction_signal]
+        peak_value = df.loc[peak_index, construction_signal]
+        end_value = df.loc[end_index, construction_signal]
+
+        # Rising and falling phases.
+        ax.axvspan(
+            start_index,
+            peak_index,
+            alpha=0.08,
+            color=rising_color,
+        )
+        ax.axvspan(
+            peak_index,
+            end_index,
+            alpha=0.08,
+            color=falling_color,
+        )
+
+        # Boundaries between oscillation objects.
+        ax.axvline(
+            start_index,
+            linestyle="--",
+            linewidth=0.8,
+            alpha=0.45,
+        )
+
+        # Trough: enter rising.
+        ax.scatter(
+            start_index,
+            start_value,
+            marker="v",
+            s=55,
+            color=rising_color,
+            zorder=4,
+        )
+
+        # Peak: exit rising / enter falling.
+        ax.scatter(
+            peak_index,
+            peak_value,
+            marker="^",
+            s=55,
+            color=falling_color,
+            zorder=4,
+        )
+
+        # Oscillation-object label.
+        midpoint = start_index + (end_index - start_index) / 2
+
+        ax.text(
+            midpoint,
+            label_y,
+            rf"$O_{{{object_id}}}$",
+            ha="center",
+            va="bottom",
+            fontsize=10,
+            fontweight="medium",
+        )
+
+    # Final boundary.
+    ax.axvline(
+        objects["end_index"].max(),
+        linestyle="--",
+        linewidth=0.8,
+        alpha=0.45,
+    )
+
+    ax.set_title(title or signal)
+    ax.set_ylabel(ylabel or signal)
+    ax.grid(alpha=0.25)
+    ax.margins(x=0.01)
+
+
+def add_construction_legend(fig):
+    """Add one shared legend for both panels."""
+    cycle = plt.rcParams["axes.prop_cycle"].by_key()["color"]
+
+    handles = [
+        plt.Line2D(
+            [],
+            [],
+            linewidth=1.0,
+            color=cycle[0],
+            label="Observed signal",
+        ),
+        plt.Line2D(
+            [],
+            [],
+            linewidth=2.0,
+            color=cycle[1],
+            label="Smoothed signal",
+        ),
+        plt.Rectangle(
+            (0, 0),
+            1,
+            1,
+            alpha=0.08,
+            color=cycle[2],
+            label="Rising phase",
+        ),
+        plt.Rectangle(
+            (0, 0),
+            1,
+            1,
+            alpha=0.08,
+            color=cycle[3],
+            label="Falling phase",
+        ),
+        plt.Line2D(
+            [],
+            [],
+            linestyle="none",
+            marker="v",
+            markersize=7,
+            color=cycle[2],
+            label="enter rising (trough)",
+        ),
+        plt.Line2D(
+            [],
+            [],
+            linestyle="none",
+            marker="^",
+            markersize=7,
+            color=cycle[3],
+            label="exit rising (peak)",
+        ),
+    ]
+
+    fig.legend(
+        handles=handles,
+        loc="lower center",
+        ncol=3,
+        frameon=True,
+        bbox_to_anchor=(0.5, -0.01),
+    )

featuregraph_smoothing_core/utils/_bidmc.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import pandas as pd
+import requests
+
+
+BIDMC_VERSION = "1.0.0"
+BIDMC_BASE_URL = (
+    f"https://physionet.org/files/bidmc/{BIDMC_VERSION}/bidmc_csv"
+)
+
+FileKind = Literal["Signals", "Numerics", "Breaths", "Fix"]
+
+
+def get_cache_dir() -> Path:
+    """
+    Return the BIDMC cache directory outside the Git repository.
+    """
+    cache_dir = (
+        Path.home()
+        / ".cache"
+        / "featuregraph"
+        / "bidmc"
+        / BIDMC_VERSION
+    )
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def bidmc_filename(subject: int, kind: FileKind) -> str:
+    """
+    Return the source filename for a BIDMC subject file.
+    """
+    if not isinstance(subject, int):
+        raise TypeError("subject must be an integer")
+
+    if not 1 <= subject <= 53:
+        raise ValueError("subject must be between 1 and 53")
+
+    suffix = "txt" if kind == "Fix" else "csv"
+    return f"bidmc_{subject:02d}_{kind}.{suffix}"
+
+
+def download_bidmc_file(
+    subject: int,
+    kind: FileKind,
+    *,
+    refresh: bool = False,
+    timeout: int = 60,
+) -> Path:
+    """
+    Download one BIDMC source file into the external cache.
+    """
+    filename = bidmc_filename(subject, kind)
+    destination = get_cache_dir() / filename
+
+    if destination.exists() and destination.stat().st_size > 0 and not refresh:
+        return destination
+
+    url = f"{BIDMC_BASE_URL}/{filename}"
+    temporary_path = destination.with_suffix(
+        destination.suffix + ".part"
+    )
+
+    try:
+        with requests.get(
+            url,
+            stream=True,
+            timeout=timeout,
+        ) as response:
+            response.raise_for_status()
+
+            with temporary_path.open("wb") as file:
+                for chunk in response.iter_content(
+                    chunk_size=1024 * 1024
+                ):
+                    if chunk:
+                        file.write(chunk)
+
+        if temporary_path.stat().st_size == 0:
+            raise RuntimeError(
+                f"Downloaded BIDMC file is empty: {url}"
+            )
+
+        temporary_path.replace(destination)
+
+    except Exception:
+        temporary_path.unlink(missing_ok=True)
+        raise
+
+    return destination
+
+
+def _load_bidmc_csv(
+    subject: int,
+    kind: Literal["Signals", "Numerics", "Breaths"],
+    *,
+    refresh: bool = False,
+) -> pd.DataFrame:
+    """
+    Download and load one BIDMC CSV table.
+    """
+    path = download_bidmc_file(
+        subject,
+        kind,
+        refresh=refresh,
+    )
+
+    df = pd.read_csv(path)
+
+    # Clean source-column whitespace at the loader boundary.
+    df.columns = df.columns.str.strip()
+
+    # Ensure the observation table identifies its source subject.
+    df["subject"] = subject
+
+    df.attrs["bidmc_subject"] = subject
+    df.attrs["bidmc_kind"] = kind
+    df.attrs["source_file"] = str(path)
+    df.attrs["bidmc_version"] = BIDMC_VERSION
+
+    return df
+
+
+def load_bidmc_signals(
+    subject: int,
+    *,
+    refresh: bool = False,
+) -> pd.DataFrame:
+    """
+    Load waveform observations for one BIDMC subject.
+    """
+    return _load_bidmc_csv(
+        subject,
+        "Signals",
+        refresh=refresh,
+    )
+
+
+def load_bidmc_numerics(
+    subject: int,
+    *,
+    refresh: bool = False,
+) -> pd.DataFrame:
+    """
+    Load numeric observations for one BIDMC subject.
+    """
+    return _load_bidmc_csv(
+        subject,
+        "Numerics",
+        refresh=refresh,
+    )
+
+
+def load_bidmc_breaths(
+    subject: int,
+    *,
+    refresh: bool = False,
+) -> pd.DataFrame:
+    """
+    Load breath annotations for one BIDMC subject.
+    """
+    return _load_bidmc_csv(
+        subject,
+        "Breaths",
+        refresh=refresh,
+    )
+
+
+def load_bidmc_subject(
+    subject: int,
+    *,
+    refresh: bool = False,
+) -> pd.DataFrame:
+    """
+    Load the waveform observation table for one BIDMC subject.
+
+    This is the primary BIDMC loader used by FeatureGraph. It returns a
+    DataFrame directly so that its output can be passed into behavioral
+    constructors such as ``featuregraph.oscillate``.
+
+    Numerics and breath annotations remain available through
+    ``load_bidmc_numerics`` and ``load_bidmc_breaths``.
+
+    Parameters
+    ----------
+    subject:
+        BIDMC subject number, between 1 and 53.
+
+    refresh:
+        Redownload the source waveform file even when it is cached.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Waveform observations for one subject.
+    """
+    return load_bidmc_signals(
+        subject,
+        refresh=refresh,
+    )
+
+
+def clear_bidmc_cache() -> None:
+    """
+    Remove locally cached BIDMC files.
+    """
+    cache_dir = get_cache_dir()
+
+    for path in cache_dir.iterdir():
+        if path.is_file():
+            path.unlink()

featuregraph_smoothing_core/utils/_rename_map.py

@@ -0,0 +1,23 @@
+"""
+bidmc_map transcribed from the real state_detection/utils/_rename_map.py
+(private repo, commit 8bfee18), lines 72-79.
+
+NOTE ON SCOPE: the real file also contains a second dict, eastman_map,
+mapping Tennessee Eastman Process (TEP) column names (xmeas_1..41,
+xmv_1..11, faultNumber, simulationRun) to descriptive names. That dict
+is deliberately NOT included here -- it's irrelevant to this package's
+purpose (reproducing the smoothing paper's BIDMC-only population
+statistics), and TEP work hasn't started yet regardless. It was also
+only partially visible when this package was assembled (lines 1-19 and
+45-79 of the real file were seen; lines 20-44 were not), so it
+couldn't be transcribed completely even if it were in scope.
+"""
+
+bidmc_map = {
+    "Time [s]": "time",
+    "RESP": "respiration",
+    "PLETH": "ppg",
+    "II": "ecg_ii",
+    "V": "ecg_v",
+    "AVR": "ecg_avr",
+}

featuregraph_smoothing_core/validation/__init__.py

@@ -0,0 +1,15 @@
+from featuregraph_smoothing_core.validation.characterize import (
+    estimate_period_acf,
+    characterize_signal,
+)
+from featuregraph_smoothing_core.validation.matching import match_breaths
+from featuregraph_smoothing_core.validation.canonical import compute_canonical_indices
+from featuregraph_smoothing_core.validation.exclusions import FLAGGED_ANOMALY_SUBJECTS
+
+__all__ = [
+    "estimate_period_acf",
+    "characterize_signal",
+    "match_breaths",
+    "compute_canonical_indices",
+    "FLAGGED_ANOMALY_SUBJECTS",
+]

featuregraph_smoothing_core/validation/canonical.py

@@ -0,0 +1,76 @@
+"""
+The private repo's ground-truth validation notebook fetched "canonical"
+detected objects (the ones built with each subject's own ACF-recommended
+window) from a Postgres table that cached an earlier computation. That
+table is just a cache -- the same objects can be recomputed directly,
+identically, using characterize_signal() and OscillationConfig(), both
+of which are public in this package. This module does that recomputation
+so the ground-truth validation doesn't depend on the private storage
+layer at all.
+"""
+
+from featuregraph_smoothing_core.behaviors.oscillation import OscillationConfig
+from featuregraph_smoothing_core.validation.characterize import characterize_signal
+
+
+def compute_canonical_indices(df, signal, group, index_kind='peak', min_correlation=0.6):
+    """
+    For each group (e.g. subject or case_id), estimate a smoothing
+    window via ACF-based characterization and, if confident, construct
+    Oscillation objects using that group's own recommended window.
+
+    Mirrors the private repo's canonical_bidmc_troughs / canonical_bidmc_peaks
+    / canonical_capno_troughs functions, but recomputes directly instead
+    of reading a cached Postgres table -- the result is the same, since
+    those functions cached exactly this computation.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Observations for all groups (e.g. all 53 BIDMC subjects).
+    signal : str
+        Name of the observed signal column (e.g. "respiration").
+    group : str
+        Name of the grouping column (e.g. "subject" or "case_id").
+    index_kind : "peak" or "trough"
+        Which boundary index to return.
+    min_correlation : float
+        Passed through to characterize_signal.
+
+    Returns
+    -------
+    (indices_by_group, characterization)
+        indices_by_group : dict mapping each confident group's value to
+            a sorted list of int sample indices.
+        characterization : the full characterize_signal() output, so
+            callers can inspect is_confident / estimated_period / etc.
+            for every group, not only the confident ones.
+    """
+    if index_kind not in ('peak', 'trough'):
+        raise ValueError("index_kind must be 'peak' or 'trough'")
+
+    characterization = characterize_signal(df, signal, group, min_correlation=min_correlation)
+
+    indices_by_group = {}
+    for group_value, row in characterization.iterrows():
+        if not row['is_confident']:
+            continue
+
+        window = int(row['window_medium'])
+        subj_df = df[df[group] == group_value].copy()
+
+        config = OscillationConfig(signal=signal, smooth_window=window)
+        added = config.add_primitives(subj_df, group)
+
+        # summarize() gives one row per actual oscillation object -- the
+        # add_primitives() output has one row per SAMPLE, with peak/trough
+        # index forward-filled across every row between events, so reading
+        # straight from added would count each sample between two peaks
+        # as if it were its own detected peak.
+        summarized = config.summarize(added, [group, config.trough_event_id_col])
+        index_col = 'peak_index' if index_kind == 'peak' else 'trough_index'
+        indices_by_group[group_value] = sorted(
+            summarized[index_col].dropna().astype(int).tolist()
+        )
+
+    return indices_by_group, characterization

featuregraph_smoothing_core/validation/characterize.py

@@ -0,0 +1,61 @@
+import numpy as np
+import pandas as pd
+
+
+def estimate_period_acf(signal, max_lag=None, min_lag=100):
+    """
+    Estimate the dominant period of a signal using autocorrelation,
+    computed directly on the raw signal with no smoothing window involved.
+    Returns (peak_lag, peak_correlation, at_boundary).
+    at_boundary=True means the search never found a real local peak --
+    the max was just the start of the region, i.e. the curve was still
+    decaying from lag 0 rather than showing genuine periodic recurrence.
+    """
+    x = signal.dropna().to_numpy()
+    x = x - x.mean()
+    n = len(x)
+    if max_lag is None:
+        max_lag = n // 2
+
+    f = np.fft.fft(x, n=2 * n)
+    acf = np.fft.ifft(f * np.conj(f))[:n].real
+    acf /= acf[0]
+
+    search_region = acf[min_lag:max_lag]
+    if len(search_region) == 0:
+        return None, None, True
+
+    peak_offset = np.argmax(search_region)
+    peak_lag = peak_offset + min_lag
+    peak_corr = acf[peak_lag]
+    at_boundary = (peak_offset == 0)
+
+    return peak_lag, peak_corr, at_boundary
+
+
+def characterize_signal(df, signal, group, min_correlation=0.6):
+    """
+    Estimate each group's dominant period directly from the raw signal
+    via autocorrelation. is_confident requires both a sufficiently strong
+    peak correlation AND a genuine local peak (not just the search
+    boundary), since a boundary hit means no real periodicity was found.
+    """
+    results = []
+    for subj, subj_df in df.groupby(group):
+        period, corr, at_boundary = estimate_period_acf(subj_df[signal])
+        is_confident = (
+            period is not None
+            and corr is not None
+            and corr >= min_correlation
+            and not at_boundary
+        )
+        results.append({
+            group: subj,
+            'estimated_period': period,
+            'acf_peak_correlation': corr,
+            'at_boundary': at_boundary,
+            'is_confident': is_confident,
+            'window_small': max(int(round(period * 0.25)), 2) if is_confident else None,
+            'window_medium': max(int(round(period * 0.5)), 2) if is_confident else None,
+        })
+    return pd.DataFrame(results).set_index(group)

featuregraph_smoothing_core/validation/exclusions.py

@@ -0,0 +1,14 @@
+"""
+Subjects flagged in the private repo's earlier analysis as showing a
+validation gap that does not close as the matching tolerance widens --
+a structural construction-annotation mismatch, not ordinary timing
+imprecision. Transcribed verbatim (FLAGGED_ANOMALY_SUBJECTS) from the
+private repo's ground-truth validation notebook (cell-bidmc-gap-to-ceiling).
+
+Excluding these from the paper's reported recall/precision figures is
+the same treatment already given to the 16 BIDMC subjects with no
+reliable ACF period at all -- a recorded, structural fact, not an
+error hidden from the reader.
+"""
+
+FLAGGED_ANOMALY_SUBJECTS = [9, 10, 23, 48, 51]

featuregraph_smoothing_core/validation/matching.py

@@ -0,0 +1,42 @@
+import pandas as pd
+
+
+def match_breaths(detected_indices, expert_indices, tolerance_samples):
+    """
+    Matches each expert-marked breath sample index to the nearest
+    detected cycle's boundary index, within a tolerance window. Works
+    for any two lists of sample indices, so this is dataset-agnostic.
+
+    recall = fraction of expert-marked breaths that had a detected cycle
+             boundary nearby (did the algorithm miss real breaths?)
+    precision = fraction of detected cycle boundaries that had an
+             expert-marked breath nearby (did the algorithm hallucinate
+             extra cycles?)
+    """
+    detected = pd.DataFrame({'detected_index': sorted(detected_indices)}).astype(float)
+    expert = pd.DataFrame({'expert_index': sorted(expert_indices)}).astype(float)
+
+    if len(detected) == 0 or len(expert) == 0:
+        return {
+            'recall': float('nan'), 'precision': float('nan'),
+            'n_expert': len(expert), 'n_detected': len(detected),
+        }
+
+    matched_forward = pd.merge_asof(
+        expert, detected,
+        left_on='expert_index', right_on='detected_index',
+        direction='nearest', tolerance=tolerance_samples,
+    )
+    recall = matched_forward['detected_index'].notna().mean()
+
+    matched_backward = pd.merge_asof(
+        detected, expert,
+        left_on='detected_index', right_on='expert_index',
+        direction='nearest', tolerance=tolerance_samples,
+    )
+    precision = matched_backward['expert_index'].notna().mean()
+
+    return {
+        'recall': recall, 'precision': precision,
+        'n_expert': len(expert), 'n_detected': len(detected),
+    }

featuregraph_smoothing_core-1.0.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: featuregraph-smoothing-core
+Version: 1.0.0
+Summary: Minimal, frozen subset of FeatureGraph's state-detection code, extracted to support reproducibility of the smoothing-paper results.
+Author: Nazia Habib
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: numpy>=1.23
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# featuregraph-smoothing-core
+
+Code and data behind "A Compiler-Level Account of Smoothing-Parameter
+Choice." Contains `OscillationConfig` (the construction used throughout
+the paper), a BIDMC data loader, and the validation logic behind the
+paper's human-annotation results.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Reproduce the paper's results
+
+```bash
+pytest tests/ -v
+```
+
+Two tests are skipped by default, since they need a live download from
+PhysioNet. Their skip reasons record the exact confirmed results;
+remove the `@pytest.mark.skip` decorator above either one and rerun to
+reproduce it directly:
+
+- `test_reproduces_paper_correlation_and_ratio_range` — the paper's
+  population correlation (0.39) and ratio range (1.14x–40.25x) across
+  all 53 BIDMC subjects.
+- `test_bidmc_peak_matched_recall_excluding_flagged_subjects` — the
+  paper's human-annotation recall results (Table 1), N=32.
+
+## Using OscillationConfig directly
+
+```python
+from featuregraph_smoothing_core.behaviors.oscillation import OscillationConfig
+
+config = OscillationConfig(signal="respiration", smooth_window=100)
+added = config.add_primitives(df, "subject")
+summary = config.summarize(added, ["subject", config.trough_event_id_col])
+```
+
+## What's here
+
+- `src/featuregraph_smoothing_core/` — the package
+- `notebooks/bidmc_visual_demo.ipynb` — the code that produced Figure 1
+- `artifacts/paper/compiler/smoothing.md` — the paper manuscript
+- `tests/` — the full test suite
+
+## Citation
+
+Software: https://doi.org/10.5281/zenodo.22947447
+
+## License
+
+MIT. See `LICENSE`.

featuregraph_smoothing_core-1.0.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+featuregraph_smoothing_core/__init__.py,sha256=56xg_Y7VTThPE8u4UFuql9tS_Nvrskr367OhyV0QM8c,377
+featuregraph_smoothing_core/plot.py,sha256=lDrAG82ekeYxTZcG1s2Vt1-EGH2vKgvz-pmXIYpfqo0,11016
+featuregraph_smoothing_core/behaviors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+featuregraph_smoothing_core/behaviors/oscillation.py,sha256=_hCrtxGC_WZ1nXNzYHLF8XkcdUmhl3Pisk_50MHvXmk,4236
+featuregraph_smoothing_core/datasets/__init__.py,sha256=ISTqeMQEo_FwgKrcBJNlzlMwYNA85b4F2Y1eSIWnuaE,115
+featuregraph_smoothing_core/datasets/_bidmc.py,sha256=9wxzzhIyLyy_rIUIAkhV8OGOq_3HPdOMHQxOlk2UBMw,894
+featuregraph_smoothing_core/operators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+featuregraph_smoothing_core/operators/events.py,sha256=-uwO6cFhANyxxcSADiLqE6IdQMM7jAWMiADFmFI9Bx0,756
+featuregraph_smoothing_core/operators/measures.py,sha256=nPvNWHtJftbnK9UoaHqd6Tm8yLwr9xvGa9u9wrGCCqI,501
+featuregraph_smoothing_core/operators/states.py,sha256=SnyoyTvNnmODL4x2agXMpIOWGiVCOvO0dhtSE-MPdEA,661
+featuregraph_smoothing_core/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+featuregraph_smoothing_core/utils/_bidmc.py,sha256=5TvvI0cmGNdSiNw6wMwJRwmfFNFLABn_Wh4wlWvR_mQ,4814
+featuregraph_smoothing_core/utils/_rename_map.py,sha256=A7RlqV1oQ9Mwm5HZEzue94nWZeYkawvn2W4e956AIa0,884
+featuregraph_smoothing_core/validation/__init__.py,sha256=gYq6X2Q7JHA26PPvPKTrbl1WxZKUzYPmCMK3Hq41nu0,521
+featuregraph_smoothing_core/validation/canonical.py,sha256=-1Ile-3GhBRYnta9eBqREgidoTCxSyGR7YJFriEI6sQ,3345
+featuregraph_smoothing_core/validation/characterize.py,sha256=5U7DXpCCwi9FBF8GViY_53qipH40L8MTYea4jAuj-ro,2172
+featuregraph_smoothing_core/validation/exclusions.py,sha256=8hwZsHdq9dypDzvAX_1RpwQS7iNPRawveunJo_wiNhg,643
+featuregraph_smoothing_core/validation/matching.py,sha256=GbNbXmJgH81TfG8txHidkpX0qEBlUiw_qCMUnFNCLgE,1631
+featuregraph_smoothing_core-1.0.0.dist-info/licenses/LICENSE,sha256=XRtysk4F6gH4GboWx_7UwWzosDC3RHHoLx1ynZZAJeQ,1068
+featuregraph_smoothing_core-1.0.0.dist-info/METADATA,sha256=Oyw_Qn0gLF5YwyAUlLMKuPvVUstHyxT0ESmar2Gf_as,2043
+featuregraph_smoothing_core-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+featuregraph_smoothing_core-1.0.0.dist-info/top_level.txt,sha256=Vdb7pu2xT6ASV-C3qskrH32qHTEXOJlu8TFUVXBHfcI,28
+featuregraph_smoothing_core-1.0.0.dist-info/RECORD,,

featuregraph_smoothing_core-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

featuregraph_smoothing_core-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nazia Habib
+
+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.

featuregraph_smoothing_core-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+featuregraph_smoothing_core