API Reference

Warning

All hidden modules, classes, functions and members (i.e. those starting with _) are hidden because they are not part of the public API and their behavior may change in future versions. We recommend you do not use them and will not provide support for them. This includes the _internal module.

The Inscopix Python API package.

class isx.CellSet

A cell set contains the image and trace data associated with components in a movie, such as cells or regions of interest.

It is always backed by a file in the native .isxd format.

Examples

Read an existing cell set from a file and get the image and trace data of the first cell.

>>> cell_set = isx.CellSet.read('recording_20160613_105808-PP-PP-BP-MC-DFF-PCA-ICA.isxd')
>>> image_0 = cell_set.get_cell_image_data(0)
>>> trace_0 = cell_set.get_cell_trace_data(0)

Write a new cell set to a file with the same timing and spacing as an existing movie, with 3 random cell images and traces.

>>> movie = isx.Movie.read('recording_20160613_105808-PP-PP.isxd')
>>> cell_set = isx.CellSet.write('cell_set.isxd', movie.timing, movie.spacing)
>>> for i in range(3):
>>>     image = numpy.random.random(cell_set.spacing.num_pixels).astype(numpy.float32)
>>>     trace = numpy.random.random(cell_set.timing.num_samples).astype(numpy.float32)
>>>     cell_set.set_cell_data(i, image, trace, 'C{}'.format(i))
>>> cell_set.flush()

Attributes

file_pathstr

The path of the file that stores this.

mode{‘r’, ‘w’}

The mode the file was opened with.

timingisx.Timing

The timing of the samples in each cell trace.

spacingisx.Spacing

The spacing of the pixels in each cell image.

num_cellsint

The number of cells or components.

flush()

Flush all meta-data and cell data to the file.

This should be called after setting all cell data of a cell set opened with isx.CellSet.write().

get_acquisition_info()

Get information about acquisition that may be stored in some files, such as nVista 3 movies and data derived from those.

Returns

dict

A dictionary likely parsed from JSON that maps from string keys to variant values.

get_cell_image_data(index)

Get the image data associated with a cell.

Arguments

indexint >= 0

The index of a cell.

Returns

numpy.ndarray

The image data in a 2D array.

get_cell_name(index)

Arguments

indexint >= 0

The index of a cell.

Returns

str

The name of the indexed cell.

get_cell_status(index)

Arguments

indexint >= 0

The index of a cell.

Returns

{‘accepted’, ‘undecided’, ‘rejected’}

The status of the indexed cell as a string.

get_cell_trace_data(index)

Get the trace data associated with a cell.

Arguments

indexint >= 0

The index of a cell.

Returns

numpy.ndarray

The trace data in a 1D array.

classmethod read(file_path, read_only=True)

Open an existing cell set from a file for reading.

This is a light weight operation that simply reads the meta-data from the cell set, and does not read any image or trace data.

Arguments

file_pathstr

The path of the file to read.

read_onlybool

If true, only allow meta-data and data to be read, otherwise allow some meta-data to be written (e.g. cell status).

Returns

isx.CellSet

The cell set that was read. Meta-data is immediately available. Image and trace data must be read using isx.CellSet.get_cell_image_data() and isx.CellSet.get_cell_trace_data() respectively.

set_cell_data(index, image, trace, name)

Set the image and trace data of a cell.

Cells must be set in increasing order, otherwise this will error.

Arguments

indexint >= 0

The index of a cell.

imagenumpy.ndarray

The image data in a 2D array.

tracenumpy.ndarray

The trace data in a 1D array.

namestr

The name of the cell.

set_cell_status(index, status)

Set the status of cell. This will also flush the file.

Warning

As this flushes the file, only use this after all cells have been written using isx.CellSet.set_cell_data().

Arguments

indexint >= 0

The index of a cell.

status{‘accepted’, ‘undecided’, ‘rejected’}

The desired status of the indexed cell.

classmethod write(file_path, timing, spacing)

Open a new cell set to a file for writing.

This is a light weight operation. It does not write any image or trace data immediately.

Arguments

file_pathstr

The path of the file to write. If it already exists, this will error.

timingisx.Timing

The timing of the cell set to write. Typically this comes from the movie this is derived from.

spacingisx.Spacing

The spacing of the movie to write. Typically this comes from the movie this is derived from.

Returns

isx.CellSet

The empty cell set that was written. Image and trace data must be written with isx.CellSet.set_cell_data().

class isx.Duration

A duration of time.

Examples

Make a period of 50 milliseconds

>>> period = isx.Duration.from_msecs(50)

Attributes

secs_floatfloat

The duration in seconds as a floating point number.

classmethod from_msecs(msecs)

Make a duration from a number of milliseconds.

classmethod from_secs(secs)

Make a duration from a number of seconds.

classmethod from_usecs(usecs)

Make a duration from a number of microseconds.

to_msecs()

Convert to an integer number of whole milliseconds.

to_secs()

Convert to an integer number of whole seconds.

to_usecs()

Convert to an integer number of whole microseconds.

class isx.Enum(value)

Generic enumeration.

Derive from this class to define new enumerations.

class isx.EventSet

An event set contains the event data of a number of components or cells.

It is typically derived from a cell set after applying an event detection algorithm. Each event of a cell is comprised of a time stamp offset and a value or amplitude.

Examples

Read an existing event set from a file and get the event data associated with the first cell.

>>> event_set = isx.EventSet.read('recording_20160613_105808-PP-PP-BP-MC-DFF-PCA-ICA-ED.isxd')
>>> [offsets, amplitudes] = event_set.get_cell_data(0)

Write a new event set to a file by applying a threshold to the traces of an existing cell set.

>>> cell_set = isx.CellSet.read('recording_20160613_105808-PP-PP-BP-MC-DFF-PCA-ICA.isxd')
>>> cell_names = ['C{}'.format(c) for c in range(cell_set.num_cells)]
>>> event_set = isx.EventSet.write('recording_20160613_105808-PP-PP-BP-MC-DFF-PCA-ICA-custom_ED.isxd', cell_set.timing, cell_names)
>>> offsets = numpy.array([x.to_usecs() for x in cell_set.timing.get_offsets_since_start()], numpy.uint64)
>>> for c in range(cell_set.num_cells):
>>>     trace = cell_set.get_cell_trace_data(c)
>>>     above_thresh = trace > 500
>>>     event_set.set_cell_data(c, offsets[above_thresh], trace[above_thresh])
>>> event_set.flush()

