pneumonitor 0.1.1__py3-none-any.whl

pneumonitor/filters.py

@@ -0,0 +1,54 @@
+import numpy as np
+from scipy.signal import butter, filtfilt, sosfiltfilt, iirnotch
+
+
+# Low-pass filter
+def lowpass_filter(data, cutoff=100, fs=500, order=4):
+    nyquist = 0.5 * fs
+    normal_cutoff = cutoff / nyquist
+    print("normal_cutoff", normal_cutoff)
+    b, a = butter(order, normal_cutoff, btype="low", analog=False)
+    return filtfilt(b, a, data)
+
+
+def bandpass_filter(data, lowcut=0.5, highcut=25, fs=500, order=4):
+    # SOS form used instead of the (b, a) transfer-function form: at order 4
+    # with a narrow low-frequency band (e.g. 0.05-1 Hz at fs=500), the (b, a)
+    # coefficients are numerically unstable and filtfilt silently returns NaNs.
+    sos = butter(order, [lowcut, highcut], btype="band", fs=fs, output="sos")
+    return sosfiltfilt(sos, data)
+
+
+def resp_filter(data, fs=500, order=6, low_freq=3 / 60, high_freq=180 / 60):
+    data = np.asarray(data, dtype=float)
+
+    sos = butter(
+        order,
+        [low_freq, high_freq],
+        btype="bandpass",
+        fs=fs,
+        output="sos",
+    )
+
+    return sosfiltfilt(sos, data)
+
+
+def notch_filter(data, fs=500, notch_freq=50, notch_quality=30):
+    """Applies a 50 Hz notch filter to the input signal.
+
+    Parameters:
+        data (array-like): Input signal.
+        fs (float): Sampling frequency in Hz (default: 500 Hz).
+        notch_freq (float): Frequency to be notched out (default: 50 Hz).
+        notch_quality (float): Quality factor of the notch filter (default: 30).
+
+    Returns:
+        array-like: Filtered signal with 50 Hz removed.
+    """
+    # Design notch filter
+    b_notch, a_notch = iirnotch(notch_freq, notch_quality, fs)
+
+    # Apply filter using zero-phase filtering
+    filtered_data = filtfilt(b_notch, a_notch, data)
+
+    return filtered_data

pneumonitor/load.py

@@ -0,0 +1,83 @@
+import numpy as np
+import pandas as pd
+import pathlib
+import ast, re
+
+from typing import Tuple, List
+
+
+def timestamp_to_seconds(
+    df_bio: pd.DataFrame, df_to_transform: pd.DataFrame
+) -> pd.DataFrame:
+    df_to_transform["timestamp[us]"] = (
+        df_to_transform["timestamp[us]"] - df_bio["timestamp[us]"].iloc[0]
+    ) / 1e6  # Normalize timestamp to seconds
+    df_to_transform = df_to_transform.rename(columns={"timestamp[us]": "timestamp[s]"})
+    return df_to_transform
+
+
+# Compute amplitude and phase
+def compute_amplitude_phase(df):
+    df["Amplitude"] = np.sqrt(df["BiozI[uV]"] ** 2 + df["BiozQ[uV]"] ** 2)
+    df["Phase"] = np.arctan2(df["BiozQ[uV]"], df["BiozI[uV]"]) * (
+        180 / np.pi
+    )  # Convert to degrees
+    return df
+
+
+def load_data(
+    folder_path: str,
+) -> Tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame, pd.DataFrame, List[int]]:
+
+    folder_path = pathlib.Path(folder_path)
+    # load ECG and impedance data
+    df_bio = pd.read_csv(
+        folder_path / "bio.txt",
+        delimiter=";",
+        names=["timestamp[us]", "ECG[uV]", "BiozI[uV]", "BiozQ[uV]"],
+        skiprows=1,
+    )
+
+    # load accelerometer data
+    df_acc = pd.read_csv(
+        folder_path / "imu.txt",
+        delimiter=";",
+        names=["timestamp[us]", "X[mq]", "Y[mg]", "Z[mg]"],
+        skiprows=1,
+    )
+
+    # load markers
+    df_markers = pd.read_csv(
+        folder_path / "mark.txt", delimiter=";", names=["timestamp[us]"], skiprows=1
+    )
+
+    # load stats
+    df_stats = pd.read_csv(
+        folder_path / "stat.txt",
+        delimiter=";",
+        names=[
+            "timestamp[us]",
+            "BatLevel[%]",
+            "BatVoltage[mV]",
+            "BatCurrent[mA]",
+            "Status[NONE]",
+        ],
+        skiprows=1,
+    )
+
+    with open(folder_path / "info.txt") as f:
+        for line in f:
+            if line.startswith("Errors"):
+                errors = ast.literal_eval(re.search(r"\[.*\]", line).group())
+                break
+        else:
+            errors = []
+
+    df_bio = compute_amplitude_phase(df_bio)
+
+    df_acc = timestamp_to_seconds(df_bio, df_acc)
+    df_markers = timestamp_to_seconds(df_bio, df_markers)
+    df_stats = timestamp_to_seconds(df_bio, df_stats)
+    df_bio = timestamp_to_seconds(df_bio, df_bio)
+
+    return df_bio, df_acc, df_markers, df_stats, errors

