Cortexlab Python Utilities for Functional Ultrasound Imaging

This repository contains a collection of Python utilities for loading and processing tasks that are specific to the Cortexlab's functional ultrasound imaging (fUSI) rig. This includes functions for loading behavioral recordings and synchronizing fUSI data with behavioral data. Meanwhile, all general-purpose features have been implemented in the ConfUSIus package.

Features

Timeline & Synchronization:

• Load fUSI acquisition times directly from Timeline.mat — Extract IQ block timing without needing intermediate alignment files.
• Load Timeline timestamps — Access the raw DAQ timestamps for custom synchronization.
• Load photodiode transitions — Recover hardware display transitions from Timeline.
• Synchronize camera frame times — Align camera data to Timeline using blackout detection.

Stimulus Metadata (MPEP):

• Load raw MPEP UDP events — Inspect experiment, block, and stimulus messages.
• Load Protocol.mat stimulus tables — Access xfile parameters and presentation metadata.
• Load stimulus events with optional photodiode refinement — Build event tables suitable for analysis and BIDS-style workflows.

Behavioral Data:

• Load wheel velocity data — Process rotary encoder data from Timeline.
• Load pupil size data — Extract pupil area from Facemap motSVD files.
• Load eye position data — Extract pupil coordinates from Facemap motSVD files.
• Load motion SVD data — Extract behavioral movement components from Facemap.

Flexible Data Loading:

• Optional binning — Get raw data at native sampling rates or bin to target times.
• Preserves timing precision — Maintains actual capture timing with hardware jitter.

Quick Start

from cortexlab_fusi_utils.io import (
    load_iq_block_times,
    load_pupil_size,
    load_stimulus_events,
    load_wheel_velocity,
)

# Load fUSI acquisition times from Timeline.mat.
fusi_block_times = load_iq_block_times("path/to/Timeline.mat")

# Load wheel velocity binned to fUSI frame times.
wheel_df = load_wheel_velocity(
    rotary_encoder_path="path/to/rotaryEncoder.raw.npy",
    timeline_path="path/to/Timeline.mat",
    target_times=fusi_block_times,
)
wheel_df["wheel_velocity"]

# Load camera-based behavioral data (from Facemap output).
pupil_df = load_pupil_size(
    camera_file_path="path/to/session_eyeCamRight_motSVD.npz",
    timeline_path="path/to/Timeline.mat",
    target_times=fusi_block_times,
)
pupil_df["pupil_size"]

# Load MPEP stimulus events, optionally merging Protocol.mat metadata.
stimulus_df = load_stimulus_events(
    "path/to/Timeline.mat",
    protocol_path="path/to/Protocol.mat",
    timing_source="auto",
)
stimulus_df[["onset", "duration", "trial_type"]]