stiminterp 0.1__py3-none-any.whl

stiminterp/__init__.py

@@ -0,0 +1,11 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("stiminterp")
+except PackageNotFoundError:
+    # package is not installed
+    pass
+
+from .stim_interpolate import remove_photostim_artefacts, StimInterpConfig
+from .load_data.scanimage_metadata import ScanImageMetadata
+from .pipeline import run_stiminterp

stiminterp/load_data/custom_data_loader.py

@@ -0,0 +1,124 @@
+"""
+These functions are used to load data from a custom ScanImage data format
+used in our experiments. The data are generated and saved by MATLAB scripts
+that are not included in this repository.
+
+ScanImage's DataRecorder should be used to record:
+    - FrameOnset
+    - StimTTL
+
+Please also see:
+BaselLaserMouse/ScanImageTools - Rob Campbell, Sumiya Kuroda
+https://github.com/BaselLaserMouse/ScanImageTools/tree/2p-313
+"""
+
+from pathlib import Path
+
+import h5py
+import numpy as np
+import pandas as pd
+
+
+def read_h5_array(h5_path: Path, dataset_path: str) -> np.ndarray:
+    """
+    Read a dataset from an HDF5 file and return it as a NumPy array.
+
+    Parameters
+    ----------
+    h5_path : str
+        Path to the .h5 / .hdf5 file
+    dataset_path : str
+        Path inside the HDF5 file (e.g. 'SyncTTL' or '/group/dataset')
+
+    Returns
+    -------
+    np.ndarray
+        Dataset as a NumPy array
+    """
+    with h5py.File(h5_path, "r") as f:
+        data = f[dataset_path][:]
+    return data
+
+
+def digitize_ai_signal(ai_signal, digitizeThr=4):
+    ai_signal_digitized = np.array(ai_signal).copy()
+
+    ai_signal_digitized[ai_signal < digitizeThr] = 0.0
+    ai_signal_digitized[ai_signal >= digitizeThr] = 1.0
+
+    return ai_signal_digitized
+
+
+def find_edges(signal: np.ndarray, return_edges: str = "both"):
+    signal = np.asarray(signal).astype(bool)
+
+    diff = np.diff(signal.astype(np.int8))
+
+    rising = np.where(diff == 1)[0] + 1
+    falling = np.where(diff == -1)[0] + 1
+
+    # If signal starts HIGH, first rising edge is at index 0
+    if signal[0]:
+        rising = np.insert(rising, 0, 0)
+
+    # If signal ends HIGH, final falling edge is at last index
+    if signal[-1]:
+        falling = np.append(falling, len(signal) - 1)
+
+    if return_edges == "rising":
+        return rising
+    elif return_edges == "falling":
+        return falling
+    elif return_edges == "both":
+        return rising, falling
+
+
+def get_artefact_dfs(
+    path_to_h5: Path,
+    channel_name_framettl: str,
+    channel_name_stimttl: str,
+    digitize_threshold: float = 4,
+) -> tuple:
+    """Read the HDF5 file generated by ScanImage's Data Recorder
+
+    Parameters
+    ----------
+    path_to_h5 : Path
+        Path to the HDF5 file.
+    channel_name_framettl : str
+        Name of the channel for frame clock.
+    channel_name_stimttl : str
+        Name of the channel for photostim TTL.
+    digitize_threshold: float
+        Threshold used to digitize analog signals
+
+    Returns
+    -------
+    tuple
+        tuple of pd.DataFrame
+    """
+
+    framettl = read_h5_array(path_to_h5, channel_name_framettl)
+    stimttl = read_h5_array(path_to_h5, channel_name_stimttl)
+
+    framettl_d = digitize_ai_signal(framettl, digitizeThr=digitize_threshold)
+    stimttl_d = digitize_ai_signal(stimttl, digitizeThr=digitize_threshold)
+
+    framettl_rising, framettl_falling = find_edges(framettl_d)
+    stimttl_rising, stimttl_falling = find_edges(stimttl_d)
+
+    df_frames = pd.DataFrame(
+        {
+            "start": framettl_rising,
+            "stop": framettl_falling,
+        }
+    )
+
+    df_stims = pd.DataFrame(
+        {
+            "start": stimttl_rising,
+            "stop": stimttl_falling,
+        }
+    )
+
+    return df_frames, df_stims