Attributes

file_pathstr

The path of the file that stores this.

mode{‘r’, ‘w’}

The mode the file was opened with.

timingisx.Timing

The timing of the samples in each event trace.

num_cellsint

The number of cells or components.

cell_dictdict

Dictionary mapping cell names to cell indices

flush()

Flush all meta-data and cell data to the file.

This should be called after setting all cell data of an event set opened with isx.EventSet.write().

get_acquisition_info()

Get information about acquisition that may be stored in some files, such as nVista 3 movies and data derived from those.

Returns

dict

A dictionary likely parsed from JSON that maps from string keys to variant values.

get_cell_data(index)

Get the event data associated with a cell.

Arguments

indexint >= 0

The index of a cell.

Returns

offsetsnumpy.ndarray

The 1D array of time stamps offsets from the start in microseconds.

amplitudesnumpy.ndarray

The 1D array of event amplitudes.

get_cell_index(name)

Arguments

nameint >= 0

The name of a cell.

Returns

str

The index of the named cell.

get_cell_name(index)

Arguments

indexint >= 0

The index of a cell.

Returns

str

The name of the indexed cell.

classmethod read(file_path)

Open an existing event set from a file for reading.

This is a light weight operation that simply reads the meta-data from the event set, and does not read any event data.

Arguments

file_pathstr

The path of the file to read.

Returns

isx.EventSet

The event set that was read. Meta-data is immediately available. Event data must be read using isx.EventSet.get_cell_data().

set_cell_data(index, offsets, amplitudes)

Set the event data of a cell.

Arguments

indexint >= 0

The index of a cell.

offsetsnumpy.ndarray

The 1D array of time stamps offsets from the start in microseconds.

amplitudesnumpy.ndarray

The 1D array of event amplitudes.

classmethod write(file_path, timing, cell_names)

Open a new event set to a file for writing.

This is a light weight operation. It does not write any event data immediately.

Arguments

file_pathstr

The path of the file to write. If it already exists, this will error.

timingisx.Timing

The timing of the event set to write. Typically this comes from the cell set this is derived from.

cell_nameslist<str>

The names of the cells that will be written. Typically these come from the cell set this is derived from.

Returns

isx.EventSet

The empty event set that was written. Image and trace data must be written with isx.EventSet.set_cell_data().

class isx.Fraction(numerator=0, denominator=None, *, _normalize=True)

This class implements rational numbers.

In the two-argument form of the constructor, Fraction(8, 6) will produce a rational number equivalent to 4/3. Both arguments must be Rational. The numerator defaults to 0 and the denominator defaults to 1 so that Fraction(3) == 3 and Fraction() == 0.

Fractions can also be constructed from:

• numeric strings similar to those accepted by the float constructor (for example, ‘-2.3’ or ‘1e10’)

• strings of the form ‘123/456’

• float and Decimal instances

• other Rational instances (including integers)

as_integer_ratio()

Return the integer ratio as a tuple.

Return a tuple of two integers, whose ratio is equal to the Fraction and with a positive denominator.

classmethod from_decimal(dec)

Converts a finite Decimal instance to a rational number, exactly.

classmethod from_float(f)

Converts a finite float to a rational number, exactly.

Beware that Fraction.from_float(0.3) != Fraction(3, 10).

limit_denominator(max_denominator=1000000)

Closest Fraction to self with denominator at most max_denominator.

>>> Fraction('3.141592653589793').limit_denominator(10)
Fraction(22, 7)
>>> Fraction('3.141592653589793').limit_denominator(100)
Fraction(311, 99)
>>> Fraction(4321, 8765).limit_denominator(10000)
Fraction(4321, 8765)

class isx.GpioSet

A GPIO set contains the data recorded across a number of channels.

Each data point is comprised of a time stamp offset and a value or amplitude.

Examples

Read an existing gpio set from a file and get the data associated with the first channel.

>>> gpio_set = isx.GpioSet.read('2020-05-20-10-33-22_video.gpio')
>>> [offsets, amplitudes] = gpio_set.get_channel_data(0)

Attributes

file_pathstr

The path of the file that stores this.

mode{‘r’, ‘w’}

The mode the file was opened with.

timingisx.Timing

The timing of the samples.

num_channelsint

The number of channels.

channel_dictdict

Dictionary mapping channel names to channel indices

get_acquisition_info()

Get information about acquisition that may be stored in some files, such as nVista 3 movies and data derived from those.

Returns

dict

A dictionary likely parsed from JSON that maps from string keys to variant values.

get_channel_data(index)

Get the data associated with a channel.

Arguments

indexint >= 0

The index of a channel.

Returns

offsetsnumpy.ndarray

The 1D array of time stamps offsets from the start in microseconds.

amplitudesnumpy.ndarray

The 1D array of amplitudes.

get_channel_index(name)

Arguments

nameint >= 0

The name of a channel.

Returns

str

The index of the named channel.

get_channel_name(index)

Arguments

indexint >= 0

The index of a channel.

Returns

str

The name of the indexed channel.

classmethod read(file_path)

Open an existing GPIO set from a file for reading.

This is a light weight operation that simply reads the meta-data from the GPIO set, and does not read any GPIO data.

Arguments

file_pathstr

The path of the file to read.

Returns

isx.GpioSet

The GPIO set that was read. Meta-data is immediately available. GPIO data must be read using isx.GpioSet.get_channel_data().

class isx.Image

An image is effectively a movie with one frame and no timing.

It is always backed by a file, which can be read or written using this class. See importMovie for details on what formats are supported for read. Only the native .isxd format is supported for write.

Examples

Read an existing image and get its data.

>>> image = isx.Image.read('recording_20160613_105808-PP-PP-BP-Mean Image.isxd')
>>> image_data = image.get_data()

Calculate the minimum image from an existing movie and write it.

