MiniscopeImagingExtractor#

class MiniscopeImagingExtractor(folder_path: str | Path | None = None, file_paths: list[str | Path] | None = None, configuration_file_path: str | Path | None = None, timestamps_path: str | Path | None = None, *, sampling_frequency: float | None = None)[source]#

Bases: MultiImagingExtractor

Extractor for Miniscope calcium imaging data recorded with Miniscope-DAQ-QT-Software.

This extractor consolidates multiple .avi video files from a Miniscope recording session into a single continuous dataset. It uses hardware-generated timestamps from timeStamps.csv for accurate timing information.

The extractor works at the device folder level, where a typical Miniscope recording has the following structure:

device_folder/ (e.g., “Miniscope”, “HPC_miniscope1”, “ACC_miniscope2”) ├── 0.avi, 1.avi, 2.avi, … # Video files (FFV1 lossless codec) ├── timeStamps.csv # Hardware-generated timestamps (required) ├── metaData.json # Device configuration (optional, for reference) └── headOrientation.csv # IMU data (optional)

Key Features#

  • Automatically discovers and concatenates multiple .avi files from a recording

  • Calculates sampling frequency from hardware timestamps (timeStamps.csv)

  • Supports both folder-based and file-list initialization

  • Provides access to device and session metadata via static methods

See also

MiniscopeMultiRecordingImagingExtractor

For multi-session recordings (Tye Lab format)

Initialize MiniscopeImagingExtractor.

Parameters:

  • folder_path (PathType | None, optional) – Path to the device folder containing the Miniscope recording files (.avi videos, metaData.json, and timeStamps.csv). This is the recommended way to initialize the extractor as it automatically discovers all necessary files.

    Note: This is the device-level folder (e.g., “HPC_miniscope1”), not the session folder (which may contain multiple device folders).

  • file_paths (list[PathType] | None, optional) – List of .avi file paths to be processed. These files should be from the same recording session and will be concatenated in the order provided.

  • configuration_file_path (PathType | None, optional) – DEPRECATED: This parameter is deprecated and will be removed in March 2026. This parameter is no longer used and is ignored.

    The device folder is now automatically inferred from file_paths. If provided, this parameter only triggers validation (checking if the file exists and is valid JSON), but has no functional effect on the extractor’s behavior.

    Migration: Simply remove this parameter from your code. For example:

    # Old (deprecated): extractor = MiniscopeImagingExtractor(file_paths=files, configuration_file_path=config) # New (recommended): extractor = MiniscopeImagingExtractor(file_paths=files)

    If you need to read metaData.json files, use the private static methods: - MiniscopeImagingExtractor._read_device_folder_metadata(file_path) - MiniscopeImagingExtractor._read_session_folder_metadata(file_path)

    Deprecation rationale: - The metaData.json frameRate field is user-settable, not measured. The DAQ system

    attempts to achieve this rate but cannot guarantee it due to hardware limitations.

    • Analysis shows sampling frequency calculated from timeStamps.csv often differs from the configured frameRate, making metaData.json unreliable for timing information.

    • timeStamps.csv provides ground truth timing (hardware-generated, always produced by DAQ)

    • Requiring both file_paths and configuration_file_path is redundant when timestamps are available

    Default is None.

  • timestamps_path (PathType | None, optional) – Path to the timeStamps.csv file containing timestamps relative to the recording start. If not provided, the extractor will look for a timeStamps.csv file in the same directory as the video files as a fallback. This file is required for accurate timing. Default is None.

  • sampling_frequency (float | None, optional) – Explicit sampling frequency in Hz. If provided, this overrides the calculated value from timeStamps.csv. Only use this if you have a specific reason to override the measured sampling frequency (e.g., working with incomplete data). Default is None (calculate from timeStamps.csv).

Examples

>>> # Recommended: Folder-based initialization (auto-detects .avi files and timeStamps.csv)
>>> folder_path = "/path/to/miniscope_folder"
>>> extractor = MiniscopeImagingExtractor(folder_path=folder_path)

>>> # Direct file specification (device folder inferred from file_paths)
>>> file_paths = ["/path/to/device_folder/0.avi", "/path/to/device_folder/1.avi"]
>>> extractor = MiniscopeImagingExtractor(file_paths=file_paths)

>>> # With explicit timestamps path
>>> timestamps_path = "/path/to/device_folder/timeStamps.csv"
>>> extractor = MiniscopeImagingExtractor(file_paths=file_paths, timestamps_path=timestamps_path)

>>> # Legacy usage with configuration_file_path (deprecated, triggers warning)
>>> config_path = "/path/to/device_folder/metaData.json"
>>> extractor = MiniscopeImagingExtractor(file_paths=file_paths, configuration_file_path=config_path)

Notes

For each video file, a _MiniscopeSingleVideoExtractor is created. These individual extractors are then combined into the MiniscopeImagingExtractor to handle the session’s recordings as a unified, continuous dataset.

static validate_miniscope_files(file_paths: list[str | Path], timestamps_path: str | Path | None = None) → None[source]#

Validate that the provided Miniscope files exist and are accessible.

Parameters:

  • file_paths (List[PathType]) – List of .avi file paths to validate.

  • timestamps_path (PathType | None) – Path to the timestamps file to validate, by default None.

Raises:

  • FileNotFoundError – If any of the specified files do not exist.

  • ValueError – If the file lists are empty or contain invalid file types.

Notes

Only the .avi files are strictly required. The timestamps file is optional.

static load_miniscope_config(configuration_file_path: str | Path) → dict[source]#

Load and parse the Miniscope configuration file.

This is a generic method that can read any metaData.json file (session or device level). For more explicit metadata reading with specialized documentation, consider using: - _read_session_folder_metadata() for session-level metadata - _read_device_folder_metadata() for device-level metadata

Parameters:

configuration_file_path (PathType) – Path to the metaData.json configuration file.

Returns:

Parsed configuration data from the JSON file.

Return type:

dict

Raises:

  • FileNotFoundError – If the configuration file does not exist.

  • json.JSONDecodeError – If the configuration file is not valid JSON.

get_native_timestamps(start_sample: int | None = None, end_sample: int | None = None) → ndarray | None[source]#

Retrieve the original unaltered timestamps for the data in this interface.

This function should retrieve the data on-demand by re-initializing the IO. Can be overridden to return None if the extractor does not have native timestamps.

Parameters:

  • start_sample (int, optional) – The starting sample index. If None, starts from the beginning.

  • end_sample (int, optional) – The ending sample index. If None, goes to the end.

Returns:

timestamps – The timestamps for the data stream, or None if native timestamps are not available.

Return type:

numpy.ndarray or None

has_time_vector() → bool[source]#

Detect if the ImagingExtractor has a time vector set or not.

Notes

Miniscope recordings should always have native timestamps from timeStamps.csv. This method overrides the parent implementation to ensure timestamps are properly loaded and returned, as Miniscope data is fundamentally time-based with hardware-generated timestamps that provide ground truth timing.

Returns:

has_times – True if the ImagingExtractor has a time vector set, otherwise False.

Return type:

bool