cortexlab_fusi_utils.io¶

Resolve full path and check its type.

Parameters:

• path ¶

  (str or Path) –

  Path to check validity.

• label ¶

  (str, default: "path" ) –

  Name of the variable passed to check_path, used in the error message.

• type ¶

  ((file, dir), default: "file" ) –

  Type of path to check for. If "file", checks that the path is a file. If "dir", checks that the path is a directory. If not provided, no type check is performed, meaning the path may not exist.

Returns:

• Path –

  If successful, the path resolved to its full path.

Raises:

• TypeError –

  If path cannot be cast to pathlib.Path.

• ValueError –

  If type is not None and the path is not of the correct type.

Compute eye movement speed from position data.

Parameters:

• eye_position ¶

  ((n_timepoints, 2) numpy.ndarray) –

  Eye position as (x, y) coordinates in pixels.

• dt ¶

  (float) –

  Time step between samples in seconds.

Returns:

• (n_timepoints,) numpy.ndarray –

  Eye movement speed in pixels per second.

Examples:

>>> times, eye_pos = load_eye_position(...)
>>> sampling_rate = 3.33  # Hz
>>> dt = 1 / sampling_rate
>>> eye_mvt = compute_eye_movement(eye_pos, dt)

Load acquisition metadata from a CortexLab AUTC fUSI rig MAT file.

This function reads the rig-specific MAT file (v7.3 / HDF5 format) produced by the CortexLab AUTC fUSI rig and extracts the spatial coordinates, probe parameters, and acquisition parameters used by confusius and related pipelines. The internal HDF5 structure (doppler/params/parSeq and its field names) is specific to this rig and may not match MAT files produced by other AUTC setups.

Parameters:

• meta_path ¶

  (str or Path) –

  Path to the CortexLab AUTC fUSI rig sequence parameter file (MAT v7.3 / HDF5 format, typically named *_fus.mat).

Returns:

• AUTCMetadata –

  Dictionary containing the extracted metadata fields.

Raises:

• FileNotFoundError –

  If meta_path does not exist or is not a file.

Load camera frame times synchronized to Timeline.

This function loads camera frame times from a frame times MAT file and synchronizes them to Timeline using blackout detection. The blackout is a brief period at the start of the session where all cameras are turned off to provide a synchronization marker.

Parameters:

• frame_times_path ¶

  (str or Path) –

  Path to the *_frameTimes.mat file containing camera frame timestamps.

• video_path ¶

  (str or Path) –

  Path to the .mj2 video file for blackout detection.

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

• ratio_detection ¶

  (float, default: 0.5 ) –

  Intensity ratio threshold for blackout detection. Frames with mean intensity below ratio_detection * reference_intensity are considered part of the blackout.

• cam_sync_channel_name ¶

  (str, default: `"camSync"` ) –

  Name of the channel in Timeline's hw.inputs list that carries the camera sync signal.

Returns:

• ndarray –

  Camera frame times in seconds (Timeline reference frame). The length of this array corresponds to the number of camera frames acquired.

Raises:

• FileNotFoundError –

  If the frame times file, video file, or Timeline file is not found.

• ValueError –

  If the blackout cannot be detected in the video or camSync channel is missing.

Examples:

>>> camera_times = load_camera_frame_times(
...     "2024-01-15_001_ALD020_eyeCamRight_frameTimes.mat",
...     "2024-01-15_001_ALD020_eyeCamRight.mj2",
...     "Timeline.mat"
... )
>>> # Use these times to bin camera-based metrics to target times.
>>> pupil_data = ...  # load pupil data
>>> binned_pupil = binned_statistic(camera_times, pupil_data, bins=target_bins)

Load and preprocess a Doric fiber photometry recording.

Runs the complete preprocessing pipeline:

