TwoPhotonSeries

See also:: Format Specification or Source Specification for TwoPhotonSeries.

class types.core.TwoPhotonSeries(varargin)[source]

Bases: types.core.ImageSeries, types.untyped.GroupClass

TWOPHOTONSERIES - Image stack recorded over time from 2-photon microscope.

Required Properties*:: data, data_unit, imaging_plane

Constructor Summary

TwoPhotonSeries(varargin)

TWOPHOTONSERIES - Constructor for TwoPhotonSeries

Syntax:

twoPhotonSeries = types.core.TWOPHOTONSERIES() creates a TwoPhotonSeries object with unset property values.

twoPhotonSeries = types.core.TWOPHOTONSERIES(Name, Value) creates a TwoPhotonSeries object where one or more property values are specified using name-value pairs.

Input Arguments (Name-Value Arguments):

comments (char) - Human-readable comments about the TimeSeries. This second descriptive field can be used to store additional information, or descriptive information if the primary description field is populated with a computer-readable string.
control (uint8) - Numerical labels that apply to each time point in data for the purpose of querying and slicing data by these values. If present, the length of this array should be the same size as the first dimension of data.
control_description (char) - Description of each control value. Must be present if control is present. If present, control_description[0] should describe time points where control == 0.
data (numeric) - Time-series of microscopy data indexed as data[time, width, height].
Indexing convention:
- width: first spatial axis (horizontal direction, columns)
- height: second spatial axis (vertical direction, rows)
For raster-scanning systems (two-photon, confocal, one-photon laser scanning):
- width: fast scan direction (horizontal)
- height: slow scan direction (vertical)
Coordinate system diagram:
```
height  ^
(slow)  |
        |    +-----------------+
        |    |                 |
        |    |   Image plane   |
        |    |                 |
        |    +-----------------+
        |
        0 ----------------------> width (fast)
```
For non-raster systems (wide-field, light-sheet, random-access), width and height are arbitrary coordinates of the image plane.

Note: This indexing convention conflicts with standard matrix[row, column] notation for array access where the first index moves vertically through rows and the second moves horizontally through columns. In the schema, data[time, width, height] means that the first spatial index moves horizontally (width) through columns and the second spatial index moves vertically (height) through rows.
data_continuity (char) - Optionally describe the continuity of the data. Can be “continuous”, “instantaneous”, or “step”. For example, a voltage trace would be “continuous”, because samples are recorded from a continuous process. An array of lick times would be “instantaneous”, because the data represents distinct moments in time. Times of image presentations would be “step” because the picture remains the same until the next timepoint. This field is optional, but is useful in providing information about the underlying data. It may inform the way this data is interpreted, the way it is visualized, and what analysis methods are applicable. For storing instantaneous event information, it is recommended to use an EventsTable instead of a TimeSeries with continuity set to “instantaneous”.
data_conversion (single) - Scalar to multiply each element in data to convert it to the specified ‘unit’. If the data are stored in acquisition system units or other units that require a conversion to be interpretable, multiply the data by ‘conversion’ to convert the data to the specified ‘unit’. e.g. if the data acquisition system stores values in this object as signed 16-bit integers (int16 range -32,768 to 32,767) that correspond to a 5V range (-2.5V to 2.5V), and the data acquisition system gain is 8000X, then the ‘conversion’ multiplier to get from raw data acquisition values to recorded volts is 2.5/32768/8000 = 9.5367e-9.
data_offset (single) - Scalar to add to the data after scaling by ‘conversion’ to finalize its coercion to the specified ‘unit’. Two common examples of this include (a) data stored in an unsigned type that requires a shift after scaling to re-center the data, and (b) specialized recording devices that naturally cause a scalar offset with respect to the true units.
data_resolution (single) - Smallest meaningful difference between values in data, stored in the specified by unit, e.g., the change in value of the least significant bit, or a larger number if signal noise is known to be present. If unknown, use -1.0.
data_unit (char) - Base unit of measurement for working with the data. Actual stored values are not necessarily stored in these units. To access the data in these units, multiply ‘data’ by ‘conversion’ and add ‘offset’.
description (char) - Description of the time series.
device (Device) - Link to the Device object that was used to capture these images.
dimension (int32) - Number of pixels on x, y, (and z) axes.
external_file (char) - Paths to one or more external file(s). The field is only present if format=’external’. This is only relevant if the image series is stored in the file system as one or more image file(s). This field should NOT be used if the image is stored in another NWB file and that file is linked to this file.
external_file_starting_frame (int32) - Each external image may contain one or more consecutive frames of the full ImageSeries. This attribute serves as an index to indicate which frames each file contains, to facilitate random access. The ‘starting_frame’ attribute, hence, contains a list of frame numbers within the full ImageSeries of the first frame of each file listed in the parent ‘external_file’ dataset. Zero-based indexing is used (hence, the first element will always be zero). For example, if the ‘external_file’ dataset has three paths to files and the first file has 5 frames, the second file has 10 frames, and the third file has 20 frames, then this attribute will have values [0, 5, 15]. If there is a single external file that holds all of the frames of the ImageSeries (and so there is a single element in the ‘external_file’ dataset), then this attribute should have value [0].
field_of_view (single) - Physical dimensions of the imaging field of view in width, height, and optionally depth directions, in meters. The width dimension corresponds to the faster scanning axis, and the height dimension corresponds to the slower scanning axis.
format (char) - Format of image. If this is ‘external’, then the attribute ‘external_file’ contains the path information to the image files. If this is ‘raw’, then the raw (single-channel) binary data is stored in the ‘data’ dataset. If this attribute is not present, then the default format=’raw’ case is assumed.
imaging_plane (ImagingPlane) - Link to ImagingPlane object from which this TimeSeries data was generated.
num_samples (uint32) - Total number of frames across all external files. This is required when format=’external’ and timing is described using starting_time and rate, since data is empty and its first dimension cannot be used to determine the number of frames. When timestamps is provided, len(timestamps) already serves this purpose.
pmt_gain (single) - Photomultiplier gain.
scan_line_rate (single) - Lines imaged per second. This is also stored in /general/optophysiology but is kept here as it is useful information for analysis, and so good to be stored w/ the actual data.
starting_time (double) - Timestamp of the first sample in seconds. When timestamps are uniformly spaced, the timestamp of the first sample can be specified and all subsequent ones calculated from the sampling rate attribute.
starting_time_rate (single) - Sampling rate, in Hz.
timestamps (double) - Timestamps for samples stored in data, in seconds, relative to the common experiment master-clock stored in NWBFile.timestamps_reference_time.

Output Arguments:

twoPhotonSeries (types.core.TwoPhotonSeries) - A TwoPhotonSeries object

Property Summary

field_of_view: (single) Physical dimensions of the imaging field of view in width, height, and optionally depth directions, in meters. The width dimension corresponds to the faster scanning axis, and the height dimension corresponds to the slower scanning axis.

imaging_plane: REQUIRED (ImagingPlane) Link to ImagingPlane object from which this TimeSeries data was generated.

pmt_gain: (single) Photomultiplier gain.

scan_line_rate: (single) Lines imaged per second. This is also stored in /general/optophysiology but is kept here as it is useful information for analysis, and so good to be stored w/ the actual data.

Tip

* If a required property link is not functional, the property may be defined in a superclass. Please refer to the superclass documentation.