pneumonitor/plots.py

@@ -0,0 +1,547 @@
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+import matplotlib.pyplot as plt
+
+
+def plot_cardio_resp_data(
+    df_bio: pd.DataFrame,
+    df_markers: pd.DataFrame = None,
+    include_raw: bool = True,
+    resp_phase: bool = True,
+    height: int = 700,
+    width: int = 1000,
+    additional_signals: list[str] = None,
+):
+
+    raw_signals = {
+        "ECG_clean[uV]": "ECG[uV]",
+        "Amplitude_clean": "Amplitude",
+    }
+    colors = {
+        "ECG_clean[uV]": "red",
+        "Amplitude_clean": "blue",
+        "ECG[uV]": "purple",
+        "Amplitude": "orange",
+    }
+    signals = ["ECG_clean[uV]", "Amplitude_clean"]
+    if additional_signals:
+        signals.extend(additional_signals)
+    titles = [
+        "ECG",
+        "Amplitude",
+    ]
+    if additional_signals:
+        titles.extend(additional_signals)
+
+    # Create figure with subplots
+    fig = make_subplots(
+        rows=len(signals), cols=1, shared_xaxes=True, vertical_spacing=0.04
+    )
+
+    # Add signal traces
+    for i, signal in enumerate(signals):
+        row = i + 1
+
+        fig.add_trace(
+            go.Scatter(
+                x=df_bio["timestamp[s]"],
+                y=df_bio[signal],
+                mode="lines",
+                name=f"Raw {titles[i]}",
+                line=dict(color=colors[signal]) if signal in colors else None,
+                # opacity=0.2,
+            ),
+            row=row,
+            col=1,
+        )
+        if include_raw and signal in raw_signals:
+            fig.add_trace(
+                go.Scatter(
+                    x=df_bio["timestamp[s]"],
+                    y=df_bio[raw_signals[signal]],
+                    mode="lines",
+                    name=f"Raw {titles[i]}",
+                    line=(
+                        dict(color=colors[raw_signals[signal]])
+                        if raw_signals[signal] in colors
+                        else None
+                    ),
+                    opacity=0.2,
+                ),
+                row=row,
+                col=1,
+            )
+        if signal == "ECG_clean[uV]":
+            fig.add_trace(
+                go.Scatter(
+                    x=df_bio.loc[df_bio["ECG_R_Peaks"] == 1, "timestamp[s]"],
+                    y=df_bio.loc[df_bio["ECG_R_Peaks"] == 1, signal],
+                    mode="markers",
+                    name="ECG R-peaks",
+                    marker=dict(color="black", size=6),
+                ),
+                row=row,
+                col=1,
+            )
+        if resp_phase and signal == "Amplitude_clean" and "RSP_Phase" in df_bio.columns:
+            phase = df_bio["RSP_Phase"].values
+            timestamps = df_bio["timestamp[s]"].values
+            phase_changes = np.where(np.diff(phase.astype(int)) != 0)[0] + 1
+            seg_starts = np.concatenate([[0], phase_changes])
+            seg_ends = np.concatenate([phase_changes, [len(phase)]])
+            for s, e in zip(seg_starts, seg_ends):
+                fig.add_vrect(
+                    x0=timestamps[s],
+                    x1=timestamps[e - 1],
+                    fillcolor="green" if phase[s] == 1 else "red",
+                    opacity=0.15,
+                    layer="below",
+                    line_width=0,
+                    row=row,
+                    col=1,
+                )
+
+        fig.update_yaxes(title_text=titles[i], row=row, col=1)
+
+    if df_markers is not None:
+        # Add vertical lines for each timestamp from df_markers
+        for mark_time in df_markers.iloc[:, 0]:
+            for row in range(1, len(signals) + 1):
+                fig.add_vline(
+                    x=mark_time,
+                    line=dict(color="purple", width=1, dash="dash"),
+                    row=row,
+                    col=1,
+                )
+
+    # Update x-axis title
+    fig.update_xaxes(title_text="Time [s]", row=len(signals), col=1)
+
+    # Adjust layout
+    fig.update_layout(
+        height=height,
+        width=width,
+        margin=dict(l=50, r=50, t=50, b=50),
+        legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+    )
+
+    fig.show()
+    return fig
+
+
+def plot_accelerometer_data(
+    df_acc: pd.DataFrame,
+    df_markers: pd.DataFrame = None,
+    height: int = 700,
+    width: int = 1000,
+):
+    fig = make_subplots(rows=2, cols=1, shared_xaxes=True, vertical_spacing=0.04)
+    fig.add_trace(
+        go.Scatter(
+            x=df_acc["timestamp[s]"],
+            y=df_acc["X[mq]"],
+            mode="lines",
+            name="X",
+            opacity=0.5,
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=df_acc["timestamp[s]"],
+            y=df_acc["Y[mg]"],
+            mode="lines",
+            name="Y",
+            opacity=0.5,
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=df_acc["timestamp[s]"],
+            y=df_acc["Z[mg]"],
+            mode="lines",
+            name="Z",
+            opacity=0.5,
+        ),
+        row=1,
+        col=1,
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=df_acc["timestamp[s]"],
+            y=df_acc["Acc_Magnitude[g]"],
+            mode="lines",
+            name="Vector magnitude",
+            opacity=0.5,
+        ),
+        row=2,
+        col=1,
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=df_acc["timestamp[s]"],
+            y=df_acc["Acc_RMS[g]"],
+            mode="lines",
+            name="RMS",
+            line=dict(color="black"),
+        ),
+        row=2,
+        col=1,
+    )
+
+    fig.update_xaxes(title_text="Time [s]", row=2, col=1)
+    fig.update_yaxes(title_text="Acceleration X [mg]", row=1, col=1)
+    fig.update_yaxes(title_text="Acceleration Y [mg]", row=1, col=1)
+    fig.update_yaxes(title_text="Acceleration Z [mg]", row=1, col=1)
+    fig.update_yaxes(title_text="Acceleration vector magnitude [g]", row=2, col=1)
+
+    # Add vertical lines for each timestamp from df_markers
+    if df_markers is not None:
+        for mark_time in df_markers.iloc[:, 0]:
+            for row in range(1, 3):
+                fig.add_vline(
+                    x=mark_time,
+                    line=dict(color="purple", width=1, dash="dash"),
+                    row=row,
+                    col=1,
+                )
+
+    fig.update_layout(
+        height=height,
+        width=width,
+        margin=dict(l=50, r=50, t=50, b=50),
+        legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+    )
+    fig.show()
+    return fig
+
+
+def plot_cardio_resp_data_mpl(
+    df_bio: pd.DataFrame,
+    df_markers: pd.DataFrame = None,
+    include_raw: bool = True,
+    resp_phase: bool = True,
+    height: int = 700,
+    width: int = 1000,
+    additional_signals: list[str] = None,
+):
+    raw_signals = {
+        "ECG_clean[uV]": "ECG[uV]",
+        "Amplitude_clean": "Amplitude",
+    }
+    colors = {
+        "ECG_clean[uV]": "red",
+        "Amplitude_clean": "blue",
+        "ECG[uV]": "purple",
+        "Amplitude": "orange",
+    }
+    signals = ["ECG_clean[uV]", "Amplitude_clean"]
+    if additional_signals:
+        signals.extend(additional_signals)
+    titles = ["ECG", "Amplitude"]
+    if additional_signals:
+        titles.extend(additional_signals)
+
+    n = len(signals)
+    fig, axes = plt.subplots(n, 1, sharex=True, figsize=(width / 100, height / 100))
+    if n == 1:
+        axes = [axes]
+
+    for i, (signal, ax) in enumerate(zip(signals, axes)):
+        color = colors.get(signal)
+        ax.plot(df_bio["timestamp[s]"], df_bio[signal], color=color, label=f"Clean {titles[i]}")
+
+        if include_raw and signal in raw_signals:
+            raw_col = raw_signals[signal]
+            raw_color = colors.get(raw_col)
+            ax.plot(
+                df_bio["timestamp[s]"],
+                df_bio[raw_col],
+                color=raw_color,
+                alpha=0.2,
+                label=f"Raw {titles[i]}",
+            )
+
+        if signal == "ECG_clean[uV]":
+            peaks = df_bio["ECG_R_Peaks"] == 1
+            ax.scatter(
+                df_bio.loc[peaks, "timestamp[s]"],
+                df_bio.loc[peaks, signal],
+                color="black",
+                s=20,
+                zorder=5,
+                label="ECG R-peaks",
+            )
+
+        if resp_phase and signal == "Amplitude_clean" and "RSP_Phase" in df_bio.columns:
+            phase = df_bio["RSP_Phase"].values
+            timestamps = df_bio["timestamp[s]"].values
+            phase_changes = np.where(np.diff(phase.astype(int)) != 0)[0] + 1
+            seg_starts = np.concatenate([[0], phase_changes])
+            seg_ends = np.concatenate([phase_changes, [len(phase)]])
+            for s, e in zip(seg_starts, seg_ends):
+                ax.axvspan(
+                    timestamps[s],
+                    timestamps[e - 1],
+                    color="green" if phase[s] == 1 else "red",
+                    alpha=0.15,
+                )
+
+        if df_markers is not None:
+            for mark_time in df_markers.iloc[:, 0]:
+                ax.axvline(x=mark_time, color="purple", linewidth=1, linestyle="--")
+
+        ax.set_ylabel(titles[i])
+        ax.legend(loc="upper right", fontsize="small")
+
+    axes[-1].set_xlabel("Time [s]")
+    fig.tight_layout()
+    plt.show()
+    return fig
+
+
+def plot_accelerometer_data_mpl(
+    df_acc: pd.DataFrame,
+    df_markers: pd.DataFrame = None,
+    height: int = 700,
+    width: int = 1000,
+):
+    fig, axes = plt.subplots(2, 1, sharex=True, figsize=(width / 100, height / 100))
+
+    for col, label in [("X[mq]", "X"), ("Y[mg]", "Y"), ("Z[mg]", "Z")]:
+        axes[0].plot(df_acc["timestamp[s]"], df_acc[col], alpha=0.5, label=label)
+
+    axes[1].plot(
+        df_acc["timestamp[s]"],
+        df_acc["Acc_Magnitude[g]"],
+        alpha=0.5,
+        label="Vector magnitude",
+    )
+    axes[1].plot(
+        df_acc["timestamp[s]"],
+        df_acc["Acc_RMS[g]"],
+        color="black",
+        label="RMS",
+    )
+
+    if df_markers is not None:
+        for mark_time in df_markers.iloc[:, 0]:
+            for ax in axes:
+                ax.axvline(x=mark_time, color="purple", linewidth=1, linestyle="--")
+
+    axes[0].set_ylabel("Acceleration [mg]")
+    axes[1].set_ylabel("Acceleration vector magnitude [g]")
+    axes[1].set_xlabel("Time [s]")
+    for ax in axes:
+        ax.legend(loc="upper right", fontsize="small")
+
+    fig.tight_layout()
+    plt.show()
+    return fig
+
+
+def plot_combined_data(
+    df_acc: pd.DataFrame,
+    df_bio: pd.DataFrame,
+    df_markers: pd.DataFrame = None,
+    include_raw: bool = True,
+    resp_phase: bool = True,
+    height: int = 900,
+    width: int = 1000,
+    additional_signals: list[str] = None,
+):
+    raw_signals = {
+        "ECG_clean[uV]": "ECG[uV]",
+        "Amplitude_clean": "Amplitude",
+    }
+    colors = {
+        "ECG_clean[uV]": "red",
+        "Amplitude_clean": "blue",
+        "ECG[uV]": "purple",
+        "Amplitude": "orange",
+    }
+    bio_signals = ["ECG_clean[uV]", "Amplitude_clean"]
+    if additional_signals:
+        bio_signals.extend(additional_signals)
+    bio_titles = ["ECG", "Amplitude"]
+    if additional_signals:
+        bio_titles.extend(additional_signals)
+
+    total_rows = 2 + len(bio_signals)
+    fig = make_subplots(rows=total_rows, cols=1, shared_xaxes=True, vertical_spacing=0.03)
+
+    # Row 1: X, Y, Z axes
+    for col, name in [("X[mq]", "X"), ("Y[mg]", "Y"), ("Z[mg]", "Z")]:
+        fig.add_trace(
+            go.Scatter(x=df_acc["timestamp[s]"], y=df_acc[col], mode="lines", name=name, opacity=0.5),
+            row=1, col=1,
+        )
+    fig.update_yaxes(title_text="Acceleration [mg]", row=1, col=1)
+
+    # Row 2: magnitude + RMS
+    fig.add_trace(
+        go.Scatter(x=df_acc["timestamp[s]"], y=df_acc["Acc_Magnitude[g]"], mode="lines", name="Vector magnitude", opacity=0.5),
+        row=2, col=1,
+    )
+    fig.add_trace(
+        go.Scatter(x=df_acc["timestamp[s]"], y=df_acc["Acc_RMS[g]"], mode="lines", name="RMS", line=dict(color="black")),
+        row=2, col=1,
+    )
+    fig.update_yaxes(title_text="Magnitude [g]", row=2, col=1)
+
+    # Rows 3+: cardio resp signals
+    for i, signal in enumerate(bio_signals):
+        row = 3 + i
+        fig.add_trace(
+            go.Scatter(
+                x=df_bio["timestamp[s]"],
+                y=df_bio[signal],
+                mode="lines",
+                name=f"Clean {bio_titles[i]}",
+                line=dict(color=colors[signal]) if signal in colors else None,
+            ),
+            row=row, col=1,
+        )
+        if include_raw and signal in raw_signals:
+            fig.add_trace(
+                go.Scatter(
+                    x=df_bio["timestamp[s]"],
+                    y=df_bio[raw_signals[signal]],
+                    mode="lines",
+                    name=f"Raw {bio_titles[i]}",
+                    line=dict(color=colors[raw_signals[signal]]) if raw_signals[signal] in colors else None,
+                    opacity=0.2,
+                ),
+                row=row, col=1,
+            )
+        if signal == "ECG_clean[uV]":
+            fig.add_trace(
+                go.Scatter(
+                    x=df_bio.loc[df_bio["ECG_R_Peaks"] == 1, "timestamp[s]"],
+                    y=df_bio.loc[df_bio["ECG_R_Peaks"] == 1, signal],
+                    mode="markers",
+                    name="ECG R-peaks",
+                    marker=dict(color="black", size=6),
+                ),
+                row=row, col=1,
+            )
+        if resp_phase and signal == "Amplitude_clean" and "RSP_Phase" in df_bio.columns:
+            phase = df_bio["RSP_Phase"].values
+            timestamps = df_bio["timestamp[s]"].values
+            phase_changes = np.where(np.diff(phase.astype(int)) != 0)[0] + 1
+            seg_starts = np.concatenate([[0], phase_changes])
+            seg_ends = np.concatenate([phase_changes, [len(phase)]])
+            for s, e in zip(seg_starts, seg_ends):
+                fig.add_vrect(
+                    x0=timestamps[s],
+                    x1=timestamps[e - 1],
+                    fillcolor="green" if phase[s] == 1 else "red",
+                    opacity=0.15,
+                    layer="below",
+                    line_width=0,
+                    row=row, col=1,
+                )
+        fig.update_yaxes(title_text=bio_titles[i], row=row, col=1)
+
+    if df_markers is not None:
+        for mark_time in df_markers.iloc[:, 0]:
+            for row in range(1, total_rows + 1):
+                fig.add_vline(x=mark_time, line=dict(color="purple", width=1, dash="dash"), row=row, col=1)
+
+    fig.update_xaxes(title_text="Time [s]", row=total_rows, col=1)
+    fig.update_layout(
+        height=height,
+        width=width,
+        margin=dict(l=50, r=50, t=50, b=50),
+        legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+    )
+    fig.show()
+    return fig
+
+
+def plot_combined_data_mpl(
+    df_acc: pd.DataFrame,
+    df_bio: pd.DataFrame,
+    df_markers: pd.DataFrame = None,
+    include_raw: bool = True,
+    include_xyz: bool = True,
+    resp_phase: bool = True,
+    height: int = 900,
+    width: int = 1000,
+    additional_signals: list[str] = None,
+):
+    raw_signals = {
+        "ECG_clean[uV]": "ECG[uV]",
+        "Amplitude_clean": "Amplitude",
+    }
+    colors = {
+        "ECG_clean[uV]": "red",
+        "Amplitude_clean": "blue",
+        "ECG[uV]": "purple",
+        "Amplitude": "orange",
+    }
+    bio_signals = ["ECG_clean[uV]", "Amplitude_clean"]
+    if additional_signals:
+        bio_signals.extend(additional_signals)
+    bio_titles = ["ECG", "Amplitude"]
+    if additional_signals:
+        bio_titles.extend(additional_signals)
+
+    total_rows = 1 + include_xyz*1 + len(bio_signals)
+    fig, axes = plt.subplots(total_rows, 1, sharex=True, figsize=(width / 100, height / 100))
+    axs_idx = 0
+    # Row 0: X, Y, Z axes
+    if include_xyz:
+        for col, label in [("X[mq]", "X"), ("Y[mg]", "Y"), ("Z[mg]", "Z")]:
+            axes[axs_idx].plot(df_acc["timestamp[s]"], df_acc[col], alpha=0.5, label=label)
+        axes[axs_idx].set_ylabel("Acceleration [mg]")
+        axes[axs_idx].legend(loc="upper right", fontsize="small")
+        axs_idx += 1
+
+    # Row 1: magnitude + RMS
+    axes[axs_idx].plot(df_acc["timestamp[s]"], df_acc["Acc_Magnitude[g]"], alpha=0.5, label="Vector magnitude")
+    axes[axs_idx].plot(df_acc["timestamp[s]"], df_acc["Acc_RMS[g]"], color="black", label="RMS")
+    axes[axs_idx].set_ylabel("Magnitude [g]")
+    axes[axs_idx].legend(loc="upper right", fontsize="small")
+    axs_idx += 1
+
+    # Rows 2+: cardio resp signals
+    for i, signal in enumerate(bio_signals):
+        ax = axes[axs_idx]
+        color = colors.get(signal)
+        ax.plot(df_bio["timestamp[s]"], df_bio[signal], color=color, label=f"Clean {bio_titles[i]}")
+        if include_raw and signal in raw_signals:
+            raw_col = raw_signals[signal]
+            ax.plot(df_bio["timestamp[s]"], df_bio[raw_col], color=colors.get(raw_col), alpha=0.2, label=f"Raw {bio_titles[i]}")
+        if signal == "ECG_clean[uV]":
+            peaks = df_bio["ECG_R_Peaks"] == 1
+            ax.scatter(df_bio.loc[peaks, "timestamp[s]"], df_bio.loc[peaks, signal], color="black", s=20, zorder=5, label="ECG R-peaks")
+        if resp_phase and signal == "Amplitude_clean" and "RSP_Phase" in df_bio.columns:
+            phase = df_bio["RSP_Phase"].values
+            timestamps = df_bio["timestamp[s]"].values
+            phase_changes = np.where(np.diff(phase.astype(int)) != 0)[0] + 1
+            seg_starts = np.concatenate([[0], phase_changes])
+            seg_ends = np.concatenate([phase_changes, [len(phase)]])
+            for s, e in zip(seg_starts, seg_ends):
+                ax.axvspan(timestamps[s], timestamps[e - 1], color="green" if phase[s] == 1 else "red", alpha=0.15)
+        if df_markers is not None:
+            for mark_time in df_markers.iloc[:, 0]:
+                ax.axvline(x=mark_time, color="purple", linewidth=1, linestyle="--")
+        ax.set_ylabel(bio_titles[i])
+        ax.legend(loc="upper right", fontsize="small")
+        axs_idx += 1
+
+    if df_markers is not None:
+        for mark_time in df_markers.iloc[:, 0]:
+            for ax in axes[:2]:
+                ax.axvline(x=mark_time, color="purple", linewidth=1, linestyle="--")
+
+    axes[-1].set_xlabel("Time [s]")
+    fig.tight_layout()
+    plt.show()
+    return axes, fig