stiminterp/load_data/scanimage_metadata.py

@@ -0,0 +1,159 @@
+# https://github.com/AllenNeuralDynamics/aind-ophys-mesoscope-image-splitter/blob/c034d3d893dc7365498b61e5353337c1a4e45fb5/code/tiff_metadata.py#L19
+
+import copy
+import pathlib
+from typing import List, Union
+
+import tifffile
+
+
+def _read_metadata(tiff_path: pathlib.Path):
+    """
+    Calls tifffile.read_scanimage_metadata on the specified
+    path and returns the result. This method was factored
+    out so that it could be easily mocked in unit tests.
+    """
+    return tifffile.read_scanimage_metadata(open(tiff_path, "rb"))
+
+
+class ScanImageMetadata(object):
+    """
+    A class to handle reading and parsing the metadata that
+    comes with the TIFF files produced by ScanImage
+
+    Parameters
+    ----------
+    tiff_path: pathlib.Path
+        Path to the TIFF file whose metadata we are parsing
+    """
+
+    def __init__(self, tiff_path: pathlib.Path):
+        self._file_path = tiff_path
+        if not tiff_path.is_file():
+            raise ValueError(f"{tiff_path.resolve().absolute()} is not a file")
+        self._metadata = _read_metadata(tiff_path)
+
+    @property
+    def file_path(self) -> pathlib.Path:
+        return self._file_path
+
+    @property
+    def raw_metadata(self) -> tuple:
+        """
+        Return a copy of the raw metadata as read by
+        tifffile.read_scanimage_metadata.
+        """
+        return copy.deepcopy(self._metadata)
+
+    @property
+    def numVolumes(self) -> int:
+        """
+        The metadata field representing the number of volumes
+        recorded by the rig
+        """
+        if not hasattr(self, "_numVolumes"):
+            value = self._metadata[0]["SI.hStackManager.actualNumVolumes"]
+            if not isinstance(value, int):
+                raise ValueError(
+                    f"in {self._file_path}\n"
+                    "SI.hStackManager.actualNumVolumes is a "
+                    f"{type(value)}; expected int"
+                )
+
+            self._numVolumes = value
+
+        return self._numVolumes
+
+    @property
+    def numSlices(self) -> int:
+        """
+        The metadata field representing the number of slices
+        recorded by the rig
+        """
+        if not hasattr(self, "_numSlices"):
+            value = self._metadata[0]["SI.hStackManager.actualNumSlices"]
+            if not isinstance(value, int):
+                raise ValueError(
+                    f"in {self._file_path}\n"
+                    "SI.hStackManager.actualNumSlices is a "
+                    f"{type(value)}; expected int"
+                )
+            self._numSlices = value
+
+        return self._numSlices
+
+    @property
+    def channelSave(self) -> Union[int, List[int]]:
+        """
+        The metadata field representing which channels were saved
+        in this TIFF. Either 1 or [1, 2]
+        """
+        if not hasattr(self, "_channelSave"):
+            self._channelSave = self._metadata[0]["SI.hChannels.channelSave"]
+        return self._channelSave
+
+    @property
+    def defined_rois(self) -> List[dict]:
+        """
+        Get the ROIs defined in this TIFF file
+
+        This is list of dicts, each dict containing the ScanImage
+        metadata for a given ROI
+
+        In this context, an ROI is a 3-dimensional volume of the brain
+        that was scanned by the microscope.
+        """
+        if not hasattr(self, "_defined_rois"):
+            roi_parent = self._metadata[1]["RoiGroups"]
+            roi_group = roi_parent["imagingRoiGroup"]["rois"]
+            if isinstance(roi_group, dict):
+                self._defined_rois = [
+                    roi_group,
+                ]
+            elif isinstance(roi_group, list):
+                self._defined_rois = roi_group
+            else:
+                msg = "unable to parse "
+                msg += "self._metadata[1]['RoiGroups']"
+                msg += "['imagingROIGroup']['rois'] "
+                msg += f"of type {type(roi_group)}"
+                raise RuntimeError(msg)
+
+        # use copy to make absolutely sure self._defined_rois
+        # is not accidentally changed downstream
+        return copy.deepcopy(self._defined_rois)
+
+    @property
+    def n_rois(self) -> int:
+        """
+        Number of ROIs defined in the metadata for this TIFF file.
+        """
+        if not hasattr(self, "_n_rois"):
+            self._n_rois = len(self.defined_rois)
+        return self._n_rois
+
+    @property
+    def n_chans(self) -> int:
+        """
+        Number of channels saved in this TIFF.
+
+        ScanImage's SI.hChannels.channelSave is typically either:
+        - 1 (meaning channel 1 only), or
+        - [1, 2] (meaning channels 1 and 2)
+        """
+        ch = self.channelSave
+        if isinstance(ch, int):
+            return 1
+        return len(ch)
+
+    def zs_for_roi(self, i_roi: int) -> List[int]:
+        """
+        Return a list of the z-values at which the specified
+        ROI was scanned
+        """
+        if i_roi >= self.n_rois:
+            msg = f"You asked for ROI {i_roi}; "
+            msg += f"there are only {self.n_rois} "
+            msg += "specified in this TIFF file"
+            raise ValueError(msg)
+        return self.defined_rois[i_roi]["zs"]

