filtering

filtering ¶

Temporal filtering and interpolation for perfusion data.

This module provides functions for temporal filtering, smoothing, and interpolation of time-series perfusion data.

All operations are GPU/CPU agnostic using the xp array module pattern. NO scipy dependencies - see XP Compatibility Requirements in plan.md.

temporal_filter ¶

temporal_filter(
    data, filter_type="gaussian", sigma=1.0, window_size=3
)

Apply temporal filtering to time-series data.

GPU/CPU agnostic implementation using FFT-based convolution. No scipy dependency.

PARAMETER	DESCRIPTION
`data`	Time-series data. Last dimension is time. TYPE: `NDArray[floating]`
`filter_type`	Filter type: - "gaussian": Gaussian smoothing (sigma controls width) - "moving_average": Moving average (window_size controls width) - "median": Median filter (window_size controls width) TYPE: `str` DEFAULT: `"gaussian"`
`sigma`	Standard deviation for Gaussian filter (in time points). TYPE: `float` DEFAULT: `1.0`
`window_size`	Window size for moving average or median filter. TYPE: `int` DEFAULT: `3`

RETURNS	DESCRIPTION
`NDArray[floating]`	Filtered data with same shape as input.

RAISES	DESCRIPTION
`ValueError`	If invalid filter_type or parameters.

Examples:

>>> import numpy as np
>>> from osipy.common.signal.filtering import temporal_filter
>>> data = np.random.rand(64, 64, 20, 30)
>>> smoothed = temporal_filter(data, filter_type="gaussian", sigma=1.0)

temporal_interpolate ¶

temporal_interpolate(
    data, time_old, time_new, method="linear"
)

Interpolate time-series data to new time points.

GPU/CPU agnostic implementation. No scipy dependency.

PARAMETER	DESCRIPTION
`data`	Time-series data. Last dimension is time with length len(time_old). TYPE: `NDArray[floating]`
`time_old`	Original time points. TYPE: `NDArray[floating]`
`time_new`	Target time points for interpolation. TYPE: `NDArray[floating]`
`method`	Interpolation method: - "linear": Linear interpolation - "cubic": Cubic spline interpolation - "nearest": Nearest neighbor TYPE: `str` DEFAULT: `"linear"`

RETURNS	DESCRIPTION
`NDArray[floating]`	Interpolated data with last dimension length len(time_new).

RAISES	DESCRIPTION
`ValueError`	If time arrays have invalid shapes or method is unknown.

Examples:

>>> import numpy as np
>>> from osipy.common.signal.filtering import temporal_interpolate
>>> data = np.random.rand(64, 64, 20, 30)
>>> time_old = np.linspace(0, 300, 30)
>>> time_new = np.linspace(0, 300, 60)  # Upsample to 60 points
>>> interpolated = temporal_interpolate(data, time_old, time_new)
>>> print(interpolated.shape)
(64, 64, 20, 60)

resample_to_uniform ¶

resample_to_uniform(data, time, dt=None)

Resample non-uniform time series to uniform temporal spacing.

GPU/CPU agnostic implementation. No scipy dependency.

PARAMETER	DESCRIPTION
`data`	Time-series data. Last dimension is time. TYPE: `NDArray[floating]`
`time`	Original (possibly non-uniform) time points. TYPE: `NDArray[floating]`
`dt`	Target temporal resolution. If None, uses minimum time difference in original data. TYPE: `float \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`tuple[NDArray, NDArray]`	(resampled_data, new_time_points)

Examples:

>>> import numpy as np
>>> from osipy.common.signal.filtering import resample_to_uniform
>>> # Non-uniform sampling
>>> time = np.array([0, 1, 2, 5, 10, 15, 20])
>>> data = np.random.rand(64, 64, 20, len(time))
>>> resampled, new_time = resample_to_uniform(data, time, dt=1.0)