pneumonitor/preprocess.py

@@ -0,0 +1,46 @@
+import pandas as pd
+import neurokit2 as nk
+
+
+def _preprocess_cardio(df_bio: pd.DataFrame, sampling_rate: int = 500) -> pd.DataFrame:
+    df_bio = df_bio.copy()
+    res, _ = nk.ecg_process(df_bio["ECG[uV]"].values, sampling_rate=sampling_rate)
+    df_bio["ECG_clean[uV]"] = res["ECG_Clean"]
+    df_bio["ECG_R_Peaks"] = res["ECG_R_Peaks"]
+    df_bio["ECG_Rate"] = res["ECG_Rate"]
+    return df_bio
+
+
+def _preprocess_resp(df_bio: pd.DataFrame, sampling_rate: int = 500) -> pd.DataFrame:
+    df_bio = df_bio.copy()
+    res, _ = nk.rsp_process(df_bio["Amplitude"].values, sampling_rate=sampling_rate)
+    df_bio["Amplitude_clean"] = res["RSP_Clean"]
+    df_bio["RSP_Rate"] = res["RSP_Rate"]
+    df_bio["RSP_Peaks"] = res["RSP_Peaks"]
+    df_bio["RSP_Phase"] = res["RSP_Phase"]
+    return df_bio
+
+
+def preprocess_cardio_resp(
+    df_bio: pd.DataFrame, sampling_rate: int = 500
+) -> pd.DataFrame:
+    df_bio = _preprocess_cardio(df_bio, sampling_rate)
+    df_bio = _preprocess_resp(df_bio, sampling_rate)
+    return df_bio
+
+
+def process_imu(
+    df_acc: pd.DataFrame, rms_window_sec: int, sampling_rate: int = 500
+) -> pd.DataFrame:
+    df_acc = df_acc.copy()
+    df_acc["Acc_Magnitude[g]"] = (
+        df_acc["X[mq]"] ** 2 + df_acc["Y[mg]"] ** 2 + df_acc["Z[mg]"] ** 2
+    ) ** 0.5 / 1000  # Convert to g
+    df_acc["Acc_Magnitude[g]"] = df_acc["Acc_Magnitude[g]"] - 1  # Remove gravity
+    window_size = rms_window_sec * sampling_rate
+    df_acc["Acc_RMS[g]"] = (
+        df_acc["Acc_Magnitude[g]"]
+        .rolling(window=window_size, center=True)
+        .apply(lambda x: (x**2).mean() ** 0.5, raw=True)
+    )
+    return df_acc