>>> movie = isx.Movie.read('recording_20160613_105808-PP-PP.isxd')
>>> min_image = 4095 * numpy.ones(movie.spacing.num_pixels, dtype=movie.data_type)
>>> for i in range(movie.timing.num_samples):
>>>     min_image = numpy.minimum(min_image, movie.get_frame_data(i))
>>> isx.Image.write('recording_20160613_105808-PP-PP-min.isxd', movie.spacing, movie.data_type, min_image)

Attributes

file_pathstr

The path of the file that stores this.

mode{‘r’, ‘w’}

The mode the file was opened with.

spacingisx.Spacing

The spacing of the pixels in the image.

data_type{numpy.uint16, numpy.float32}

The data type of each pixel.

get_data()

Get the data stored in the image.

Returns

numpy.ndarray

The image data.

classmethod read(file_path)

Read an existing image from a file.

Arguments

file_pathstr

The path of the image file to read.

Returns

isx.Image

The image that was read.

classmethod write(file_path, spacing, data_type, data)

Write an image to a file.

Arguments

file_pathstr

The path of the file to write. If it already exists, this will error.

spacingisx.Spacing

The spacing of the image to write.

data_type{numpy.uint16, numpy.float32}

The data type of each pixel.

datanumpy.array

The 2D array of data to write.

Returns

isx.Image

The image that was written.

class isx.Movie

A movie contains a number of frames with timing and spacing information.

It is always backed by a file, which can be read or written using this class. See importMovie for details on what formats are supported for read. Only the native .isxd format is supported for write.

Examples

Read an existing movie and get its first frame as a numpy array.

>>> movie = isx.Movie.read('recording_20160613_105808-PP-PP.isxd')
>>> frame_data = movie.get_frame_data(0)

Write a 400x300 movie with 200 random frames of float32 values.

>>> timing = isx.Timing(num_samples=200)
>>> spacing = isx.Spacing(num_pixels=(300, 400))
>>> movie = isx.Movie.write('movie-400x300x200.isxd', timing, spacing, numpy.float32)
>>> for i in range(timing.num_samples):
>>>     movie.set_frame_data(i, numpy.random.random(spacing.num_pixels).astype(numpy.float32))
>>> movie.flush()

Attributes

file_pathstr

The path of the file that stores this.

mode{‘r’, ‘w’}

The mode the file was opened with.

timingisx.Timing

The timing of the frames.

spacingisx.Spacing

The spacing of the pixels in each frame.

data_type{numpy.uint16, numpy.float32}

The data type of each pixel.

flush()

Flush all meta-data and frame data to the file.

This should be called after setting all frames of a movie opened with isx.Movie.write().

get_acquisition_info()

Get information about acquisition that may be stored in some files, such as nVista 3 movies and data derived from those.

Returns

dict

A dictionary likely parsed from JSON that maps from string keys to variant values.

get_frame_data(index)

Get a frame from the movie by index.

Arguments

indexint >= 0

The index of the frame. If this is out of range, this should error.

Returns

numpy.ndarray

The retrieved frame data.

get_frame_timestamp(index)

Get a frame timestamp from the movie by index.

The timestamps are in units of microseconds. This is a TSC (time stamp counter) value which is saved during acquisition. These values come from a hardware counter on a particular acquisition box. As a result, they can only be used to compare to other values that originate from the same hardware counter (e.g., paired recordings).

To get timestamps relative to the start of the movie, simply subtract each timestamp with the timestamp of the first frame in the movie. To get timestamps relative to Unix epoch time, add the timestamps computed relative to the start of the movie with the Unix epoch start timestamp of the movie, accessible through the timing member of this class. Alternatively, the timestamps of a movie can be exported relative to the start of the movie, or relative to the Unix epoch time, using the function isx.export_movie_timestamps_to_csv.

Arguments

indexint >= 0

The index of the frame. If this is out of range, this should error.

Returns

int

The retreived frame timestamp. If the movie has no frame timestamps, the function will throw an error,

classmethod read(file_path)

Open an existing movie from a file for reading.

This is a light weight operation that simply reads the meta-data from the movie, and does not read any frame data.

Arguments

file_pathstr

The path of the file to read.

Returns

isx.Movie

The movie that was read. Meta-data is immediately available. Frames must be read using isx.Movie.get_frame().

set_frame_data(index, frame)

Set frame data in a writable movie.

Frames must be set in increasing order, otherwise this will error.

Arguments

indexint >= 0

The index of the frame.

framenumpy.ndarray

The frame data.

classmethod write(file_path, timing, spacing, data_type)

Open a new movie to a file for writing.

This is a light weight operation. It does not write any frame data immediately.

Arguments

file_pathstr

The path of the file to write. If it already exists, this will error.

timingisx.Timing

The timing of the movie to write.

spacingisx.Spacing

The spacing of the movie to write.

data_type{numpy.uint16, numpy.float32}

The data type of each pixel.

Returns

isx.Movie

The empty movie that was written. Frame data must be written with isx.Movie.set_frame_data().

class isx.Spacing(num_pixels=(0, 0))

The spacing associated with a set of pixels.

Examples

Make spacing for a 1440x1080 image.

>>> spacing = isx.Spacing(num_pixels=(1080, 1440))

Attributes

num_pixels2-tuple<int>

The number of pixels as (num_rows, num_cols).

class isx.Time

A time stamp that defines a calendar date and wall time.

to_datetime()

Returns

datetime.datetime

The nearest Python datetime.

class isx.Timing(num_samples=0, period=<isx.core.Duration object>, start=<isx.core.Time object>, dropped=[], cropped=[], blank=[])

The timing associated with a set of samples, such as the frames of a movie or the values of a trace.

Some samples are described as invalid, meaning that the sample is missing. These include dropped samples, which could arise due to an error at acquisition time, and cropped samples, which are likely due to processing.

Examples

Make timing for 9 samples, every 10 milliseconds.

>>> timing = isx.Timing(num_samples=9, period=isx.Duration.from_msecs(10))

Attributes

num_samplesint >= 0

The number of samples, including invalid (dropped, cropped, or blank) ones.

periodisx.Duration

The period or duration of one sample.

startisx.Time

The time stamp associated with the start of the first sample.

droppedlist<int>

The indices of the dropped samples.

croppedlist<2-tuple>

