Base ImagingExtractors#

ImagingExtractor#

Base class definitions for all ImagingExtractors.

Classes#

ImagingExtractor

Abstract class that contains all the meta-data and input data from the imaging data.

class ImagingExtractor(*args, **kwargs)[source]#

Bases: ABC

Abstract class that contains all the meta-data and input data from the imaging data.

Initialize the ImagingExtractor object.

abstract get_image_shape() → tuple[int, int][source]#

Get the shape of the video frame (num_rows, num_columns).

Returns:

image_shape – Shape of the video frame (num_rows, num_columns).

Return type:

tuple

get_frame_shape() → tuple[int, int][source]#

Get the shape of the video frame (num_rows, num_columns).

Returns:

frame_shape – Shape of the video frame (num_rows, num_columns).

Return type:

tuple

Notes

This method is equivalent to get_image_shape()

get_sample_shape() → tuple[int, int] | tuple[int, int, int][source]#

Get the shape of a single sample elements from the series.

If the series is volumetric, the shape is the shape of the volume and otherwise returns the shape of a single frame/image.

Returns:

sample_shape – Shape of a single sample from the time series (num_rows, num_columns, num_planes) if volumetric (num_rows, num_columns) otherwise

Return type:

tuple

get_num_planes() → int[source]#

Get the number of depth planes.

Returns:

num_planes – The number of depth planes.

Return type:

int

Raises:

NotImplementedError – If the extractor is not volumetric.

get_volume_shape() → tuple[int, int, int][source]#

Get the shape of the volumetric video (num_rows, num_columns, num_planes).

Returns:

video_shape – Shape of the volumetric video (num_rows, num_columns, num_planes).

Return type:

tuple

Raises:

NotImplementedError – If the extractor is not volumetric or does not implement get_num_planes method.

abstract get_num_samples() → int[source]#

Get the number of samples in the video.

Returns:

num_samples – Number of samples in the video.

Return type:

int

abstract get_sampling_frequency() → float[source]#

Get the sampling frequency in Hz.

Returns:

sampling_frequency – Sampling frequency in Hz.

Return type:

float

get_channel_names() → list[source]#

Get the channel names in the recoding.

Returns:

channel_names – List of strings of channel names

Return type:

list

get_dtype() → dtype[Any] | None | type[Any] | _SupportsDType[dtype[Any]] | str | tuple[Any, int] | tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | list[Any] | _DTypeDict | tuple[Any, Any][source]#

Get the data type of the video.

Returns:

dtype – Data type of the video.

Return type:

dtype

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

Get the series of samples.

Parameters:

  • start_sample (int, optional) – Start sample index (inclusive).

  • end_sample (int, optional) – End sample index (exclusive).

Returns:

series – The series of samples.

Return type:

numpy.ndarray

Notes

Importantly, we follow the convention that the dimensions of the array are returned in their matrix order, More specifically: (time, height, width)

Which is equivalent to: (samples, rows, columns)

For volumetric data, the dimensions are: (time, height, width, planes)

Which is equivalent to: (samples, rows, columns, planes)

Note that this does not match the cartesian convention: (t, x, y)

Where x is the columns width or and y is the rows or height.

