`cortexlab_fusi_utils.bids`¶

bids ¶

BIDS conversion utilities for fUSI data.

Modules:

io –

File finding and fUSI data loading utilities for BIDS conversion.
physio –

Physiology data conversion utilities.
sidecar –

BIDS sidecar JSON building utilities.

Classes:

DataPathResolver –

Resolves data paths for a given animal.
SequenceMetadata –

Metadata extracted from a _fus.mat file plus computed values.
SpatialInfo –

Spatial information computed from AUTCMetadata.
VoxelDimensions –

Voxel dimensions in millimeters.

Functions:

build_functional_sidecar –

Build the complete BIDS sidecar JSON for a functional fUSI scan.
build_scans_tsv –

Build a *_scans.tsv DataFrame for a single subject.
build_sequence_sidecar –

Build the sequence-parameter portion of a BIDS fUSI sidecar JSON.
convert_physio_session –

Convert physiology data for one recording session to BIDS physio files.
find_bids_paths –

Return absolute BIDS paths for a subject, optionally filtered.
find_fus_mat –

Return the path to the _fus.mat file for a recording session.
find_mot_svd_files –

Return available Facemap motSVD NPZ files for a recording session.
find_rotary_encoder –

Return the path to the rotary encoder file for a recording session.
find_timeline_mat –

Return the path to the Timeline.mat file for a recording session.
get_data_path_resolver –

Get the current data path resolver.
load_angio_as_nifti –

Load the latest reference (angiography) scan and return as a NIfTI image.
load_fusi_as_nifti –

Load a preprocessed fUSI file and return a NIfTI image.
load_sequence_metadata –

Load sequence acquisition metadata from the _fus.mat HDF5 file.
save_physio_bids –

Save physiological data to BIDS format (TSV.gz + JSON sidecar).
set_data_path_resolver –

Set the global data path resolver.

DataPathResolver ¶

Resolves data paths for a given animal.

Parameters:

animal_data_path_func ¶
(callable) –

Function that takes an animal ID and returns its data root path.
iq_blocks_per_doppler_frame ¶
(int) –

Number of IQ blocks per Doppler frame (from preprocessing).
doppler_frames_per_clutter_window ¶
(int) –

Number of Doppler frames per clutter filter window.
camera_names ¶
(tuple[str, ...], default: ("eyeCamRight", "eyeCamLeft", "frontCam", "bellyCam") ) –

Ordered camera names used to search for motion SVD files.
fusi_filename_pattern ¶
(str, default: 'fUSi_preprocessed_{date}_{session}_50.npz' ) –

Format string for fUSI NPZ filenames. Variables: {date}, {session}, {animal}.
fus_filename_pattern ¶
(str, default: '{date}_{session}_{animal}_fus.mat' ) –

Format string for _fus.mat filenames. Variables: {date}, {session}, {animal}.
timeline_filename_pattern ¶
(str, default: '{date}_{session}_{animal}_Timeline.mat' ) –

Format string for Timeline.mat filenames. Variables: {date}, {session}, {animal}.

Methods:

animal_root –

Return the root data directory for an animal.
available_mot_svds –

Return available motion-SVD files for one session.
fus_mat –

Return the expected path to the raw _fus.mat file.
fusi_npz –

Return the expected path to the preprocessed fUSI archive.
mot_svd_for_camera –

Return the expected motion-SVD NPZ path for one camera and session.
reference_scan –

Return the latest angiography reference scan for an animal.
rotary_encoder –

Return the expected path to the rotary encoder recording.
timeline_mat –

Return the expected path to the raw Timeline.mat file.

Attributes:

camera_names (tuple[str, ...]) –

Return camera names searched for motion SVD files.

camera_names `property` ¶

camera_names: tuple[str, ...]

Return camera names searched for motion SVD files.

Returns:

tuple[str, ...] –

Ordered camera names used to locate motSVD files.

animal_root ¶

animal_root(animal: str) -> Path

Return the root data directory for an animal.

Parameters:

animal ¶
(str) –

Animal identifier.

Returns:

Path –

Root directory containing the animal's source data.

available_mot_svds ¶

available_mot_svds(
    animal: str,
    date: str,
    session: int,
    camera_names: tuple[str, ...] | None = None,
) -> dict[str, Path]

Return available motion-SVD files for one session.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.
camera_names ¶
(tuple[str, ...], default: None ) –

Camera names to search, in priority order. If None, uses self.camera_names.

Returns:

dict[str, Path] –

Mapping from camera name to existing motSVD path.