stiminterp/pipeline.py

@@ -0,0 +1,51 @@
+from pathlib import Path
+
+from ScanImageTiffReader import ScanImageTiffReader
+from tifffile import imwrite
+
+from stiminterp import remove_photostim_artefacts
+from stiminterp.load_data.custom_data_loader import get_artefact_dfs
+from stiminterp.load_data.scanimage_metadata import ScanImageMetadata
+
+
+def run_stiminterp(
+    input_tif: str,
+    input_h5: str | None = None,
+    output_tif: str | None = None,
+):
+    tif_path = Path(input_tif)
+    sim = ScanImageMetadata(tif_path)
+
+    # infer h5 if not provided
+    if input_h5 is None:
+        h5_path = tif_path.with_suffix(".h5")
+    else:
+        h5_path = Path(input_h5)
+
+    # determine output path
+    if output_tif is None:
+        out_path = tif_path.with_name(f"{tif_path.stem}_corrected.tif")
+    else:
+        out_tmp = Path(output_tif)
+        if out_tmp.is_dir():
+            out_path = out_tmp / f"{tif_path.stem}_corrected.tif"
+        else:
+            out_path = out_tmp
+
+    vol = ScanImageTiffReader(input_tif).data()
+
+    df_frames, df_stims = get_artefact_dfs(
+        h5_path,
+        "FrameTTL",
+        "SatsumaGateTTL",
+    )
+
+    corrected, bad_mask, df_split = remove_photostim_artefacts(
+        vol,
+        df_frames,
+        df_stims,
+        frame_gap=sim.n_rois - 1,
+        num_channel=sim.n_chans,
+    )
+
+    imwrite(str(out_path), corrected)

stiminterp/plotting_hooks/sanity_check.py