pneumonitor-0.1.1.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: pneumonitor
+Version: 0.1.1
+Summary: Code related to Pneumonitor data processing
+Project-URL: Repository, https://github.com/<your-username>/Pneumonitor
+Author-email: Maciej Rosoł <maciej.rosol@pw.edu.pl>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: neurokit2>=0.2.12
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: plotly>=6.7.0
+Requires-Dist: scipy>=1.17.1
+Description-Content-Type: text/markdown
+
+# Pneumonitor
+
+Python toolkit for analysing cardiorespiratory data recorded with the **Pneumonitor 4** wearable device. The device simultaneously acquires ECG and impedance pneumography signals, enabling synchronised analysis of cardiac and respiratory activity.
+
+## Project structure
+
+```
+Pneumonitor/
+├── pneumonitor/
+│   ├── load.py         # Data loading and timestamp normalisation
+│   ├── preprocess.py   # Signal processing (ECG, respiration, IMU)
+│   ├── filters.py      # Digital filter building blocks
+│   └── plots.py        # Interactive Plotly visualisations
+├── <recording_id>/     # One folder per recording (e.g. 00001/)
+│   ├── bio.txt         # ECG + bioimpedance (I/Q) at 500 Hz
+│   ├── imu.txt         # 3-axis accelerometer at 50 Hz
+│   ├── mark.txt        # User-triggered event markers
+│   ├── stat.txt        # Battery and device status
+│   ├── imp.txt         # Empty in the current version
+│   └── info.txt        # Recording metadata and error log
+└── experiments.py      # Example analysis notebook (%-cell format)
+```
+
+## Recording format
+
+Each recording folder contains semicolon-delimited text files:
+
+| File | Columns | Description |
+|------|---------|-------------|
+| `bio.txt` | `timestamp[us]`, `ECG[uV]`, `BiozI[uV]`, `BiozQ[uV]` | ECG and bioimpedance in-phase / quadrature components |
+| `imu.txt` | `timestamp[us]`, `X[mq]`, `Y[mg]`, `Z[mg]` | 3-axis accelerometer in mg |
+| `mark.txt` | `timestamp[us]` | Timestamps of manual markers |
+| `stat.txt` | `timestamp[us]`, `BatLevel[%]`, `BatVoltage[mV]`, `BatCurrent[mA]`, `Status[NONE]` | Device telemetry |
+| `info.txt` | Key-value pairs | Hardware/firmware version, sample counts, error list |
+
+Timestamps are in microseconds from device boot. `load_data()` normalises them to seconds relative to the first biosignal sample.
+
+## Usage
+
+### 1. Load a recording
+
+```python
+from pneumonitor.load import load_data
+
+df_bio, df_acc, df_markers, df_stats, errors = load_data('00001')
+```
+
+`df_bio` already contains the derived `Amplitude` (√(I²+Q²)) and `Phase` (arctan2(Q,I)) columns computed from the bioimpedance I/Q pair.
+
+### 2. Process IMU data
+
+```python
+from pneumonitor.preprocess import process_imu
+
+df_acc = process_imu(df_acc, rms_window_sec=1, sampling_rate=50)
+```
+
+Adds `Acc_Magnitude[g]` (gravity-removed vector magnitude) and `Acc_RMS[g]` (rolling RMS over the specified window).
+
+### 3. Preprocess cardiorespiratory signals
+
+```python
+from pneumonitor.preprocess import preprocess_cardio_resp
+
+df_bio = preprocess_cardio_resp(df_bio, sampling_rate=500)
+```
+
+Uses [NeuroKit2](https://github.com/neuropsychology/NeuroKit) internally and appends the following columns to `df_bio`:
+
+| Column | Description |
+|--------|-------------|
+| `ECG_clean[uV]` | Cleaned ECG signal |
+| `ECG_R_Peaks` | Binary mask of R-peak locations |
+| `ECG_Rate` | Instantaneous heart rate (bpm) |
+| `Amplitude_clean` | Cleaned respiratory amplitude |
+| `RSP_Rate` | Instantaneous respiratory rate (bpm) |
+| `RSP_Peaks` | Binary mask of respiration peaks |
+| `RSP_Phase` | Respiratory phase (0 = exhalation, 1 = inhalation) |
+
+### 4. Visualise
+
+```python
+from pneumonitor.plots import plot_cardio_resp_data, plot_accelerometer_data
+
+# Cardiorespiratory overview — add extra derived signals as extra subplots
+plot_cardio_resp_data(df_bio, df_markers, include_raw=True,
+                      additional_signals=['ECG_Rate', 'RSP_Rate'])
+
+# Accelerometer overview
+plot_accelerometer_data(df_acc, df_markers)
+```
+
+Both functions return a Plotly `Figure` and call `.show()`. The cardiorespiratory plot shades the respiratory amplitude subplot green (inhalation) / red (exhalation) based on `RSP_Phase`, and overlays R-peak markers on the ECG subplot.
+
+### 5. Filters (optional low-level use)
+
+```python
+from pneumonitor.filters import bandpass_filter, notch_filter, resp_filter
+
+ecg_filtered = notch_filter(df_bio['ECG[uV]'].values)          # remove 50 Hz mains
+ecg_filtered = bandpass_filter(ecg_filtered, lowcut=0.5, highcut=25)
+resp_filtered = resp_filter(df_bio['Amplitude'].values)        # 3–180 bpm bandpass
+```
+
+## Installation
+
+Once published to PyPI, install it into any project with:
+
+```bash
+pip install pneumonitor
+# or
+uv add pneumonitor
+```
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+### Installing dependencies
+
+Install all dependencies specified in `pyproject.toml`:
+
+```bash
+uv sync
+```
+
+### Adding new dependencies
+
+To add a new package to the project:
+
+```bash
+uv add <package-name>
+```
+
+This will update both `pyproject.toml` and the virtual environment automatically.

pneumonitor-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+pneumonitor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pneumonitor/filters.py,sha256=zLNb2zrSaaNFAiApXdLHUmGJbA_cNqawTI4ywznULbE,1760
+pneumonitor/load.py,sha256=Y3ifmqDZM3hyLkCUFI0d8k9nhPL8pmjIAmYPI_rzSPs,2331
+pneumonitor/plots.py,sha256=5abblLpFy5bTZLYabv724YYhFVQqtFmx7XHsKYXzgrE,18326
+pneumonitor/preprocess.py,sha256=55QIrxFznNGv318em5e00Adnf2utxzIT3EPINEPzBNg,1625
+pneumonitor-0.1.1.dist-info/METADATA,sha256=biBoo9gWgRXwUGUy6v2-XUokEM4e6BP_lLuKeNqlgsU,5243
+pneumonitor-0.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+pneumonitor-0.1.1.dist-info/licenses/LICENSE,sha256=OE_-dlnv6cZcWVE8zz1spqE3pItX8Srfz8XINY192tA,1070
+pneumonitor-0.1.1.dist-info/RECORD,,

pneumonitor-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pneumonitor-0.1.1.dist-info/licenses/LICENSE

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