get_samples(sample_indices: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → ndarray[source]#

Get specific samples from indices (not necessarily continuous).

Parameters:

sample_indices (array-like) – Indices of samples to return.

Returns:

samples – The samples.

Return type:

numpy.ndarray

abstract 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

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

Retrieve the timestamps for the data in this extractor.

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.

Return type:

numpy.ndarray

time_to_sample_indices(times: float | _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → float | ndarray[source]#

Convert user-inputted times (in seconds) to sample indices.

Parameters:

times (float or array-like) – The times (in seconds) to be converted to sample indices.

Returns:

sample_indices – The corresponding sample indices.

Return type:

float or array-like

set_times(times: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → None[source]#

Set the recording times (in seconds) for each frame.

Parameters:

times (array-like) – The times in seconds for each frame.

Raises:

ValueError – If the length of ‘times’ does not match the number of samples.

has_time_vector() → bool[source]#

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

Returns:

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

Return type:

bool

copy_times(extractor) → None[source]#

Copy times from another extractor.

Parameters:

extractor – The extractor from which the times will be copied.

slice_samples(start_sample: int | None = None, end_sample: int | None = None)[source]#

Return a new ImagingExtractor ranging from the start_sample to the end_sample.

Parameters:

  • start_sample (int, optional) – Start sample index (inclusive).

  • end_sample (int, optional) – End sample index (exclusive).

Returns:

imaging – The sliced ImagingExtractor object.

Return type:

SampleSlicedImagingExtractor

slice_field_of_view(row_start: int | None = None, row_end: int | None = None, column_start: int | None = None, column_end: int | None = None)[source]#

Return a new ImagingExtractor with a spatially sliced field of view.

Parameters:

  • row_start (int, optional) – Starting row index (inclusive). Default is 0.

  • row_end (int, optional) – Ending row index (exclusive). Default is the full height.

  • column_start (int, optional) – Starting column index (inclusive). Default is 0.

  • column_end (int, optional) – Ending column index (exclusive). Default is the full width.

Returns:

imaging – The spatially sliced ImagingExtractor object.

Return type:

FieldOfViewSlicedImagingExtractor

Notes

This method creates a lazy view of the imaging data with a cropped field of view. The slicing is applied to the spatial dimensions (rows and columns) of each frame. For volumetric data, all depth planes are preserved with the same spatial crop applied.

Examples

>>> # Crop to center 100x100 region starting at (50, 50)
>>> cropped_extractor = extractor.slice_field_of_view(row_start=50, row_end=150,
...                                                    column_start=50, column_end=150)
>>>
>>> # Get top-left quadrant
>>> height, width = extractor.get_image_shape()
>>> quadrant = extractor.slice_field_of_view(row_end=height//2, column_end=width//2)
>>>
>>> # Compose with temporal slicing
>>> subset = extractor.slice_samples(0, 1000).slice_field_of_view(100, 200, 100, 200)
class SampleSlicedImagingExtractor(parent_imaging: ImagingExtractor, start_sample: int | None = None, end_sample: int | None = None)[source]#

Bases: ImagingExtractor

Class to get a lazy sample slice.

Do not use this class directly but use .slice_samples(…) on an ImagingExtractor object.

Initialize an ImagingExtractor whose samples subset the parent.

Subset is exclusive on the right bound, that is, the indexes of this ImagingExtractor range over [0, …, end_sample-start_sample-1], which is used to resolve the index mapping in get_samples(sample_indices=[…]).

Parameters:

  • parent_imaging (ImagingExtractor) – The ImagingExtractor object to subset the samples of.

  • start_sample (int, optional) – The left bound of the samples to subset. The default is the start sample of the parent.

  • end_sample (int, optional) – The right bound of the samples, exclusively, to subset. The default is end sample of the parent.

get_samples(sample_indices: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]) → ndarray[source]#

Get specific samples from indices (not necessarily continuous).

Parameters:

sample_indices (array-like) – Indices of samples to return.

Returns:

samples – The samples.

Return type:

numpy.ndarray

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

Get the series of samples.

Parameters:

  • start_sample (int, optional) – Start sample index (inclusive).

  • end_sample (int, optional) – End sample index (exclusive).

Returns:

series – The series of samples.

Return type:

numpy.ndarray

Notes

Importantly, we follow the convention that the dimensions of the array are returned in their matrix order, More specifically: (time, height, width)

Which is equivalent to: (samples, rows, columns)

For volumetric data, the dimensions are: (time, height, width, planes)

Which is equivalent to: (samples, rows, columns, planes)

Note that this does not match the cartesian convention: (t, x, y)

Where x is the columns width or and y is the rows or height.

get_image_shape() → tuple[int, int][source]#

Get the shape of the video frame (num_rows, num_columns).

Returns:

image_shape – Shape of the video frame (num_rows, num_columns).

Return type:

tuple

get_num_samples() → int[source]#

Get the number of samples in the video.

Returns:

num_samples – Number of samples in the video.

Return type:

int

get_sampling_frequency() → float[source]#

Get the sampling frequency in Hz.

Returns:

sampling_frequency – Sampling frequency in Hz.

Return type:

float

get_channel_names() → list[source]#

Get the channel names in the recoding.

Returns:

channel_names – List of strings of channel names

Return type:

list

get_num_planes() → int[source]#

Get the number of depth planes.

Returns:

num_planes – The number of depth planes.

Return type:

int

Raises:

NotImplementedError – If the parent extractor is not volumetric.

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.

Returns:

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

Return type:

bool

MultiImagingExtractor#

Defines the MultiImagingExtractor class.

Classes#

MultiImagingExtractor

This class is used to combine multiple ImagingExtractor objects by frames.

class MultiImagingExtractor(imaging_extractors: list[ImagingExtractor])[source]#

Bases: ImagingExtractor

Class to combine multiple ImagingExtractor objects by frames.

Initialize a MultiImagingExtractor object from a list of ImagingExtractors.

Parameters:

imaging_extractors (list of ImagingExtractor) – list of imaging extractor objects

get_dtype()[source]#

Get the data type of the video.

Returns:

dtype – Data type of the video.

Return type:

dtype

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

Get the video frames.

Parameters:

  • start_sample (int, optional) – Start sample index (inclusive).

  • end_sample (int, optional) – End sample index (exclusive).

Returns:

series – The video frames.

Return type:

numpy.ndarray

get_image_shape() → tuple[int, int][source]#

Get the shape of the video frame (num_rows, num_columns).

Returns:

image_shape – Shape of the video frame (num_rows, num_columns).

Return type:

tuple

get_num_samples() → int[source]#

Get the number of samples in the video.

Returns:

num_samples – Number of samples in the video.

Return type:

int

get_sampling_frequency() → float[source]#

Get the sampling frequency in Hz.

Returns:

sampling_frequency – Sampling frequency in Hz.

Return type:

float

get_channel_names() → list[source]#

Get the channel names in the recoding.

Returns:

channel_names – List of strings of channel names

Return type:

list

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

VolumetricImagingExtractor#

Base class definition for volumetric imaging extractors.

class VolumetricImagingExtractor(imaging_extractors: list[ImagingExtractor])[source]#

Bases: ImagingExtractor

Class to combine multiple ImagingExtractor objects by depth plane.

Initialize a VolumetricImagingExtractor object from a list of ImagingExtractors.

Parameters:

imaging_extractors (list of ImagingExtractor) – list of imaging extractor objects

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

Get the series of samples.

Parameters:

  • start_sample (int, optional) – Start sample index (inclusive).

  • end_sample (int, optional) – End sample index (exclusive).

Returns:

series – The series of samples.

Return type:

numpy.ndarray

Notes

Importantly, we follow the convention that the dimensions of the array are returned in their matrix order, More specifically: (time, height, width)

Which is equivalent to: (samples, rows, columns)

For volumetric data, the dimensions are: (time, height, width, planes)

Which is equivalent to: (samples, rows, columns, planes)

Note that this does not match the cartesian convention: (t, x, y)

Where x is the columns width or and y is the rows or height.

get_image_shape() → tuple[int, int][source]#

Get the shape of the video frame (num_rows, num_columns).

Returns:

image_shape – Shape of the video frame (num_rows, num_columns).

Return type:

tuple

get_num_planes() → int[source]#

Get the number of depth planes.

Returns:

_num_planes – The number of depth planes.

Return type:

int

get_num_samples() → int[source]#

Get the number of samples in the video.

Returns:

num_samples – Number of samples in the video.

Return type:

int

get_sampling_frequency() → float[source]#

Get the sampling frequency in Hz.

Returns:

sampling_frequency – Sampling frequency in Hz.

Return type:

float

get_channel_names() → list[source]#

Get the channel names in the recoding.

Returns:

channel_names – List of strings of channel names

Return type:

list

get_dtype() → dtype[Any] | None | type[Any] | _SupportsDType[dtype[Any]] | str | tuple[Any, int] | tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | list[Any] | _DTypeDict | tuple[Any, Any][source]#

Get the data type of the video.

Returns:

dtype – Data type of the video.

Return type:

dtype

get_volume_shape() → tuple[int, int, int][source]#

Get the shape of the volumetric video (num_rows, num_columns, num_planes).

Returns:

video_shape – Shape of the volumetric video (num_rows, num_columns, num_planes).

Return type:

tuple

depth_slice(start_plane: int | None = None, end_plane: int | None = None)[source]#

Return a new VolumetricImagingExtractor ranging from the start_plane to the end_plane.

slice_samples(start_sample: int | None = None, end_sample: int | None = None)[source]#

Return a new VolumetricImagingExtractor with a subset of samples.

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

class DepthSliceVolumetricImagingExtractor(parent_extractor: VolumetricImagingExtractor, start_plane: int | None = None, end_plane: int | None = None)[source]#

Bases: VolumetricImagingExtractor

Class to get a lazy depth slice.

This class can only be used for volumetric imaging data. Do not use this class directly but use .depth_slice(…) on a VolumetricImagingExtractor object.

Initialize a VolumetricImagingExtractor whose plane(s) subset the parent.

Subset is exclusive on the right bound, that is, the plane indices of this VolumetricImagingExtractor range over [0, …, end_plane-start_plane-1].

Parameters:

  • parent_extractor (VolumetricImagingExtractor) – The VolumetricImagingExtractor object to subset the planes of.

  • start_plane (int, optional) – The left bound of the depth to subset. The default is the first plane of the parent.

  • end_plane (int, optional) – The right bound of the depth, exclusively, to subset. The default is the last plane of the parent.

On this page

This Page