The index ranges of the cropped samples. Each element specifies the inclusive lower and upper bounds of a range of indices.

blanklist<int>

The indices of the blank samples.

get_offsets_since_start()

Get the offsets from the start of the timing.

Returns

list<isx.Duration>

Each element is the offset from the start to a sample.

get_valid_samples()

Returns

numpy.ndarray

The valid sample indices.

get_valid_samples_mask()

Get a 1D array mask indicating whether each sample is valid.

Returns

numpy.ndarray

Each element indicates whether the corresponding sample is valid.

class isx.VesselSet

A vessel set contains the image, line and trace data associated with components in a movie, such as vessels or regions of interest.

It is always backed by a file in the native .isxd format.

A vessel set can represent two types of data: vessel diameter and rbc velocity. Depending on the vessel type, different information will be stored to disk.

Note: Since blood flow algorithms apply a sliding window over input movies, the timing of a vessel trace is different from the timing of its input movie. Each frame of a vessel trace represents a measurement for a particular window sampled from its input movie. Relative to the input movie, each frame maps to the start of the corresponding window sampled. The duration of a frame is equal to the time increment of the sliding window.

The following examples will demonstrate the types of data accessible for both types of vessel sets.

Examples

Vessel Diameter Read an existing vessel set from a file and get the image, line and diameter trace data of the first vessel.

>>> vessel_set = isx.VesselSet.read('bloodflow_movie_10s-VD.isxd')
>>> image_0 = vessel_set.get_vessel_image_data(0)
>>> line_0 = vessel_set.get_vessel_line_data(0)
>>> trace_0 = vessel_set.get_vessel_trace_data(0)
>>> center_trace_0 = vessel_set.get_vessel_center_trace_data(0)

Write a new vessel set to a file with the same timing and spacing as an existing movie, with 3 random vessel images, lines and diameter traces.

>>> movie = isx.Movie.read('recording_20160613_105808-PP-PP.isxd')
>>> vessel_set = isx.VesselSet.write('vessel_set.isxd', movie.timing, movie.spacing, 'vessel diameter')
>>> for i in range(3):
>>>     image = numpy.random.random(vessel_set.spacing.num_pixels).astype(numpy.float32)
>>>     lines = numpy.random.randint(0, min(spacing.num_pixels), (num_vessels, 2, 2))
>>>     trace = numpy.random.random(vessel_set.timing.num_samples).astype(numpy.float32)
>>>     center_trace = numpy.random.random(vessel_set.timing.num_samples).astype(numpy.float32)
>>>     vessel_set.set_vessel_diameter_data(i, image, lines, trace, center_trace, 'V{}'.format(i))
>>> vessel_set.flush()

RBC Velocity Read an existing vessel set from a file and get the image, line and rbc velocity trace data of the first vessel.

>>> vessel_set = isx.VesselSet.read('bloodflow_movie_10s-RBCV.isxd')
>>> image_0 = vessel_set.get_vessel_image_data(0)
>>> line_0 = vessel_set.get_vessel_line_data(0)
>>> trace_0 = vessel_set.get_vessel_trace_data(0)
>>> direction_trace_0 = vessel_set.get_vessel_direction_trace_data(0)
>>> corr_0 = vessel_set.get_vessel_correlations_data(0, 0) # look at first frame of correlation data for the first vessel

Write a new vessel set to a file with the same timing and spacing as an existing movie, with 3 random vessel images, lines and rbc velocity traces.

>>> movie = isx.Movie.read('recording_20160613_105808-PP-PP.isxd')
>>> vessel_set = isx.VesselSet.write('vessel_set.isxd', movie.timing, movie.spacing, 'rbc velocity')
>>> for i in range(3):
>>>     image = numpy.random.random(vessel_set.spacing.num_pixels).astype(numpy.float32)
>>>     lines = numpy.random.randint(0, min(spacing.num_pixels), (num_vessels, 2, 2))
>>>     trace = numpy.random.random(vessel_set.timing.num_samples).astype(numpy.float32)
>>>     direction_trace = numpy.random.random(vessel_set.timing.num_samples).astype(numpy.float32)
>>>     correlation_size = np.random.randint(2, 5, size=(2,))
>>>     correlations_trace = numpy.random.random([vessel_set.timing.num_samples, 3, correlation_size[0], correlation_size[1]]).astype(numpy.float32)
>>>     vessel_set.set_rbc_velocity_data(i, image, lines, trace, direction_trace, correlations_trace, 'V{}'.format(i))
>>> vessel_set.flush()

Attributes

file_pathstr

The path of the file that stores this.

mode{‘r’, ‘w’}

The mode the file was opened with.

timingisx.Timing

The timing of the samples in each vessel trace.

spacingisx.Spacing

The spacing of the pixels in each vessel image.

num_vesselsint

The number of vessels or components.

class VesselSetType(value)

An enumeration.

flush()

Flush all meta-data and vessel data to the file.

This should be called after setting all vessel data of a vessel set opened with isx.VesselSet.write().

get_acquisition_info()

Get information about acquisition that may be stored in some files, such as nVista 3 movies and data derived from those.

Returns

dict

A dictionary likely parsed from JSON that maps from string keys to variant values.

get_vessel_center_trace_data(index)

Get the center trace data associated with a vessel. This represents an index on the user drawn line where the center of the diamter was estimated to be.

Arguments

indexint >= 0

The index of a vessel.

Returns

numpy.ndarray

The center trace data in a 1D array. If no center traces are stored in the file, the function will throw an error

get_vessel_correlations_data(index, frame)

Get the correlation trace data associated with a vessel at a certain frame.

Arguments

indexint >= 0

The index of a vessel.

frameint >= 0

The frame index of the time-series trace.

Returns

numpy.ndarray

The correlations data in a 3D array of size (3, width, height) Each slice of the ndarray is a correlation heatmap for a particular temporal offset The mapping of temporal offsets is (slice 0 -> t = -1, slice 1 -> t = 0, slice 2 = t = 1) If no correlations are stored in the file, the function will throw an error

get_vessel_direction_trace_data(index)

Get the direction trace data associated with a vessel This is the direction component of each velocity measurement reported in degrees relative to positive x-axis.

Arguments