@@ -0,0 +1,81 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+def create_sanitycheck_axes(nchannel: int):
+    """
+    Create axes for stim visualisation.
+
+    Layout:
+        rows = nchannel
+        cols = 3  (Uncorrected | Bad mask | Corrected)
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    axes : ndarray of shape (nchannel, 3)
+    """
+
+    ncols = 3
+
+    fig, axes = plt.subplots(
+        nchannel,
+        ncols,
+        figsize=(5 * ncols, 4 * nchannel),
+        sharex=True,
+        sharey=True,
+        constrained_layout=True,
+    )
+
+    # Ensure 2D array even if nchannel == 1
+    if nchannel == 1:
+        axes = axes[None, :]
+
+    # Column titles (only top row)
+    axes[0, 0].set_title("Uncorrected")
+    axes[0, 1].set_title("NaN mask")
+    axes[0, 2].set_title("Corrected")
+
+    return fig, axes
+
+
+def plot_removal(
+    axes_row,
+    frame: int,
+    y_frac_start: float,
+    y_frac_stop: float,
+    uncorrected: np.ndarray,
+    corrected: np.ndarray,
+    bad_mask: np.ndarray,
+    channel: int,  # <-- NEW
+    cmap: str = "gray",
+):
+    raw = uncorrected[frame]
+    corr = corrected[frame]
+    mask = bad_mask[frame]
+
+    Y = uncorrected.shape[1]
+    y_min = int(y_frac_start * Y)
+    y_max = int(y_frac_stop * Y)
+
+    vmin = np.percentile(raw, 1)
+    vmax = np.percentile(raw, 99.5)
+
+    # --- Uncorrected ---
+    axes_row[0].set_ylabel(f"Ch {channel}\nFrame {frame}")
+    axes_row[0].imshow(raw, cmap=cmap, vmin=vmin, vmax=vmax)
+    axes_row[0].axhline(y_min, c="r", lw=2)
+    axes_row[0].axhline(y_max, c="r", lw=2)
+    axes_row[0].axis("off")
+
+    # --- Bad mask ---
+    axes_row[1].imshow(mask, cmap="Reds")
+    axes_row[1].axhline(y_min, c="k", lw=2)
+    axes_row[1].axhline(y_max, c="k", lw=2)
+    axes_row[1].axis("off")
+
+    # --- Corrected ---
+    axes_row[2].imshow(corr, cmap=cmap, vmin=vmin, vmax=vmax)
+    # axes_row[2].axhline(y_min, c="r", lw=2)
+    # axes_row[2].axhline(y_max, c="r", lw=2)
+    axes_row[2].axis("off")

stiminterp/stim_interpolate.py