1. Load raw signals from the .doric HDF5 file.
2. Align to Timeline — maps Doric timestamps to the Rigbox Timeline reference frame using a shared TTL sync signal (flipper).
3. Discard initial duration (optional) — removes the leading segment of the Timeline-aligned recording (e.g., to avoid LED switch-on artefacts). Performed after alignment so that all flipper pulses are available during the alignment step.
4. Demultiplex — separates the raw multiplexed detector output into the 465 nm (calcium-sensitive) and 405 nm (isosbestic control) channels based on the LED control signals.
5. Correct photobleaching (optional) — fits and subtracts a double exponential baseline from each channel.
6. Bin to target times (optional) — averages each channel into bins centred on target_times (e.g., fUSI block times).

Parameters:

• file_path ¶

  (str or Path) –

  Path to the .doric file.

• signal_name ¶

  (str) –

  Name of the analog input channel to preprocess (e.g., "AIN01").

• timeline_path ¶

  (str or Path) –

  Path to the session_Timeline.mat file. Signals are aligned to the Timeline reference frame before demultiplexing.

• led_465_name ¶

  (str, default: ``"AOUT01"`` ) –

  Name of the 465 nm LED control signal. Looked up first in AnalogOut, then in DigitalIO.

• led_405_name ¶

  (str, default: ``"AOUT02"`` ) –

  Name of the 405 nm LED control signal.

• flipper_signal_name ¶

  (str, default: ``"DIO01"`` ) –

  Digital channel in the Doric file that carries the flipper sync signal.

• flipper_channel_name ¶

  (str, default: ``"flipper"`` ) –

  Name of the flipper channel in Timeline's hw.inputs list.

• delay_start ¶

  (int, default: 0 ) –

  Samples to skip after each LED onset before averaging. Compensates for hardware transients at the start of each excitation period.

• delay_end ¶

  (int, default: 0 ) –

  Samples to extend past each LED offset when averaging.

• correct_photobleaching ¶

  (bool, default: True ) –

  Whether to fit and subtract a double exponential photobleaching baseline from each channel after demultiplexing.

• discard_initial_duration ¶

  (float, default: 0.0 ) –

  Seconds to discard from the start of the raw recording before Timeline alignment and demultiplexing. Useful for removing LED switch-on artefacts. Set to 0.0 to keep the full recording.

• target_times ¶

  ((n_bins,) numpy.ndarray, default: None ) –

  Target timepoints for binning (e.g., fUSI block times from :func:~cortexlab_fusi_utils.io.load_iq_block_times). When provided, each channel is averaged within bins centred on these times. If None, signals are returned at the native demultiplexed rate.

Returns:

• DataFrame –

  DataFrame with a "time"-named index and two columns:

  • signal_465: preprocessed 465 nm (calcium-sensitive) channel.
  • signal_405: preprocessed 405 nm (isosbestic control) channel.

  The index equals target_times when provided, otherwise the centre time of each 465 nm LED period.

Raises:

• FileNotFoundError –

  If file_path does not exist.

• KeyError –

  If signal_name, led_465_name, led_405_name, or flipper_channel_name are not found in the file or Timeline data.

• ValueError –

  If no LED transitions are found after alignment, or if the flipper signal is absent from the Doric file.

Examples:

Load and bin to fUSI block times:

>>> from cortexlab_fusi_utils.io import load_iq_block_times
>>> block_times = load_iq_block_times("session_Timeline.mat")
>>> df = load_doric(
...     "session.doric",
...     signal_name="AIN01",
...     timeline_path="session_Timeline.mat",
...     target_times=block_times,
... )
>>> df["signal_465"]
>>> df["signal_405"]

Load at native demultiplexed rate without photobleaching correction:

>>> df = load_doric(
...     "session.doric",
...     signal_name="AIN01",
...     timeline_path="session_Timeline.mat",
...     correct_photobleaching=False,
... )

Load eye position data from a Facemap motSVD.npz file.

Parameters:

• camera_file_path ¶

  (str or Path) –

  Path to the *_motSVD.npz file containing pupil tracking data.

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

• target_times ¶

  (ndarray, default: None ) –

  Target time points for binning (typically fUSI frame times). If not provided, returns raw unbinned data at camera frame times.