indexint >= 0

The index of a vessel.

Returns

numpy.ndarray

The direction trace data in a 1D array. If no direction traces are stored in the file, the function will throw an error

get_vessel_image_data(index)

Get the image data associated with a vessel.

Arguments

indexint >= 0

The index of a vessel.

Returns

numpy.ndarray

The image data in a 2D array.

get_vessel_line_data(index)

Get the line data associated with a vessel.

Arguments

indexint >= 0

The index of a vessel.

Returns

numpy.ndarray

The line data in a 2D array.

get_vessel_name(index)

Arguments

indexint >= 0

The index of a vessel.

Returns

str

The name of the indexed vessel.

get_vessel_set_type()

Get the type of the vessel set.

Returns

VesselSetType Enum

An enum representation of the different vessel set types. either VesselSetType.VESSEL_DIAMETER or VesselSetType.RBC_VELOCITY

get_vessel_status(index)

Arguments

indexint >= 0

The index of a vessel.

Returns

{‘accepted’, ‘undecided’, ‘rejected’}

The status of the indexed vessel as a string.

get_vessel_trace_data(index)

Get the trace data associated with a vessel.

Arguments

indexint >= 0

The index of a vessel.

Returns

numpy.ndarray

The trace data in a 1D array.

has_correlation_heatmaps()

If true, cross-correlation heatmaps for rbc velocity measurements are stored in this file.

Returns

bool

Flag indicating whether heatmaps were saved.

classmethod read(file_path, read_only=True)

Open an existing vessel set from a file for reading.

This is a light weight operation that simply reads the meta-data from the vessel set, and does not read any image or trace data.

Arguments

file_pathstr

The path of the file to read.

read_onlybool

If true, only allow meta-data and data to be read, otherwise allow some meta-data to be written (e.g. vessel status).

Returns

isx.VesselSet

The vessel set that was read. Meta-data is immediately available. Image and trace data must be read using isx.VesselSet.get_vessel_image_data() and isx.VesselSet.get_vessel_trace_data() respectively.

set_rbc_velocity_data(index, image, line, trace, direction_trace, correlations_trace=None, name=None)

Set the image, line and rbc velocity trace data of a vessel.

Vessels must be set in increasing order, otherwise this will error.

Arguments

indexint >= 0

The index of a vessel.

imagenumpy.ndarray

The image data in a 2D array.

linenumpy.ndarray

The line endpoint data in a 2D array.

tracenumpy.ndarray

The trace data in a 1D array.

direction_tracenumpy.ndarray

The direction trace data in a 1D array.

correlations_tracenumpy.ndarray

The correlations trace data in a 4D array T x 3 x W x H Where T is the number of time samples W is the width of the correlation heatmap H is the width of the correlation heatmap There are three heatmaps for each time sample representing the three temporal offsets (-1, 0, 1)

namestr

The name of the vessel.

set_vessel_diameter_data(index, image, line, trace, center_trace, name=None)

Set the image, line and diameter trace data of a vessel

Vessels must be set in increasing order, otherwise this will error.

Arguments

indexint >= 0

The index of a vessel.

imagenumpy.ndarray

The image data in a 2D array.

linenumpy.ndarray

The line endpoint data in a 2D array.

tracenumpy.ndarray

The trace data in a 1D array.

center_tracenumpy.ndarray

The center trace data in a 1D array.

namestr

The name of the vessel.

set_vessel_status(index, status)

Set the status of vessel. This will also flush the file.

Warning

As this flushes the file, only use this after all vessels have been written using isx.VesselSet.set_vessel_data().

Arguments

indexint >= 0

The index of a vessel.

status{‘accepted’, ‘undecided’, ‘rejected’}

The desired status of the indexed vessel.

classmethod write(file_path, timing, spacing, vessel_type)

Open a new vessel set to a file for writing.

This is a light weight operation. It does not write any image or trace data immediately.

Arguments

file_pathstr

The path of the file to write. If it already exists, this will error.

timingisx.Timing

The timing of the vessel set to write. Typically this comes from the movie this is derived from.

spacingisx.Spacing

The spacing of the movie to write. Typically this comes from the movie this is derived from.

vessel_typestr

The type of metric to store in the vessel set. Either ‘vessel diameter’ or ‘rbc velocity’.

Returns

isx.VesselSet

The empty vessel set that was written. Image and trace data must be written with isx.VesselSet.set_vessel_data().

isx.align_start_times(input_ref_file, input_align_files)

Align the epoch start times of files originating from the same paired and synchronized start-stop recording session. The epoch start time stored in the input align files are modified in-place so that they are aligned relative to the epoch start time of the input timing reference file

For each input align file, the epoch start time is recomputed using the following formula:

align_epoch_start_ms = ref_epoch_start_ms + ((align_first_tsc_us - ref_first_tsc_us) / 1e3)

In the event that the first sample of an input align file is dropped, the tsc value of the first sample is inferred using the following formula:

align_first_tsc_us = align_first_valid_tsc_us - (align_first_valid_idx * align_sample_period_us)

Arguments

input_ref_filestr

The path of the file to use as the timing reference to align with the other input files. This can be either a .gpio file, .isxd movie, or .isxb movie, otherwise the function will throw an error. If the timing reference is a movie, the movie must contain frame timestamps, otherwise this function will throw an error.

input_align_fileslist<str>

The path of the files to align to the epoch start time of the input timing reference file. These files can either be an .isxd movie or .isxb movie, otherwise the function will throw an error. The movies must contain frame timestamps, otherwise this function will throw an error.

isx.convert_type_numpy_array(array, dtype=<class 'numpy.uint16'>, keep_0_to_1=False)

Convert a numpy array to a different data type by normalizing and mapping.

isx.create_cell_map(isxd_cellset_file, selected_cell_statuses=['accepted'], cell_thresh=0.3, binary=False, rgb=None, output_isxd_cell_map_file=None, output_tiff_cell_map_file=None)

Generate cell map from an .isxd cellset file, saving the image as isxd and tiff.

Arguments

isxd_cellset_filestr

Path to an .isxd cellset file.

selected_cell_statuseslist<str>

a list of cell statuses for decision criteria to keep cell footprints. Possible list values are ‘accepted’, ‘undecided’, ‘rejected’.

