Extraction Tools#

Various tools for extraction of ROIs from imaging data.

Classes#

VideoStructure

A data class for specifying the structure of a video.

calculate_regular_series_rate(series: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], tolerance_decimals: int = 6) → float | None[source]#

Calculate the rate of a regular series from consecutive differences.

If all differences between consecutive points are the same (within rounding tolerance), returns the rate as 1.0 / interval. Otherwise returns None.

Parameters:

  • series (array-like) – Array of timestamps or time points.

  • tolerance_decimals (int, default: 6) – Number of decimal places for rounding when checking uniformity.

Returns:

The calculated rate if the series is regular, None otherwise.

Return type:

float | None

raise_multi_channel_or_depth_not_implemented(extractor_name: str)[source]#

Raise a NotImplementedError for an extractor that does not support multiple channels or depth (z-axis).

class VideoStructure(num_rows: int, num_columns: int, num_channels: int, rows_axis: int, columns_axis: int, channels_axis: int, frame_axis: int)[source]#

Bases: object

A data class for specifying the structure of a video.

The role of the data class is to ensure consistency in naming and provide some initial consistency checks to ensure the validity of the structure.

Variables:

  • num_rows (int) – The number of rows of each frame as a matrix.

  • num_columns (int) – The number of columns of each frame as a matrix.

  • num_channels (int) – The number of channels (1 for grayscale, 3 for color).

  • rows_axis (int) – The axis or dimension corresponding to the rows.

  • columns_axis (int) – The axis or dimension corresponding to the columns.

  • channels_axis (int) – The axis or dimension corresponding to the channels.

  • frame_axis (int) – The axis or dimension corresponding to the frames in the video.

  • 5 (>>> num_columns =)

  • you (where the video is to have the following shape (num_frames, num_rows, num_columns, num_channels))

  • way (could define the class this)

  • VideoStructure (>>> from roiextractors.extraction_tools import)

  • 10 (>>> num_rows =)

  • 5

  • 1 (>>> rows_axis =)

  • 0 (>>> frame_axis =)

  • 1

  • 2 (>>> columns_axis =)

  • 3 (>>> channels_axis =)

  • VideoStructure( (>>> video_structure =) – num_rows=num_rows, num_columns=num_columns, num_channels=num_channels, rows_axis=rows_axis, columns_axis=columns_axis, channels_axis=channels_axis, frame_axis=frame_axis,

  • )

__post_init__() → None[source]#

Validate the structure of the video and initialize the shape of the frame.

build_video_shape(n_frames: int) → tuple[int, int, int, int][source]#

Build the shape of the video from class attributes.

Parameters:

n_frames (int) – The number of frames in the video.

Returns:

The shape of the video.

Return type:

Tuple[int, int, int, int]

Notes

The class attributes frame_axis, rows_axis, columns_axis and channels_axis are used to determine the order of the dimensions in the returned tuple.

transform_video_to_canonical_form(video: ndarray) → ndarray[source]#

Transform a video to the canonical internal format of roiextractors (num_frames, num_rows, num_columns, num_channels).

Parameters:

video (numpy.ndarray) – The video to be transformed

Returns:

The reshaped video

Return type:

numpy.ndarray

Raises:

KeyError – If the video is not in a format that can be transformed.

read_numpy_memmap_video(file_path: str | Path, video_structure: VideoStructure, dtype: dtype[Any] | None | type[Any] | _SupportsDType[dtype[Any]] | str | tuple[Any, int] | tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | list[Any] | _DTypeDict | tuple[Any, Any], offset: int = 0) → array[source]#

Auxiliary function to read videos from binary files.

Parameters:

  • file_path (PathType) – the file_path where the data resides.

  • video_structure (VideoStructure) – A VideoStructure instance describing the structure of the video to read. This includes parameters such as the number of rows, columns and channels plus which axis (i.e. dimension) of the image corresponds to each of them.

    As an example you create one of these structures in the following way:

    from roiextractors.extraction_tools import VideoStructure

    num_rows = 10 num_columns = 5 num_channels = 3 frame_axis = 0 rows_axis = 1 columns_axis = 2 channels_axis = 3

    video_structure = VideoStructure(

    num_rows=num_rows, num_columns=num_columns, num_channels=num_channels, rows_axis=rows_axis, columns_axis=columns_axis, channels_axis=channels_axis, frame_axis=frame_axis,

    )

  • dtype (DtypeType) – The type of the data to be loaded (int, float, etc.)

  • offset (int, optional) – The offset in bytes. Usually corresponds to the number of bytes occupied by the header. 0 by default.

Returns:

video_memap – A numpy memmap pointing to the video.

Return type:

np.array

check_get_frames_args(func)[source]#

Check the arguments of the get_frames function.

This decorator allows the get_frames function to be queried with either an integer, slice or an array and handles a common return. [I think that np.take can be used instead of this]

Parameters:

func (function) – The get_frames function.

Returns:

corrected_args – The get_frames function with corrected arguments.

Return type:

function

Raises:

  • AssertionError – If ‘frame_idxs’ exceed the number of frames.

  • Deprecated –

  • ---------- –

  • This function will be removed on or after June 2026. –

  • The get_frames method it decorates has been removed. –

check_get_videos_args(func)[source]#

Check the arguments of the get_videos function.

This decorator allows the get_videos function to be queried with either an integer or slice and handles a common return.

Parameters:

func (function) – The get_videos function.

Returns:

corrected_args – The get_videos function with corrected arguments.

Return type:

function

Raises:

  • AssertionError – If ‘start_frame’ exceeds the number of frames.

  • AssertionError – If ‘end_frame’ exceeds the number of frames.

  • AssertionError – If ‘start_frame’ is greater than ‘end_frame’.

  • Deprecated –

  • ---------- –

  • This function will be removed on or after January 2026. –

  • The get_video method it decorates has been removed. –

write_to_h5_dataset_format(imaging, dataset_path, save_path=None, file_handle=None, dtype=None, chunk_size=None, chunk_mb=1000, verbose=False)[source]#

Save the video of an imaging extractor in an h5 dataset.

Parameters:

  • imaging (ImagingExtractor) – The imaging extractor object to be saved in the .h5 file

  • dataset_path (str) – Path to dataset in h5 file (e.g. ‘/dataset’)

  • save_path (str) – The path to the file.

  • file_handle (file handle) – The file handle to dump data. This can be used to append data to an header. In case file_handle is given, the file is NOT closed after writing the binary data.

  • dtype (dtype) – Type of the saved data. Default float32.

  • chunk_size (None or int) – Number of chunks to save the file in. This avoid to much memory consumption for big files. If None and ‘chunk_mb’ is given, the file is saved in chunks of ‘chunk_mb’ Mb (default 500Mb)

  • chunk_mb (None or int) – Chunk size in Mb (default 1000Mb)

  • verbose (bool) – If True, output is verbose (when chunks are used)

Returns:

save_path – The path to the file.

Return type:

str

Raises:

AssertionError – If neither ‘save_path’ nor ‘file_handle’ are given.

show_video(imaging, ax=None)[source]#

Show video as animation.

Parameters:

  • imaging (ImagingExtractor) – The imaging extractor object to be saved in the .h5 file

  • ax (matplotlib axis) – Axis to plot the video. If None, a new axis is created.

Returns:

anim – Animation of the video.

Return type:

matplotlib.animation.FuncAnimation

check_keys(dict_: dict) → dict[source]#

Check keys of dictionary for mat-objects.

Checks if entries in dictionary are mat-objects. If yes todict is called to change them to nested dictionaries.

Parameters:

dict_ (dict) – Dictionary to check.

Returns:

dict – Dictionary with mat-objects converted to nested dictionaries.

Return type:

dict

Raises:

AssertionError – If scipy is not installed.

todict(matobj)[source]#

Recursively construct nested dictionaries from matobjects.

Parameters:

matobj (mat_struct) – Matlab object to convert to nested dictionary.

Returns:

dict – Dictionary with mat-objects converted to nested dictionaries.

Return type:

dict

get_package(package_name: str, installation_instructions: str | None = None, excluded_platforms_and_python_versions: dict[str, list[str]] | None = None) → ModuleType[source]#

Check if package is installed and return module if so.

Otherwise, raise informative error describing how to perform the installation. Inspired by https://docs.python.org/3/library/importlib.html#checking-if-a-module-can-be-imported.

Parameters:

  • package_name (str) – Name of the package to be imported.

  • installation_instructions (str, optional) – String describing the source, options, and alias of package name (if needed) for installation. For example,

    >>> installation_source = "conda install -c conda-forge my-package-name"

    Defaults to f”pip install {package_name}”.

  • excluded_platforms_and_python_versions (dict mapping string platform names to a list of string versions, optional) – In case some combinations of platforms or Python versions are not allowed for the given package, specify this dictionary to raise a more specific error to that issue. For example, excluded_platforms_and_python_versions = dict(darwin=[“3.7”]) will raise an informative error when running on MacOS with Python version 3.7. Allows all platforms and Python versions used by default.

Raises:

ModuleNotFoundError – If the package is not installed.