fus_mat ¶

fus_mat(animal: str, date: str, session: int) -> Path

Return the expected path to the raw _fus.mat file.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.

Returns:

Path –

Expected _fus.mat path for the session.

fusi_npz ¶

fusi_npz(animal: str, date: str, session: int) -> Path

Return the expected path to the preprocessed fUSI archive.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.

Returns:

Path –

Expected preprocessed fUSI archive path for the session.

mot_svd_for_camera ¶

mot_svd_for_camera(
    animal: str, date: str, session: int, camera_name: str
) -> Path

Return the expected motion-SVD NPZ path for one camera and session.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.
camera_name ¶
(str) –

Camera name used in the motSVD filename.

Returns:

Path –

Expected motSVD archive path for the session.

reference_scan ¶

reference_scan(animal: str) -> Path

Return the latest angiography reference scan for an animal.

Parameters:

animal ¶
(str) –

Animal identifier.

Returns:

Path –

Path to the latest matching reference scan archive.

rotary_encoder ¶

rotary_encoder(
    animal: str, date: str, session: int
) -> Path

Return the expected path to the rotary encoder recording.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.

Returns:

Path –

Expected rotary encoder path for the session.

timeline_mat ¶

timeline_mat(animal: str, date: str, session: int) -> Path

Return the expected path to the raw Timeline.mat file.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.

Returns:

Path –

Expected Timeline.mat path for the session.

SequenceMetadata ¶

Metadata extracted from a _fus.mat file plus computed values.

Parameters:

autc_meta ¶
(AUTCMetadata) –

Raw metadata from load_autc_metadata.
spatial ¶
(SpatialInfo) –

Computed spatial information, including voxel dimensions.
tr ¶
(float) –

Repetition time in seconds.
probe_voltage ¶
(float) –

Probe HV voltage in volts.
n_iq_frames_per_hardware_block ¶
(int) –

Number of IQ frames per hardware block.
svd_hp_threshold ¶
(float) –

SVD high-pass filter threshold.
low_rank_kernel ¶
(float) –

Low-rank kernel filter parameter.
iq_blocks_per_doppler_frame ¶
(int) –

Number of IQ blocks integrated into one Doppler frame.
doppler_frames_per_clutter_window ¶
(int) –

Number of Doppler frames used by the clutter filter.

Attributes:

autc_meta (AUTCMetadata) –

Raw metadata from load_autc_metadata.
spatial (SpatialInfo) –

Computed spatial information (voxel dimensions).
probe_voltage (float) –

Probe HV voltage in volts.
n_iq_frames_per_hardware_block (int) –

Number of IQ frames per hardware block.
svd_hp_threshold (float) –

SVD high-pass filter threshold.
low_rank_kernel (float) –

Low-rank kernel filter parameter.
tr (float) –

Repetition time in seconds (median inter-block interval).
power_doppler_integration_duration (float) –

Duration of one power Doppler frame.
clutter_filter_window_duration (float) –

Duration of the SVD clutter filter window.

SpatialInfo `dataclass` ¶

Spatial information computed from AUTCMetadata.

VoxelDimensions `dataclass` ¶

Voxel dimensions in millimeters.

build_functional_sidecar ¶

build_functional_sidecar(
    meta: SequenceMetadata,
    animal: str,
    date: str,
    session: int,
    task: Optional[TaskConfig] = None,
    hardware: Optional[HardwareConfig] = None,
) -> dict[str, Any]

Build the complete BIDS sidecar JSON for a functional fUSI scan.

Parameters:

meta ¶
(SequenceMetadata) –

Sequence metadata loaded from the _fus.mat file.
animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.
task ¶
(TaskConfig, default: None ) –

Task configuration. Uses defaults if not provided.
hardware ¶
(HardwareConfig, default: None ) –

Hardware configuration. Uses defaults if not provided.

Returns:

dict –

Complete sidecar JSON content for the functional scan.

build_scans_tsv ¶

build_scans_tsv(
    functional_df: DataFrame,
    angio_df: DataFrame,
    animal: str,
) -> DataFrame

Build a *_scans.tsv DataFrame for a single subject.

Parameters:

functional_df ¶
(DataFrame) –

Table describing functional BIDS outputs.
angio_df ¶
(DataFrame) –

Table describing angiography BIDS outputs.
animal ¶
(str) –

Animal identifier used to filter both tables.

Returns:

DataFrame –

Rows for the subject's *_scans.tsv file.

build_sequence_sidecar ¶