@@ -0,0 +1,372 @@
+"""
+stim_interpolate.py
+
+Photostimulation artefact removal via 1D interpolation.
+
+Pipeline
+--------
+1) Use frame timing + stim timing to determine artefact regions
+   (frame index + fraction within frame).
+2) Convert fractions -> scanline rows (Y).
+3) Set contaminated pixels to NaN.
+4) Fill NaNs per pixel using nearest-neighbor in *frame_index* space.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+# -----------------------------------------------------------------------------
+# Configuration
+# -----------------------------------------------------------------------------
+
+
+@dataclass
+class StimInterpConfig:
+    """Configuration for stim artefact removal."""
+
+    pad_rows: int = 5
+    require_n_good: int = 1  # nearest fill needs only 1 neighbor
+
+
+# -----------------------------------------------------------------------------
+# Public API
+# -----------------------------------------------------------------------------
+
+
+def remove_photostim_artefacts(
+    movie: np.ndarray,
+    df_frames: pd.DataFrame,
+    df_stims: pd.DataFrame,
+    frame_gap: Optional[int] = None,
+    num_channel: Optional[int] = None,
+    cfg: Optional[StimInterpConfig] = None,
+) -> Tuple[np.ndarray, np.ndarray, pd.DataFrame]:
+    """
+    Remove photostimulation artefacts by nearest-neighbor temporal filling.
+
+    Parameters
+    ----------
+    movie : np.ndarray
+        Imaging movie, shape (T, Y, X).
+        If multiple channels are saved interleaved per TTL frame, then:
+            T = len(df_frames) * num_channel
+    df_frames : pd.DataFrame
+        Columns ["start", "stop"] per TTL frame.
+        NOTE: TTL frames should already include plane interleaving if present.
+    df_stims : pd.DataFrame
+        Columns ["start", "stop"] per stim interval.
+    frame_gap : int, optional
+        Plane interleave indicator:
+          - 1 => 2 planes interleaved (plane_id = ttl_frame % 2)
+          - 2 => 3 planes interleaved (plane_id = ttl_frame % 3)
+        If None, treat as single plane for interpolation grouping i.e, 0.
+    num_channel : int, optional
+        Number of interleaved channels in the TIFF (channel-fast ordering).
+        If None, inferred as movie.shape[0] // len(df_frames).
+    cfg : StimInterpConfig, optional
+
+    Returns
+    -------
+    corrected : np.ndarray
+        Corrected movie (float32).
+    bad_mask : np.ndarray
+        Boolean mask (T, Y, X) indicating pixels replaced.
+    df_split : pd.DataFrame
+        Per-TTL-frame stim segments: ["frame", "frac_start", "frac_stop"].
+    """
+    if cfg is None:
+        cfg = StimInterpConfig()
+
+    movie = np.asarray(movie)
+    if movie.ndim != 3:
+        raise ValueError("movie must have shape (T, Y, X)")
+    T, Y, X = movie.shape
+
+    n_ttl = len(df_frames)
+    if n_ttl <= 0:
+        raise ValueError("df_frames is empty")
+
+    if T % n_ttl != 0:
+        raise ValueError(
+            f"movie.shape[0]={T} must be a multiple of len(df_frames)={n_ttl}."
+        )
+
+    inferred_num_channel = T // n_ttl
+    nchan = (
+        int(num_channel)
+        if num_channel is not None
+        else int(inferred_num_channel)
+    )
+
+    if nchan <= 0 or (n_ttl * nchan) != T:
+        raise ValueError(
+            f"movie.shape[0]={T} must be a multiple of len(df_frames)={n_ttl}."
+        )
+
+    # --- stim regions in TTL frame space ---
+    df_split = _artefact_regions(df_frames, df_stims)
+    if df_split.empty:
+        return (
+            movie.astype(np.float32, copy=True),
+            np.zeros_like(movie, dtype=bool),
+            df_split,
+        )
+
+    # --- bad scanlines in TTL frame space: (n_ttl, Y) ---
+    bad_lines_ttl = _build_bad_line_mask(
+        df_split=df_split,
+        T=n_ttl,
+        Y=Y,
+        pad_rows=cfg.pad_rows,
+    )
+
+    # --- expand across channels to movie time axis: (T, Y) ---
+    # TTL frame t corresponds to movie indices t*nchan + c for each channel c
+    bad_lines = np.repeat(bad_lines_ttl, repeats=nchan, axis=0)
+    bad_mask = np.repeat(bad_lines[:, :, None], X, axis=2)
+
+    corrected = movie.astype(np.float32, copy=True)
+    corrected[bad_mask] = np.nan
+
+    frame_index = np.arange(n_ttl, dtype=np.int32)
+    donor_mask = np.ones(n_ttl, dtype=bool)
+
+    corrected = interpolate_nan(
+        corrected,
+        frame_index=frame_index,
+        donor_mask=donor_mask,
+        require_n_good=cfg.require_n_good,
+        num_channel=nchan,
+        frame_gap=frame_gap,
+    )
+
+    return corrected, bad_mask, df_split
+
+
+# -----------------------------------------------------------------------------
+# Region detection (timing -> per-frame fractions)
+# -----------------------------------------------------------------------------
+
+
+def _artefact_regions(
+    df_frames: pd.DataFrame, df_stims: pd.DataFrame
+) -> pd.DataFrame:
+    df_frames = df_frames.sort_values("start").reset_index(drop=True)
+    df_stims = df_stims.sort_values("start")
+
+    if df_stims.empty:
+        return pd.DataFrame(columns=["frame", "frac_start", "frac_stop"])
+
+    # Remove stims outside acquisition span
+    t0 = df_frames["start"].iloc[0]
+    t1 = df_frames["stop"].iloc[-1]
+    df_stims = df_stims[(df_stims["stop"] > t0) & (df_stims["start"] < t1)]
+    if df_stims.empty:
+        return pd.DataFrame(columns=["frame", "frac_start", "frac_stop"])
+
+    all_bounds = np.empty(2 * len(df_frames), dtype=float)
+    all_bounds[0::2] = df_frames["start"].to_numpy()
+    all_bounds[1::2] = df_frames["stop"].to_numpy()
+
+    frame_start, frac_start = _map_times_to_frame_frac(
+        times=df_stims["start"].to_numpy(),
+        frame_boundaries=df_frames["stop"].to_numpy(),
+        all_boundaries=all_bounds,
+        fill=0.0,
+        offset=1,
+    )
+    frame_stop, frac_stop = _map_times_to_frame_frac(
+        times=df_stims["stop"].to_numpy(),
+        frame_boundaries=df_frames["start"].to_numpy(),
+        all_boundaries=all_bounds,
+        fill=1.0,
+        offset=0,
+    )
+
+    df = pd.DataFrame(
+        {
+            "frame_start": frame_start,
+            "frac_start": frac_start,
+            "frame_stop": frame_stop,
+            "frac_stop": frac_stop,
+        },
+        index=df_stims.index,
+    )
+    return _split_multi_frame_stims(df)
+
+
+def _map_times_to_frame_frac(
+    times: np.ndarray,
+    frame_boundaries: np.ndarray,
+    all_boundaries: np.ndarray,
+    fill: float,
+    offset: int = 0,
+) -> Tuple[np.ndarray, np.ndarray]:
+    frame = (
+        np.interp(
+            times,
+            frame_boundaries,
+            np.arange(len(frame_boundaries)),
+            left=-offset,
+        )
+        + offset
+    )
+    frame = frame.astype(int)
+
+    all_idx = np.interp(times, all_boundaries, np.arange(len(all_boundaries)))
+    out_of_frame = (all_idx.astype(int) % 2) == 1
+
+    frac_template = np.tile([0.0, 1.0], len(frame_boundaries))
+    frac = np.interp(times, all_boundaries, frac_template)
+    frac[out_of_frame] = float(fill)
+
+    return frame, np.clip(frac, 0.0, 1.0)
+
+
+def _split_multi_frame_stims(df: pd.DataFrame) -> pd.DataFrame:
+    out = []
+    for r in df.itertuples():
+        if r.frame_start == r.frame_stop:
+            out.append(
+                (int(r.frame_start), float(r.frac_start), float(r.frac_stop))
+            )
+            continue
+
+        out.append((int(r.frame_start), float(r.frac_start), 1.0))
+        for f in range(int(r.frame_start) + 1, int(r.frame_stop)):
+            out.append((f, 0.0, 1.0))
+        out.append((int(r.frame_stop), 0.0, float(r.frac_stop)))
+
+    return pd.DataFrame(out, columns=["frame", "frac_start", "frac_stop"])
+
+
+# -----------------------------------------------------------------------------
+# Mask building (fractions -> scanlines)
+# -----------------------------------------------------------------------------
+
+
+def _build_bad_line_mask(
+    df_split: pd.DataFrame,
+    T: int,
+    Y: int,
+    pad_rows: int = 0,
+) -> np.ndarray:
+    bad = np.zeros((T, Y), dtype=bool)
+
+    for r in df_split.itertuples(index=False):
+        t = int(r.frame)
+        if t < 0 or t >= T:
+            continue
+
+        y0 = int(np.floor(float(r.frac_start) * Y))
+        y1 = int(np.ceil(float(r.frac_stop) * Y))
+
+        y0 = max(0, y0 - pad_rows)
+        y1 = min(Y, y1 + pad_rows)
+
+        if y1 > y0:
+            bad[t, y0:y1] = True
+
+    return bad
+
+
+# -----------------------------------------------------------------------------
+# Nearest-neighbor 1D interpolation
+# -----------------------------------------------------------------------------
+
+
+def interpolate_nan(
+    movie_float: np.ndarray,
+    frame_index: np.ndarray,
+    donor_mask: np.ndarray,
+    require_n_good: int = 2,
+    num_channel: int = 1,
+    frame_gap: Optional[int] = None,
+) -> np.ndarray:
+    """
+    Fill NaNs using np.interp
+    """
+
+    T, Y, X = movie_float.shape
+    n_ttl = len(frame_index)
+
+    if T != n_ttl * num_channel:
+        raise ValueError(
+            f"T ({T}) must equal len(frame_index)*num_channel "
+            f"({n_ttl * num_channel})"
+        )
+
+    x = frame_index.astype(np.float32)
+    flat = movie_float.reshape(T, -1)
+
+    # Plane grouping
+    if frame_gap is None:
+        num_planes = 1
+        plane_ids = np.zeros(n_ttl, dtype=np.int32)
+    else:
+        num_planes = int(frame_gap) + 1
+        plane_ids = np.arange(n_ttl) % num_planes
+
+    for c in range(num_channel):
+        ys = flat[c::num_channel, :]  # (n_ttl, n_pixels)
+
+        if num_planes == 1:
+            _interp_block_numpy(ys, x, donor_mask, require_n_good)
+            continue
+
+        for p in range(num_planes):
+            idx = np.where(plane_ids == p)[0]
+            if len(idx) == 0:
+                continue
+
+            block = ys[idx, :]
+            _interp_block_numpy(
+                block,
+                x[idx],
+                donor_mask[idx],
+                require_n_good,
+            )
+            ys[idx, :] = block
+
+        flat[c::num_channel, :] = ys
+
+    return flat.reshape(T, Y, X)
+
+
+def _interp_block_numpy(
+    block: np.ndarray,
+    x: np.ndarray,
+    donor_mask: np.ndarray,
+    require_n_good: int,
+) -> None:
+    """
+    In-place linear interpolation using np.interp.
+    """
+
+    N, P = block.shape
+
+    for j in range(P):
+        y = block[:, j]
+        nans = np.isnan(y)
+        if not nans.any():
+            continue
+
+        good = donor_mask & ~nans
+        if good.sum() < require_n_good:
+            continue
+
+        x_good = x[good]
+        y_good = y[good]
+
+        # NumPy requires sorted x
+        # frame_index already sorted, but keep safe
+        order = np.argsort(x_good)
+        x_good = x_good[order]
+        y_good = y_good[order]
+
+        y[nans] = np.interp(x[nans], x_good, y_good)

stiminterp-0.1.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: stiminterp
+Version: 0.1
+Summary: Photostimulation artifact removal via interpolation
+Author-email: Sumiya Kuroda <s.kuroda@ucl.ac.uk>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/SainsburyWellcomeCentre/stiminterp
+Project-URL: Bug Tracker, https://github.com/SainsburyWellcomeCentre/stiminterp/issues
+Project-URL: Source Code, https://github.com/SainsburyWellcomeCentre/stiminterp
+Project-URL: User Support, https://github.com/SainsburyWellcomeCentre/stiminterp/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: BSD License
+Requires-Python: >=3.10.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: tifffile
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: PyYAML
+Requires-Dist: fancylog
+Requires-Dist: matplotlib
+Requires-Dist: pandas
+Requires-Dist: tqdm
+Requires-Dist: scikit-learn
+Requires-Dist: scikit-image
+Requires-Dist: scanimage-tiff-reader
+Requires-Dist: h5py
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: setuptools_scm; extra == "dev"
+Dynamic: license-file
+
+[![Python
+Version](https://img.shields.io/pypi/pyversions/stiminterp.svg)](https://pypi.org/project/stiminterp)
+[![PyPI
+Version](https://img.shields.io/pypi/v/stiminterp.svg)](https://pypi.org/project/stiminterp)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-orange.svg)](https://opensource.org/licenses/BSD-3-Clause)
+
+# stiminterp
+
+**stiminterp** provides an 1D-interpolation-based solution for removing
+photostimulation artefacts from multiphoton calcium imaging data.
+
+The holographic stimulation saturates the PMTs and causes data loss. By identifying lines with the stimulation artefacts, this pipeline can replace the pixel rows containing the stimulation artefacts with the average values from corresponding rows in the preceding and following frames.
+
+------------------------------------------------------------------------
+
+## Installation
+
+Create a fresh environment and install via pip:
+
+    conda create -n stiminterp-env python=3.12
+    conda activate stiminterp-env
+    pip install stiminterp
+
+------------------------------------------------------------------------
+
+## Overview
+
+Understanding the causal role of brain dynamics is one of the fundamental questions in systemns neuroscience. Multiphoton holographic optogenetics, combined with multiphoton calcium imaging, enables causal testing of circuit models at single-cell resolution. However, photostimulation can saturate PMTs, producing line artefacts in the imaging data.
+
+With `stiminterp` you can:
+
+-   Detect artefact-contaminated lines from HDF5 generated by ScanImage
+-   Perform spatiotemporal 1D-interpolation using `scipy.interpolate`
+-   Recover calcium imaging movies that can be fed into standard analysis pipelines such as `suite2p`
+------------------------------------------------------------------------
+
+## Data Source & Funding
+
+Sample data used for examples will be publicly available in the near future.
+
+All microscopy data has been acquired using a custom two-photon microscope by [Sumiya Kuroda](https://github.com/sumiya-kuroda) in the [Mrsic-Flogel Lab](https://www.sainsburywellcome.org/web/groups/mrsic-flogel-lab) and Dale Elgar from [COSYS Ltd.](https://www.cosys.org.uk/).
+
+This work represents a joint collaboration between Stanford University and the Sainsbury Wellcome Centre for Neural Circuits and Behaviour, University College London, supported by the Gatsby Charitable Foundation.
+
+------------------------------------------------------------------------
+
+## References
+
+Previous work on artefact removal of all-optical imaging movies:
+- [Drinnenberg et al, 2025, bioRxiv](https://www.biorxiv.org/content/10.1101/2025.10.21.683734v1)
+- [Attinger et al, 2025, bioRxiv](https://www.biorxiv.org/content/10.1101/2025.10.21.683723v1)
+
+This package was inspired by [previous calcium imaging analysis pipeline at Deisseroth lab](https://github.com/deisseroth-lab/two-photon/tree/main).
+
+This repo was made using [neuroinformatics-unit/python-cookiecutter](https://github.com/neuroinformatics-unit/python-cookiecutter). See [here](https://python-cookiecutter.neuroinformatics.dev/) for more info.
+
+------------------------------------------------------------------------
+
+## Contributing
+
+Contributions are welcome. Please open an issue or submit a pull request
+on GitHub.
+
+------------------------------------------------------------------------
+
+## License
+
+BSD-3-Clause

stiminterp-0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+stiminterp/__init__.py,sha256=JoNB-7HQLr1HndEMytwpXp_DwhsyEb9pWaV-OQGES3g,349
+stiminterp/pipeline.py,sha256=tfVVt6V7M7iypFJlR-ELU9TC5-W2b0t7KOph8oUdZQ8,1328
+stiminterp/stim_interpolate.py,sha256=SLPKi8zXpbd7TZSTtVl0SbAl8A6M9FEKWSQWRSPi6xc,10692
+stiminterp/load_data/custom_data_loader.py,sha256=NIVMg0aKypvzrHuVtfR1Tjg9J8EstT_4s2NmsNgEJcA,3236
+stiminterp/load_data/scanimage_metadata.py,sha256=Dv22tm1-qKonLxWotalJx5H5BwSqxxuqYY6yErsIq64,5137
+stiminterp/plotting_hooks/sanity_check.py,sha256=iQxstWOihSfpVuKdOpR2IUyEVat9kes-JdmFOaNVk24,1959
+stiminterp-0.1.dist-info/licenses/LICENSE,sha256=5m5N81VhYYpXw_lIVFMjIf_IIx-BJxn7RX4C5RuoYjQ,1482
+stiminterp-0.1.dist-info/METADATA,sha256=STz7HVzyfMKgUK38M7IDDkAKPpYh02UWDTKwxl8kvRc,5099
+stiminterp-0.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+stiminterp-0.1.dist-info/top_level.txt,sha256=eBlYdz1-bU8B8sVmunLVsv4ixNKh4fGjC6BxknFft54,11
+stiminterp-0.1.dist-info/RECORD,,

stiminterp-0.1.dist-info/WHEEL

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

stiminterp-0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+
+Copyright (c) 2026, Sumiya Kuroda
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of stiminterp nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

stiminterp-0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+stiminterp