featuregraph-smoothing-core 1.0.0__tar.gz

featuregraph_smoothing_core-1.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,54 @@
+# 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/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "featuregraph-smoothing-core"
+version = "1.0.0"
+description = "Minimal, frozen subset of FeatureGraph's state-detection code, extracted to support reproducibility of the smoothing-paper results."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Nazia Habib" },
+]
+dependencies = [
+    "pandas>=1.5",
+    "numpy>=1.23",
+    "matplotlib>=3.5",
+    "requests>=2.25",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

featuregraph_smoothing_core-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

featuregraph_smoothing_core-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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)