build_sequence_sidecar(
    meta: SequenceMetadata,
    hardware: Optional[HardwareConfig] = None,
) -> dict[str, Any]

Build the sequence-parameter portion of a BIDS fUSI sidecar JSON.

Parameters:

meta ¶
(SequenceMetadata) –

Sequence metadata loaded from the _fus.mat file.
hardware ¶
(HardwareConfig, default: None ) –

Hardware configuration. Uses defaults if not provided.

Returns:

dict –

Sidecar fields describing the acquisition hardware and sequence.

convert_physio_session ¶

convert_physio_session(
    animal: str,
    date: str,
    session: int,
    bids_stem: str,
    bids_root: Path,
    console: Optional[Any] = None,
) -> None

Convert physiology data for one recording session to BIDS physio files.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.
bids_stem ¶
(str) –

BIDS filename stem shared with the functional scan.
bids_root ¶
(Path) –

Root of the output BIDS dataset.
console ¶
(Any, default: None ) –

Rich console for logging. If None, logging is disabled.

find_bids_paths ¶

find_bids_paths(
    animal: str,
    bids_root: Path,
    date: Optional[str] = None,
    experiment_id: Optional[int] = None,
) -> list[Path]

Return absolute BIDS paths for a subject, optionally filtered.

Parameters:

animal ¶
(str) –

Animal identifier.
bids_root ¶
(Path) –

Root of the BIDS dataset.
date ¶
(str, default: None ) –

Restrict matches to acquisitions whose acq_time starts with this date.
experiment_id ¶
(int, default: None ) –

Restrict matches to a single experiment identifier.

Returns:

list[Path] –

Absolute paths listed in the subject scans table after filtering.

find_fus_mat ¶

find_fus_mat(animal: str, date: str, session: int) -> Path

Return the path to the _fus.mat file for a recording session.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.

Returns:

Path –

Path to the matching _fus.mat file.

find_mot_svd_files ¶

find_mot_svd_files(
    animal: str,
    date: str,
    session: int,
    camera_names: tuple[str, ...] | None = None,
) -> dict[str, Path]

Return available Facemap motSVD NPZ files for a recording session.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.
camera_names ¶
(tuple[str, ...], default: None ) –

Camera names to search, in priority order. If None, uses resolver defaults.

Returns:

dict[str, Path] –

Mapping from camera name to existing motSVD path.

Raises:

FileNotFoundError –

If no motSVD files are found for the requested session.

find_rotary_encoder ¶

find_rotary_encoder(
    animal: str, date: str, session: int
) -> Path

Return the path to the rotary encoder file for a recording session.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.

Returns:

Path –

Path to the matching rotary encoder file.

find_timeline_mat ¶

find_timeline_mat(
    animal: str, date: str, session: int
) -> Path

Return the path to the Timeline.mat file for a recording session.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.

Returns:

Path –

Path to the matching Timeline.mat file.

get_data_path_resolver ¶

get_data_path_resolver() -> DataPathResolver

Get the current data path resolver.

Returns:

DataPathResolver –

The configured global data path resolver.

load_angio_as_nifti ¶

load_angio_as_nifti(animal: str) -> Nifti1Image

Load the latest reference (angiography) scan and return as a NIfTI image.

Uses voxel dimensions from the first available functional scan of the animal.

Parameters:

animal ¶
(str) –

Animal identifier.

Returns:

Nifti1Image –

Angiography volume with an affine built from the best available voxel sizes.

load_fusi_as_nifti ¶

load_fusi_as_nifti(
    animal: str, date: str, session: int
) -> Nifti1Image

Load a preprocessed fUSI file and return a NIfTI image.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.

Returns:

Nifti1Image –

4D NIfTI image with correct affine and header.

load_sequence_metadata ¶

load_sequence_metadata(
    animal: str, date: str, session: int
) -> SequenceMetadata

Load sequence acquisition metadata from the _fus.mat HDF5 file.

Computes TR from block times and voxel dimensions from AUTCMetadata.

Parameters:

animal ¶
(str) –

Animal identifier.
date ¶
(str) –

Recording date in YYYY-MM-DD format.
session ¶
(int) –

Session number.

Returns:

SequenceMetadata –

Metadata extracted from the raw sequence file and derived timing values.

save_physio_bids ¶

save_physio_bids(
    data: ndarray,
    timestamps: ndarray,
    columns: list[str],
    output_path: Path,
    column_metadata: Optional[dict[str, dict]] = None,
) -> None

