feature_computation.compute_features_from_raw

feature_computation.compute_features_from_raw(
    raw_ap,
    raw_lf,
    fs_ap=None,
    fs_lf=None,
    geometry=None,
    channel_labels=None,
    neuropixel_version=1,
    features_to_compute=None,
    output_dir=Path('.'),
    scratch_dir=None,
    lf_k_filter=False,
    skip_lf_destripe=False,
    feature_params=None,
    **kwargs,
)

Compute electrophysiological features from raw numpy arrays of AP and LF data.

This function is the core feature computation engine that processes raw electrophysiological data and computes various feature sets. It handles data destriping, feature computation for different modalities (LF, CSD, AP, waveforms), and optionally saves results to files. The function supports both computation and loading of cached features.

Args: raw_ap (np.ndarray, optional): AP voltage array shaped (n_channels, n_samples). Supply None to disable AP feature computation. raw_lf (np.ndarray, optional): LF voltage array shaped (n_channels, n_samples). Supply None to disable LF/CSD feature computation. fs_ap (float, optional): Sampling frequency (Hz) for the AP stream. Must be positive when raw_ap is provided. fs_lf (float, optional): Sampling frequency (Hz) for the LF stream. Must be positive when raw_lf is provided. geometry (dict): Mapping containing at least "x" and "y" arrays describing channel coordinates. Assumed to be a single shank (as IBL pids are): the CSD/BPR, Cadzow denoising and spike/waveform features use the channels’ x, y only, so shanks sharing (x, y) positions get mixed. Split multi-shank recordings per shank first. channel_labels (np.ndarray, optional): Per-channel label array used to mask bad channels during destriping. Defaults to zeros matching the available data. neuropixel_version (int): Neuropixel probe version passed to the destriper. features_to_compute (list, optional): Feature families to evaluate. None computes all supported families for the given inputs. Supported values are ["lf", "csd", "ap", "waveforms"]. output_dir (Path, optional): Directory where individual feature parquet files (and optional waveform artifacts) are written. None skips writing to disk. scratch_dir (Path, optional): Location for temporary scratch data used by waveform extraction. lf_k_filter (bool | None, optional): Spatial-filter mode passed to :func:ibldsp.voltage.destripe_lfp. The default False preserves the current CAR behavior; use None to bypass LF spatial filtering. skip_lf_destripe (bool, optional): Skip destripe_lfp entirely and use raw_lf as-is. False reproduces today’s behavior; use True for LF that has already been destriped/CAR’d/decimated upstream (see :func:destripe_ap_lf). feature_params (optional): Optional FeatureParams-like object used to override the per-feature kwargs. Read duck-typed (.lf / .csd attributes) so this module carries no dependency on the feature_calculators package. When None the defaults reproduce today’s behavior exactly. A truthy feature_params.lf.compute_rms_no_car additionally enables the rms_lf_no_car LF feature. **kwargs: Extra options controlling the workflow, such as skip_saved_computation or save_waveforms.

Returns: pd.DataFrame: Outer-joined feature table keyed by channel.

Raises: ValueError: If neither AP nor LF data is supplied, or if an unsupported feature family is requested. AssertionError: If provided arrays are not 2D, geometry dimensions do not align, or sampling frequencies are invalid for the requested streams.

Example: >>> import numpy as np >>> raw_ap = np.random.randn(384, 30000) >>> raw_lf = np.random.randn(384, 3000) >>> geometry = {‘x’: np.arange(384), ‘y’: np.arange(384)} >>> df = compute_features_from_raw( … raw_ap=raw_ap, raw_lf=raw_lf, fs_ap=30000, fs_lf=2500, … geometry=geometry, features_to_compute=[‘lf’, ‘ap’] … )

Notes: - AP and LF streams are destriped before feature computation. - Existing parquet outputs can be reused when skip_saved_computation is True. - Waveform features emit optional waveform files when save_waveforms is set. - Each feature DataFrame is annotated with ibleatools and feature module versions for provenance tracking.