cell_threshfloat [0, 1]

Pixels with values lower than cell_thresh will be set to 0.

binaryBool

If true, pixels with values above cell_thresh are set to 1. (Pixels with values below cell_thresh are set to 0.)

rgbone of “red”, “blue”, or “green”

Color for the cell map.

output_isxd_cell_map_filestr

Path to the output isxd cell map image. If not given, will not be generated.

output_tiff_cell_map_filestr

Path to the output tiff cell map image. If not given, will not be generated.

isx.export_aligned_timestamps(input_ref_file, input_align_files, input_ref_name, input_align_names, output_csv_file, time_ref='start')

Export timestamps from files which originate from the same paired and synced start-stop recording session to a .csv file. Timestamps are aligned to a single start time which is defined as the start time of the specified timing reference file.

Arguments

input_ref_filestr

The path of the file to use as the timing reference to align with the other input files. Timestamps are exported relative to the start time of this file. This can be either a .gpio file, .isxd movie, or .isxb movie, otherwise the function will throw an error. If the timing reference is a movie, the movie must contain frame timestamps, otherwise this function will throw an error.

input_align_fileslist<str>

The path of the files to align to the epoch start time of the input timing reference file. These files can either be a .gpio file, .isxd movie, or .isxb movie, otherwise the function will throw an error. The movies must contain frame timestamps, otherwise this function will throw an error.

input_ref_namestr

The name of the reference data set to use in the output csv.

input_align_nameslist<str>

The names of the align data sets to use in the output csv.

output_csv_filestr

The path of the csv file to be written.

time_ref{‘start’, ‘unix’, ‘tsc’}

The time reference for the CSV time stamps. If ‘start’ is used, the timestamps represent the seconds since the start of the movie. If ‘unix’ is used, the timestamps represent the seconds since the Unix epoch. If ‘tsc’ is used, the timestamps represent the hardware counter value on the acquisition box when each frame was captured.

isx.export_cell_set_to_csv_tiff(input_cell_set_files, output_csv_file, output_tiff_file, time_ref='start', output_props_file='')

Export cell sets to a CSV file with trace data and TIFF files with image data.

For more details see exportCellsAndStuff.

Unlike the desktop application, this will only produce a TIFF cell map image file and not a PNG file too.

Arguments

input_cell_set_fileslist<str>

The file paths of the cell sets to export.

output_csv_filestr

The path of the CSV file to write.

output_tiff_filestr

The base name of the TIFF files to write.

time_ref{‘start’, ‘unix’}

The time reference for the CSV time stamps. If ‘start’ is used, the time stamps represent the seconds since the start of the cell set. If ‘unix’ is used, the time stamps represents the second since the Unix epoch.

output_props_filestr

The path of the properties CSV file to write.

isx.export_ethovision_data_with_isxb_timestamps(input_ethovision_file, input_isxb_file, output_csv_file, input_ref_file=None, time_ref='start')

Given paths to an Ethovision file and a nVision (.isxb) movie file,

writes a csv file with Ethovision data and a dedicated column, either isxb Frame Timestamp (s) or isxb Frame Timestamp (us) depending on the format of the timestamps, that contains aligned timestamps from the nVision movie.

It is important to note that internal Inscopix testing has shown that the Ethovision output file

can have a length that is one less than the number of frames in the input movie. When this is true, the missing data row appears to be at the beginning. This function applies .isxb timestamps to the Ethovision table while ignoring the first timestamp to compensate for the length mismatch if the mismatch exists. More recent versions of Ethovision should prevent this from occuring.

Arguments

input_ethovision_file: str

The path to the Ethovision file (.csv, .xlsx).

input_isxb_file: str

The path to the nVision (.isxb) movie file.

output_csv_file: str

The path to the output csv file.

input_ref_file: str | None

The path to the reference file (.isxd, .gpio, .isxb). Timestamps from the .isxb file are aligned to the start time of this file. Generally, this reference is a file from a miniscope recording which was synchronized with this .isxb file. This argument is required if the time_ref is selected as ‘start’ or ‘unix’. If the .isxb file is a standalone behaviour recording that is not synchronized to any miniscope file, simply provide the .isxb file as the reference (if it’s required).

time_ref{‘start’, ‘unix’, ‘tsc’}

The time reference for the nVision (.isxb) timestamps. If ‘tsc’ is used, the timestamps represent the hardware counter value in microseconds on the acquisition box when each frame was captured. If ‘start’ is used, the timestamps represent the seconds since the start of the experiment.

Note: input_ref_file must be specified if this option is used, otherwise an exception is thrown. Timestamps are exported relative to the start time of the reference file.

If ‘unix’ is used, the timestamps represent the seconds since the Unix epoch.

Note: input_ref_file must be specified if this option is used, otherwise an exception is thrown. The input_ref_file ensures that isx.align_start_times has been called on the .isxb file with the corresponding, synchronized miniscope file.

isx.export_event_set_to_csv(input_event_set_files, output_csv_file, time_ref='start', output_props_file='', sparse_output=True, write_amplitude=True)

Export event sets to a CSV file.

For more details see exportCellsAndStuff.

Arguments

input_event_set_fileslist<str>

The file paths of the cell sets to export.

output_csv_filestr

The path of the CSV file to write.

time_ref{‘start’, ‘unix’}

The time reference for the CSV time stamps. If ‘start’ is used, the time stamps represent the seconds since the start of the cell set. If ‘unix’ is used, the time stamps represents the second since the Unix epoch.

output_props_filestr

The path of the properties CSV file to write.

sparse_output: bool

If true, output events in sparse format showing all time points, otherwise, output events in dense format showing only timepoints with events.

write_amplitude: bool

Only relevant when sparse_output is True. If true, write amplitudes of each event, otherwise, writes 1 where events occur and 0 elsewhere.

isx.export_gpio_set_to_csv(input_gpio_set_files, output_csv_file, inter_isxd_file_dir='/tmp', time_ref='start')

Export gpio sets to a CSV file.

If exporting more than one file, for correct formatting, files should either be all non .imu files or all .imu files.

For more details see exportCellsAndStuff.

Arguments