Save physiological data to BIDS format (TSV.gz + JSON sidecar).

Parameters:

data ¶
(ndarray) –

One- or two-dimensional array containing the physiological signals.
timestamps ¶
(ndarray) –

Sample timestamps in seconds.
columns ¶
(list of str) –

Column names for the physiological signals stored in data.
output_path ¶
(Path) –

Output stem used to derive the .tsv.gz and .json files.
column_metadata ¶
(dict of str to dict, default: None ) –

Per-column metadata to merge into the JSON sidecar.

set_data_path_resolver ¶

set_data_path_resolver(resolver: DataPathResolver) -> None

Set the global data path resolver.

Parameters:

resolver ¶
(DataPathResolver) –

Resolver used by BIDS helpers to locate source data files.

cortexlab_fusi_utils.bids¶

bids ¶

DataPathResolver ¶

animal_data_path_func ¶

iq_blocks_per_doppler_frame ¶

doppler_frames_per_clutter_window ¶

camera_names ¶

fusi_filename_pattern ¶

fus_filename_pattern ¶

timeline_filename_pattern ¶

camera_names property ¶

animal_root ¶

animal ¶

available_mot_svds ¶

animal ¶

date ¶

session ¶

camera_names ¶

fus_mat ¶

animal ¶

date ¶

session ¶

fusi_npz ¶

animal ¶

date ¶

session ¶

mot_svd_for_camera ¶

animal ¶

date ¶

session ¶

camera_name ¶

reference_scan ¶

animal ¶

rotary_encoder ¶

animal ¶

date ¶

session ¶

timeline_mat ¶

animal ¶

date ¶

session ¶

SequenceMetadata ¶

autc_meta ¶

spatial ¶

tr ¶

probe_voltage ¶

n_iq_frames_per_hardware_block ¶

svd_hp_threshold ¶

low_rank_kernel ¶

iq_blocks_per_doppler_frame ¶

doppler_frames_per_clutter_window ¶

SpatialInfo dataclass ¶

VoxelDimensions dataclass ¶

build_functional_sidecar ¶

meta ¶

animal ¶

date ¶

session ¶

task ¶

hardware ¶

build_scans_tsv ¶

functional_df ¶

angio_df ¶

animal ¶

build_sequence_sidecar ¶

meta ¶

hardware ¶

convert_physio_session ¶

animal ¶

date ¶

session ¶

bids_stem ¶

bids_root ¶

console ¶

find_bids_paths ¶

animal ¶

bids_root ¶

date ¶

experiment_id ¶

find_fus_mat ¶

`cortexlab_fusi_utils.bids`¶

`animal_data_path_func` ¶

`iq_blocks_per_doppler_frame` ¶

`doppler_frames_per_clutter_window` ¶

`camera_names` ¶

`fusi_filename_pattern` ¶

`fus_filename_pattern` ¶

`timeline_filename_pattern` ¶

camera_names `property` ¶

`animal` ¶

`animal` ¶

`date` ¶

`session` ¶

`camera_names` ¶

`animal` ¶

`date` ¶

`session` ¶

`animal` ¶

`date` ¶

`session` ¶

`animal` ¶

`date` ¶

`session` ¶

`camera_name` ¶

`animal` ¶

`animal` ¶

`date` ¶

`session` ¶

`animal` ¶

`date` ¶

`session` ¶

`autc_meta` ¶

`spatial` ¶

`tr` ¶

`probe_voltage` ¶

`n_iq_frames_per_hardware_block` ¶

`svd_hp_threshold` ¶

`low_rank_kernel` ¶

`iq_blocks_per_doppler_frame` ¶

`doppler_frames_per_clutter_window` ¶

SpatialInfo `dataclass` ¶

VoxelDimensions `dataclass` ¶

`meta` ¶

`animal` ¶

`date` ¶

`session` ¶

`task` ¶

`hardware` ¶

`functional_df` ¶

`angio_df` ¶

`animal` ¶

`meta` ¶

`hardware` ¶

`animal` ¶

`date` ¶

`session` ¶

`bids_stem` ¶

`bids_root` ¶

`console` ¶

`animal` ¶

`bids_root` ¶

`date` ¶

`experiment_id` ¶

`animal` ¶

`date` ¶

`session` ¶

`animal` ¶

`date` ¶

`session` ¶

`camera_names` ¶

`animal` ¶

`date` ¶

`session` ¶

`animal` ¶

`date` ¶

`session` ¶

`animal` ¶

`animal` ¶

`date` ¶

`session` ¶