photon_mosaic.core.baseimaging#

Classes

BaseImaging(sampling_frequency, shape, dtype)

Base class for imaging extractors.

BaseImagingEpoch([sampling_frequency, ...])

Abstract class representing a video epoch.

class photon_mosaic.core.baseimaging.BaseImaging(sampling_frequency, shape, dtype, plane_ids=None)[source]#

Base class for imaging extractors.

The class inherits from BaseExtractor and TimeSeries to provide common functionality for imaging data handling.

Each BaseImaging instance is associated to a single “channel”. The _main_ids attribute is used here for multi-plane imaging objects.

Attributes:
epochs

Get the epochs (segments) of the imaging data.

num_planes

Get the number of planes in the imaging data.

plane_ids

Get the plane IDs associated with the imaging data.

sampling_frequency

Get the sampling frequency of the imaging object.

shape

Get the shape of the images (height, width).

Methods

add_epoch(epoch)

Add an epoch (segment) to the imaging data.

get_average_image([num_chunks, ...])

Compute the average image across all frames in the imaging data.

get_binary_description()

When imaging.is_binary_compatible() is True this returns a dictionary describing the binary format.

get_data(start_frame, end_frame[, segment_index])

Internal function to return data for SpikeInterface chunk processing.

get_dtype()

Get the data type of the video.

get_num_epochs()

Get the number of imaging epochs.

get_num_frames([epoch_index])

Get the total number of frames in the imaging data.

get_num_pixels()

Get the number of pixels in the image.

get_num_planes()

Get the number of planes in the imaging data.

get_num_samples([segment_index])

Get the number of samples (frames) in the imaging segment.

get_series([start_frame, end_frame, ...])

Get a series of frames from the imaging data.

get_shape([segment_index])

Get the shape of the imaging data as (num_samples, height, width, planes).

get_total_frames()

Get the total number of frames across all segments.

is_binary_compatible()

Checks if the imaging object is "binary" compatible.

save([format, verbose])

Save a BaseImaging object to a specified format:

get_sample_size_in_bytes

get_sampling_frequency

property shape#

Get the shape of the images (height, width).

Returns:

The shape of the images as (height, width).

Return type:

tuple

property plane_ids#

Get the plane IDs associated with the imaging data.

Returns:

A list of plane IDs.

Return type:

list

property sampling_frequency#

Get the sampling frequency of the imaging object.

Returns:

The sampling frequency in Hz.

Return type:

float

property num_planes#

Get the number of planes in the imaging data.

Returns:

The number of planes.

Return type:

int

property epochs#

Get the epochs (segments) of the imaging data.

Returns:

A list of epochs (segments) in the imaging data.

Return type:

list

add_epoch(epoch)[source]#

Add an epoch (segment) to the imaging data.

Parameters:

epoch (BaseImagingEpoch) – The epoch (segment) to add to the imaging data.

get_sampling_frequency()[source]#
get_sample_size_in_bytes(dtype=None)[source]#
get_shape(segment_index=None)[source]#

Get the shape of the imaging data as (num_samples, height, width, planes). Used internally for SpikeInterface chunk processing.

Parameters:

segment_index (int | None) – The index of the imaging segment. If None and there is only one segment, it defaults to 0.

Returns:

The shape of the imaging data as (num_samples, height, width, planes).

Return type:

tuple

get_data(start_frame, end_frame, segment_index=None, **kwargs)[source]#

Internal function to return data for SpikeInterface chunk processing.

Parameters:
  • start_frame (int) – The starting frame index (inclusive).

  • end_frame (int) – The ending frame index (exclusive).

  • segment_index (int | None) – The index of the imaging segment. If None and there is only one segment, it defaults to 0.

Returns:

The requested series of frames as a NumPy array, with shape (num_samples, height, width, planes).

Return type:

ndarray

get_num_samples(segment_index=None)[source]#

Get the number of samples (frames) in the imaging segment.

Parameters:

segment_index (int | None) – The index of the imaging segment. If None and there is only one segment, it defaults to 0.

Returns:

The number of samples (frames) in the segment.

Return type:

int

get_num_frames(epoch_index=None)[source]#

Get the total number of frames in the imaging data.

Returns:

The total number of frames.

Return type:

int

get_total_frames()[source]#

Get the total number of frames across all segments.

Returns:

The total number of frames across all segments.

Return type:

int

get_num_epochs()[source]#

Get the number of imaging epochs.

Returns:

The number of imaging epochs.

Return type:

int

get_dtype()[source]#

Get the data type of the video.

Returns:

dtype – Dtype passed to the constructor.

Return type:

DTypeLike

get_num_pixels()[source]#

Get the number of pixels in the image.

Returns:

Number of pixels in the image.

Return type:

int

get_num_planes()[source]#

Get the number of planes in the imaging data.

Returns:

The number of planes.

Return type:

int

get_series(start_frame=None, end_frame=None, plane_ids=None, epoch_index=None)[source]#

Get a series of frames from the imaging data.

Parameters:
  • start_frame (int | None) – The starting frame index (inclusive).

  • end_frame (int | None) – The ending frame index (exclusive).

  • plane_ids (list | ndarray | None) – The list of plane IDs to include. If None, all planes are included.

  • epoch_index (int | None) – The index of the imaging segment. If None and there is only one segment, it defaults to 0.

Returns:

The requested series of frames as a NumPy array.

Return type:

ndarray

get_average_image(num_chunks=20, chunk_duration='1s', chunk_size=None, recompute=False)[source]#

Compute the average image across all frames in the imaging data.

Parameters:
  • num_chunks (int) – The number of chunks to use for computing the average image. The data will be divided into this many chunks, and the average will be computed across the chunks to save memory.

  • chunk_duration (str) – The duration of each chunk, specified as a string (e.g., “1s” for 1 second, “500ms” for 500 milliseconds).

  • chunk_size (int | None) – The number of frames in each chunk. If specified, this will override the chunk_duration.

  • recompute (bool) – If True, forces recomputation of the average image even if it has been computed before.

Returns:

The average image (height, width, num_planes)computed across sampled frames in the imaging data.

Return type:

ndarray

is_binary_compatible()[source]#

Checks if the imaging object is “binary” compatible. To be used before calling imaging.get_binary_description()

Returns:

True if the underlying imaging object is binary

Return type:

bool

get_binary_description()[source]#

When imaging.is_binary_compatible() is True this returns a dictionary describing the binary format.

Return type:

dict

save(format='binary', verbose=False, **save_kwargs)[source]#

Save a BaseImaging object to a specified format:

  • “binary”

  • “zarr”

Parameters:
  • format (str) –

    The format to save the imaging in. Options are:

    • ”binary”: Saves the imaging in binary format.

    • ”zarr”: Saves the imaging in Zarr format.

  • verbose (bool) – If True, prints additional information during the save process.

  • **save_kwargs (dict) –

    Additional keyword arguments specific to the chosen format. All formats support job_kwargs for parallel processing (see si.get_global_job_kwargs() for default values).

    • ”binary” format:
      • folderstr or Path

        The folder where the binary files will be saved.

      • overwritebool, default: False

        If True, existing files in the folder will be overwritten.

      • dtypestr, optional

        The data type to use for saving the imaging. If not provided, the imaging’s dtype will be used.

    • ”zarr” format:
      • folderstr or Path

        The folder where the Zarr files will be saved.

      • overwrite: bool, default: False

        If True, the folder is removed if it already exists

      • storage_options: dict or None, default: None

        Storage options for zarr store. E.g., if “s3://” or “gcs://” they can provide authentication methods, etc. For cloud storage locations, this should not be None (in case of default values, use an empty dict)

      • dtype: np.dtype or None, default: None

        The dtype to use for the video datasets. If None, the imaging’s dtype is used

      • compressor: numcodecs.Codec or None, default: None

        Global compressor. If None, Blosc-zstd, level 5, with bit shuffle is used

      • filters: list[numcodecs.Codec] or None, default: None

        Global filters for zarr (global)

      • compressor_by_dataset: dict or None, default: None

        Optional compressor per dataset:

        • videos

        • times

        If None, the global compressor is used

      • filters_by_dataset: dict or None, default: None

        Optional filters per dataset:

        • videos

        • times

        If None, the global filters are used

      • extra_chunks: dict or None, default: None

        Extra chunk specification passed to the zarr writer

Returns:

The saved imaging object in the specified format.

Return type:

Baseimaging

class photon_mosaic.core.baseimaging.BaseImagingEpoch(sampling_frequency=None, t_start=None, time_vector=None)[source]#

Abstract class representing a video epoch.

Methods

get_data(start_frame, end_frame[, indices])

General retrieval function for time series objects

get_series(start_frame, end_frame[, ...])

Return the raw series, optionally for a subset of samples

get_series(start_frame, end_frame, plane_indices=None)[source]#

Return the raw series, optionally for a subset of samples

Parameters:
  • start_frame (int) – start sample index, or zero if None

  • end_frame (int) – end_sample, or number of samples if None

  • plane_indices (slice | ndarray | None) – List of plane indices to include, or all planes if None

Returns:

series – Array of series, num_samples x height x width

Return type:

ndarray

get_data(start_frame, end_frame, indices=None)[source]#

General retrieval function for time series objects

Return type:

ndarray