input_gpio_set_fileslist<str>

The file paths of the cell sets to export.

output_csv_filestr

The path of the CSV file to write.

inter_isxd_file_dirstr

The path of the directory to put intermediate .isxd file The default path for Mac & Linux is /tmp. The default path for Windows is the directory containing the input gpio file.

time_ref{‘start’, ‘unix’}

The time reference for the CSV time stamps. If ‘start’ is used, the time stamps represent the seconds since the start of the cell set. If ‘unix’ is used, the time stamps represents the second since the Unix epoch.

isx.export_gpio_to_isxd(input_gpio_file, output_isxd_dir)

Export GPIO file (.gpio, .raw, .hdf5, .imu) to an Inscopix Data File (.isxd).

Output file will have the name <input_file_name>_gpio.isxd

Arguments

input_gpio_filelist<str>

The file path of the gpio file to be exported.

output_isxd_dirstr

The path of the directory to write isxd file.

isx.export_image_to_isxd_tiff(image, isxd_file, tiff_file, rgb=None)

Save an image as isxd and tiff. If rgb is one of ‘red’, ‘green’, ‘blue’, the images will be colored.

isx.export_image_to_tiff(image, tiff_file, write_rgb=False)

Save an image as a uint16 tiff.

isx.export_isxd_image_to_tiff(input_isxd_image, output_tiff_file)

Convert an ISXD image file to a tiff image. WARNING: does not export tiff with alignment metadata, use align_image instead

Arguments

input_isxd_imagestr

Path to the input ISXD image file.

output_tiff_filestr

Path to the output tiff file.

isx.export_movie_timestamps_to_csv(input_movie_files, output_csv_file, time_ref='start')

Export movie frame timestamps to a csv file. This operation is supported for .isxd and .isxb movies.

For more details see exportMovie.

Arguments

input_movie_fileslist<str>

The file paths of the movies to export frame timestamps from.

output_csv_filestr

The path of the csv file to be written.

time_ref{‘start’, ‘unix’, ‘tsc’}

The time reference for the CSV time stamps. If ‘start’ is used, the timestamps represent the seconds since the start of the movie. If ‘unix’ is used, the timestamps represent the seconds since the Unix epoch. If ‘tsc’ is used, the timestamps represent the hardware counter value on the acquisition box when each frame was captured.

isx.export_movie_to_mp4(input_movie_files, output_mp4_file, compression_quality=0.1, write_invalid_frames=False, frame_rate_format='float', draw_bounding_box=True, draw_bounding_box_center=True, draw_zones=True)

Export movies to an MP4 file.

For more details see exportMovie.

Arguments

input_movie_fileslist<str>

The file paths of the movies to be exported.

output_mp4_filestr

The path of the MP4 file to be written.

compression_qualityfloat

A value between 0.001 and 1 that controls the quality and size of the output file for the MP4 format. The larger the value, the better the quality of the movie, but the larger the size of the file. The default value of 0.1 typically produces a good quality movie where the file is at most 10% of the uncompressed original file size, but may be smaller if the movie content can be efficiently encoded. More formally, this represents a rough maximum on the output file size as a fraction of the original file size.

write_invalid_framesbool

If True, write invalid (dropped, cropped, and blank) frames as zero, otherwise, do not write them at all.

frame_rate_format{“float”, “int”}

Format to encode the frame rate in the output mp4 file. If float, the frame rate will be exported as a precise estimate of the input movie sampling rate. If int, the frame rate will be rounded to the nearest integer.

draw_bounding_boxbool

Only used for nVision .isxb movies. If there is nVision tracking data in the .isxb movie, and this flag is enabled, then draw the bounding box estimate on each frame of the exported mp4 movie.

draw_bounding_box_centerbool

Only used for nVision .isxb movies. If there is nVision tracking data in the .isxb movie, and this flag is enabled, then draw the center of the bounding box estimate on each frame of the exported mp4 movie.

draw_zonesbool

Only used for nVision .isxb movies. If there is nVision tracking data in the .isxb movie, and this flag is enabled, then draw the zones of the tracking area on each frame of the exported mp4 movie.

isx.export_movie_to_nwb(input_movie_files, output_nwb_file, identifier='', session_description='', comments='', description='', experiment_description='', experimenter='', institution='', lab='', session_id='')

Export movies to an HDF5-based neurodata without borders (NWB) file.

For more details see exportMovie.

Arguments

input_movie_fileslist<str>

The file paths of the movies to be exported.

output_nwb_filestr

The path of the NWB file to be written.

identifierstr

An identifier for the file according to the NWB spec.

session_descriptionstr

A session description for the file according to the NWB spec.

commentsstr

Comments on the recording session.

descriptionstr

Description for the file according to the NWB spec.

experiment_descriptionstr

Details about the experiment.

experimenterstr

The person who recorded the data.

institutionstr

The place where the recording was performed.

labstr

The lab where the recording was performed.

session_idstr

A unique session identifier for the recording.

isx.export_movie_to_tiff(input_movie_files, output_tiff_file, write_invalid_frames=False)

Export movies to a TIFF file.

For more details see exportMovie.

Arguments

input_movie_fileslist<str>

The file paths of the movies to be exported.

output_tiff_filestr

The path of the TIFF file to be written.

write_invalid_framesbool

If True, write invalid (dropped, cropped, and blank) frames as zero, otherwise, do not write them at all.

isx.export_nvision_movie_tracking_frame_data_to_csv(input_movie_files, output_csv_file, time_ref='start')

Export frame tracking metadata from an nVision movie. This operation is supported for .isxb movies.

The frame tracking metadata is generated by the nVision tracking model, and includes the following columns:

• Global Frame Number: The frame number in the input movie series.

• Movie Number: The movie number in the series.

• Local Frame Number: The frame number in the individual movie.

• Frame Timestamp: The frame timestamp. In units of seconds or microseconds based on the input time_ref parameter.

• Bounding Box Left: X coordinate of the top left corner of the bounding box. In units of pixels.

• Bounding Box Top: Y coordinate of the top left corner of the bounding box. In units of pixels.

• Bounding Box Right: X coordinate of the bottom right corner of the bounding box. In units of pixels.