• cam_sync_channel_name ¶

  (str, default: `"camSync"` ) –

  Name of the channel in Timeline's hw.inputs list that carries the camera sync signal.

• resample_method ¶

  ((bin, fir), default: "bin" ) –

  Method used to align eye position to target_times when provided.

  • "bin" computes mean eye position within target-time bins.
  • "fir" applies FIR anti-alias decimation when downsampling and then linearly interpolates to target_times.

Returns:

• DataFrame –

  DataFrame with a "time"-named index and two columns:

  • x: horizontal pupil position in pixels.
  • y: vertical pupil position in pixels.

  The index equals target_times when provided, otherwise the camera frame times.

Raises:

• FileNotFoundError –

  If the camera file or Timeline file is not found.

• ValueError –

  If the npz file does not contain the required 'pupil_pos' key.

Examples:

Load and bin eye position to fUSI frame times:

>>> from cortexlab_fusi_utils.io import load_iq_block_times
>>> block_times = load_iq_block_times("Timeline.mat")
>>> df = load_eye_position(
...     "2024-01-15_001_ALD020_eyeCamRight_motSVD.npz",
...     "Timeline.mat",
...     block_times
... )
>>> df["x"]
>>> df["y"]

Load raw unbinned eye position at camera frame times:

>>> df = load_eye_position(
...     "2024-01-15_001_ALD020_eyeCamRight_motSVD.npz",
...     "Timeline.mat"
... )

Load beamformed IQ block onset times from Timeline.

Extracts the timing of each IQ acquisition block from the Timeline recording. Using the standard EchoFrame sequence, each TTL pulse corresponds to the start of an acquisition block.

Parameters:

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

• neural_frames_channel_name ¶

  (str, default: `"neuralFrames"` ) –

  Name of the channel in Timeline's hw.inputs list that carries the neural frames TTL signal.

Returns:

• ndarray –

  TTL onset times in seconds (Timeline reference frame). The length of this array corresponds to the number of IQ blocks acquired.

Examples:

>>> block_times = load_iq_block_times("Timeline.mat")
>>> # Compute mean block duration.
>>> block_duration = np.mean(np.diff(block_times))
>>> # Compute sampling rate.
>>> sampling_rate = 1.0 / block_duration

Load motion SVD coefficients from motSVD file.

Parameters:

• camera_file_path ¶

  (str or Path) –

  Path to the *_motSVD.npz file containing motion SVD data.

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

• target_times ¶

  (ndarray, default: None ) –

  Target time points for binning (typically fUSI frame times). If not provided, returns raw unbinned data at camera frame times.

• svd_type ¶

  (str, default: "motion_tc" ) –

  Type of SVD data to load. Options: "motion_tc" (motion energy) or "movie_tc" (raw video frames).

• apply_zscore ¶

  (bool, default: True ) –

  Whether to z-score each SVD component independently.

• cam_sync_channel_name ¶

  (str, default: `"camSync"` ) –

  Name of the channel in Timeline's hw.inputs list that carries the camera sync signal.

• resample_method ¶

  ((bin, fir), default: "bin" ) –

  Method used to align motion SVD to target_times when provided.

  • "bin" computes mean component values within target-time bins.
  • "fir" applies FIR anti-alias decimation when downsampling and then linearly interpolates to target_times.

Returns:

• DataFrame –

  DataFrame with a "time"-named index and one column per SVD component, named component_00, component_01, etc. (zero-padded to the width needed for the total number of components).

  The index equals target_times when provided, otherwise the camera frame times.

Raises:

• FileNotFoundError –

  If the camera file or Timeline file is not found.

• ValueError –

  If the npz file does not contain the required SVD key or invalid svd_type.

Examples:

Load and bin motion SVD to fUSI frame times:

>>> from cortexlab_fusi_utils.io import load_iq_block_times
>>> block_times = load_iq_block_times("Timeline.mat")
>>> df = load_motion_svd(
...     "2024-01-15_001_ALD020_frontCam_motSVD.npz",
...     "Timeline.mat",
...     block_times,
...     svd_type="motion_tc"
... )
>>> df["component_00"]

Load raw unbinned motion SVD at camera frame times:

>>> df = load_motion_svd(
...     "2024-01-15_001_ALD020_frontCam_motSVD.npz",
...     "Timeline.mat",
...     svd_type="motion_tc"
... )

Load photodiode onset and offset transition times from Timeline.

Parameters:

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

• photo_diode_channel_name ¶

  (str, default: `"photoDiode"` ) –

  Name of the channel in Timeline's hw.inputs list that carries the photodiode signal.

• threshold ¶

  (float, default: 0.0 ) –

  Threshold applied after centering the photodiode trace by its median.

Returns:

• DataFrame –

  One row per photodiode transition with columns:

  • time: transition time in seconds in the Timeline reference frame.
  • event_type: either "onset" or "offset".

Load pupil size data from a Facemap motSVD.npz file.

Parameters:

• camera_file_path ¶

  (str or Path) –

  Path to the *_motSVD.npz file containing pupil tracking data.

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

• target_times ¶

  (ndarray, default: None ) –

  Target time points for binning (typically fUSI frame times). If not provided, returns raw unbinned data at camera frame times.

• normalize_by_median ¶

  (bool, default: True ) –

  Whether to normalize pupil size by dividing by the median value.

• cam_sync_channel_name ¶

  (str, default: `"camSync"` ) –

  Name of the channel in Timeline's hw.inputs list that carries the camera sync signal.

• resample_method ¶

  ((bin, fir), default: "bin" ) –

  Method used to align pupil size to target_times when provided.

  • "bin" computes mean pupil size within target-time bins.
  • "fir" applies FIR anti-alias decimation when downsampling and then linearly interpolates to target_times.

Returns:

• DataFrame –

  DataFrame with a "time"-named index and a single column:

  • pupil_size: pupil size in pixels, or normalized units if normalize_by_median is True.

  The index equals target_times when provided, otherwise the camera frame times.

Examples:

>>> from cortexlab_fusi_utils.io import load_iq_block_times
>>> block_times = load_iq_block_times("Timeline.mat")
>>> df = load_pupil_size(
...     "2024-01-15_001_ALD020_eyeCamRight_motSVD.npz",
...     "Timeline.mat",
...     block_times
... )
>>> df["pupil_size"]

Load matched MPEP stimulus epochs from Timeline UDP events.

This function matches StimStart and StimEnd messages using the (block_repeat, trial_type) pair. When requested, stimulus timing is refined using Timeline photodiode transitions. When a protocol_path is provided, the resulting event table is augmented with the corresponding xfile parameter columns.

Parameters:

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

• protocol_path ¶

  (str or Path, default: None ) –

  Path to the matching Protocol.mat file. When provided, stimulus parameter columns are merged into the returned event table.

• onset_reference_time ¶

  (float, default: 0.0 ) –

  Reference time in seconds subtracted from each absolute stimulus onset. Use this to express onsets relative to another acquisition clock, e.g. the first fUSI sample time.

• timing_source ¶

  ((auto, photodiode, software), default: "auto" ) –

  Timing source used for the returned onset and duration columns. "auto" prefers photodiode timing when available and falls back to software timing otherwise. "photodiode" requires successful photodiode matching. "software" uses only MPEP UDP timing.

• photo_diode_channel_name ¶

  (str, default: `"photoDiode"` ) –

  Name of the channel in Timeline's hw.inputs list that carries the photodiode signal.

• photodiode_pad_s ¶

  (float, default: 1 / 60 ) –

  Small padding added around software start/end times when searching for matching photodiode transitions.

Returns:

• DataFrame –

  One row per matched stimulus epoch with columns:

  • onset
  • duration
  • trial_type
  • block_repeat
  • stimulus_duration_code
  • timing_source
  • software_onset
  • software_duration
  • hardware_onset
  • hardware_duration
  • source_event
  • optional protocol-derived columns when protocol_path is provided.

  Column descriptions are available in DataFrame.attrs["column_descriptions"]. When protocol_path is provided, the xfile name is also stored in DataFrame.attrs["xfile"].

Load stimulus parameter definitions from an MPEP Protocol.mat file.

MPEP writes one Protocol.mat file per experiment. It contains the xfile name, stimulus parameter matrix, parameter names and descriptions, and the presentation ordering metadata for the run.

Parameters:

• protocol_path ¶

  (str or Path) –

  Path to the Protocol.mat file written by MPEP.

Returns:

• DataFrame –

  One row per stimulus definition with columns:

  • trial_type: stimulus index as referenced by MPEP UDP events.
  • xfile: stimulus xfile name.
  • one column per entry in Protocol.parnames.

  The parameter columns keep the original names defined by the xfile.

Load raw DAQ timestamps from Timeline.

Extracts the timestamp for each sample in Timeline's DAQ recording. These timestamps are the common reference frame for all signals recorded by Timeline.

Parameters:

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

Returns:

• dict –

  Dictionary containing:

  • timestamps: numpy.ndarray of raw DAQ timestamps in seconds.
  • input_channels: list of dicts with information about each input channel.
  • daq_data: numpy.ndarray of raw DAQ data samples.

Examples:

>>> timestamps = load_timeline_timestamps("Timeline.mat")
>>> # Compute DAQ sampling rate.
>>> sampling_rate = 1.0 / np.median(np.diff(timestamps))

Load raw MPEP UDP events from Timeline.

The Timeline.mat file stores UDP messages emitted by MPEP during the experiment. This function returns those messages as a table without trying to interpret stimulus epochs.

Parameters:

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

Returns:

• DataFrame –

  One row per UDP event with columns:

  • time: event time in seconds in the Timeline reference frame.
  • event: original raw UDP event string.
  • event_type: first whitespace-delimited token of event.
  • tokens: whitespace-tokenized version of event.

Load wheel velocity data from rotary encoder.

Parameters:

• rotary_encoder_path ¶

  (str or Path) –

  Path to the rotary encoder data file.

• timeline_path ¶

  (str or Path) –

  Path to the Timeline.mat file containing Timeline's data.

• target_times ¶

  (ndarray, default: None ) –

  Target time points for binning (typically fUSI frame times). If None, returns raw unbinned data at Timeline timestamps.

• diameter_cm ¶

  (float, default: 20.0 ) –

  Diameter of the wheel in centimeters.

• ticks_per_cycle ¶

  (int, default: 4096 ) –

  Number of encoder ticks per full wheel rotation.

• smooth_width_sec ¶

  (float, default: 0.03 ) –

  Width of the Gaussian smoothing kernel in seconds, or None for no smoothing.

• resample_method ¶

  ((bin, fir), default: "bin" ) –

  Method used to align wheel velocity to target_times when provided.

  • "bin" computes mean velocity within target-time bins.
  • "fir" applies FIR anti-alias decimation when downsampling and then linearly interpolates to target_times.

Returns:

• DataFrame –

  DataFrame with a "time"-named index and a single column:

  • wheel_velocity: wheel velocity in cm/s.

  The index equals target_times when provided, otherwise the Timeline timestamps.

Raises:

• FileNotFoundError –

  If wheel position file or Timeline file is not found.

Examples:

Load and bin wheel velocity to fUSI frame times:

>>> from cortexlab_fusi_utils.io import load_iq_block_times
>>> block_times = load_iq_block_times("Timeline.mat")
>>> df = load_wheel_velocity("rotaryEncoder.raw.npy", "Timeline.mat", block_times)
>>> df["wheel_velocity"]

Load raw unbinned wheel velocity at Timeline timestamps:

>>> df = load_wheel_velocity("rotaryEncoder.raw.npy", "Timeline.mat")