• Bounding Box Bottom: Y coordinate of the bottom right corner of the bounding box. In units of pixels.

• Bounding Box Center X: X coordinate of the center point of the bounding box. In units of pixels.

• Bounding Box Center Y: Y coordinate of the center point of the bounding box. In units of pixels.

• Confidence: The nVision tracking model confidence of the bounding box estimate. In units of %.

• Zone ID: If the nVision tracking model detected the mouse was inside a zone, this column contains the id of that zone.

• Zone Name: If the nVision tracking model detected the mouse was inside a zone, this column contains the name of that zone.

For more details see exportMovie.

Arguments

input_movie_fileslist<str>

The file paths of the movies to export frame tracking metadata from.

output_csv_filestr

The path of the csv file to be written.

time_ref{‘start’, ‘unix’, ‘tsc’}

The time reference for the CSV time stamps. If ‘start’ is used, the timestamps represent the seconds since the start of the movie. If ‘unix’ is used, the timestamps represent the seconds since the Unix epoch. If ‘tsc’ is used, the timestamps represent the hardware counter value on the acquisition box when each frame was captured.

isx.export_nvision_movie_tracking_zone_data_to_csv(input_movie_files, output_csv_file)

Export zone tracking metadata from an nVision movie. This operation is supported for .isxb movies.

The zone tracking metadata used by the nVision tracking model, and includes the following columns:

• ID: Unique identifier for the zone.

• Enabled: Flag indicating whether the zone is enabled for tracking.

• Name: User friendly name for the zone.

• Description: Optional description for the zone

• Type: The shape of the zone. Can be either rectangle, polygon, or ellipse.

• X i: The ith X coordinate of the zone.

  Note: Since zones can have different shapes, they can have a different number of coordinates. The csv output will contain n columns for the X coordinate, where n is the maxmimum number of coordinates across all zones in the metadata.

• Y i: The ith Y coordinate of the zone.

  Note: Since zones can have different shapes, they can have a different number of coordinates. The csv output will contain n columns for the Y coordinate, where n is the maxmimum number of coordinates across all zones in the metadata.

• Major Axis: only outputted for ellipse shaped zones. Length of the major axis.

• Minor Axis: only outputted for ellipse shaped zones. Length of the minor axis.

• Angle: only outputted for ellipse shaped zones. Ellipse rotation angle in degrees.

For more details see exportMovie.

Arguments

input_movie_fileslist<str>

The file paths of the movies to export frame tracking metadata from.

output_csv_filestr

The path of the csv file to be written.

isx.export_tiff_to_isxd_image(input_tiff_file, output_isxd_file)

Convert an tiff image file to an ISXD image. WARNING: does not export tiff with alignment metadata, use align_image instead

Arguments

input_tiff_filestr

Path to the input tiff file.

output_isxd_filestr

Path to the output ISXD image file.

isx.export_vessel_set_to_csv_tiff(input_vessel_set_files, output_trace_csv_file='', output_line_csv_file='', output_map_tiff_file='', output_heatmaps_tiff_dir='', time_ref='start')

Export vessel sets to a CSV file with trace data and TIFF files with image data.

Arguments

input_vessel_set_fileslist<str>

The file paths of the vessel sets to export.

output_trace_csv_filestr

The path of the trace CSV file to write.

output_line_csv_filestr

The path of the line CSV file to write.

output_map_tiff_filestr

The name of the vessel map TIFF file to write.

output_heatmaps_tiff_dirstr

The name of the directory to write correlation heatmaps as TIFF stacks.

time_ref{‘start’, ‘unix’}

The time reference for the CSV time stamps. If ‘start’ is used, the time stamps represent the seconds since the start of the vessel set. If ‘unix’ is used, the time stamps represents the second since the Unix epoch.

isx.get_file_extension(in_file)

Get full extension for file that can have multiple extensions.

isx.get_file_stem(in_file)

Get the file stem for file that can have multiple extensions.

isx.make_output_file_path(in_file, out_dir, suffix=None, ext='isxd')

Make an output file path from an input path, output directory, suffix and extension.

This is useful for generate output file paths for processing steps.

Arguments

in_filestr

The input file path.

out_dirstr

The output directory path.

suffixstr

The suffix to append to the file stem with a ‘-‘. If left empty, no suffix is appended.

ext‘isxd’

The output file extension, not including the ‘.’.

Returns

str

The output file path.

Examples

Make the output file path for a preprocessed recording.

>>> make_output_file_path('in_dir/in_file.xml', 'out_dir', 'PP')
'out_dir/in_file-PP.isxd'

isx.make_output_file_paths(in_files, out_dir, suffix, ext='isxd')

Like isx.make_output_file_path(), but for many files.

isx.overlay_cell_map_on_image(input_isxd_cell_map_file, input_isxd_image_file, output_tiff_image_file)

Overlay a cellmap onto an image, and save as isxd. Can save tiff as well.

Arguments

input_isxd_cell_map_filestr

Path to an .isxd cell map image file.

input_isxd_image_filestr

Path to an .isxd image file to overlay on.

output_tiff_image_filestr

Path to the output isxd cell map image.

isx.overlay_cellmaps(first_tiff_cellmap_file, second_tiff_cellmap_file, overlayed_tiff_cellmap_file, background_color='#000000', first_color='#00ff00', second_color='#ff00ff', cell_thresh=0.5)

Overlay two cellmaps using different colors to show overlap.

Arguments

first_tiff_cellmap_filestr

Path to the first tiff cellmap image.

second_tiff_cellmap_filestr

Path to the second tiff cellmap image.

overlayed_tiff_cellmap_filestr

Path to the output tiff cellmap.

background_colorstr

Hex color code for background. Format: #RRGGBB

first_colorstr

Hex color code for cells in first cellmap. Format: #RRGGBB

second_colorstr

Hex color code for cells in second cellmap. Format: #RRGGBB

cell_threshfloat [0, 1]

Pixel values less than cell_thresh will be considered as the background.

isx.verify_deinterleave(in_file, efocus)

Verify if all frames from movie has the same efocus as provided.

Arguments

in_filestr

The input file path.

efocusint

The efocus value to be compared with.

Returns

bool

True if the movie is successfully verified, False otherwise.