pynwb.base module

class pynwb.base.ProcessingModule(name, description, data_interfaces=None)[source]

Bases: MultiContainerInterface

Processing module. This is a container for one or more containers that provide data at intermediate levels of analysis

ProcessingModules should be created through calls to NWB.create_module(). They should not be instantiated directly

Parameters:

name (str) – The name of this processing module
description (str) – Description of this processing module
data_interfaces (list or tuple or dict) – NWBDataInterfaces that belong to this ProcessingModule

property description: Description of this processing module

property data_interfaces: a dictionary containing the NWBDataInterface or DynamicTable in this ProcessingModule

property containers

add_container(container)[source]

Add an NWBContainer to this ProcessingModule

Parameters:: container (NWBDataInterface or DynamicTable) – the NWBDataInterface to add to this Module

get_container(container_name)[source]

Retrieve an NWBContainer from this ProcessingModule

Parameters:: container_name (str) – the name of the NWBContainer to retrieve

add_data_interface(NWBDataInterface)[source]

Parameters:: NWBDataInterface (NWBDataInterface or DynamicTable) – the NWBDataInterface to add to this Module

get_data_interface(data_interface_name)[source]

Parameters:: data_interface_name (str) – the name of the NWBContainer to retrieve

keys()[source]

Get the names of data interfaces in this ProcessingModule.

Returns:: View of interface names
Return type:: KeysView

values()[source]

Get the data interfaces in this ProcessingModule.

Returns:: View of interfaces
Return type:: ValuesView

items()[source]

Get the (name, interface) pairs in this ProcessingModule.

Returns:: View of (name, interface) pairs
Return type:: ItemsView

__getitem__(name=None)

Get a NWBDataInterface from this ProcessingModule

Parameters:: name (str) – the name of the NWBDataInterface or DynamicTable
Returns:: the NWBDataInterface or DynamicTable with the given name
Return type:: NWBDataInterface or DynamicTable

add(data_interfaces)

Add one or multiple NWBDataInterface or DynamicTable objects to this ProcessingModule

Parameters:: data_interfaces (list or tuple or dict or NWBDataInterface or DynamicTable) – one or multiple NWBDataInterface or DynamicTable objects to add to this ProcessingModule

get(name=None)

Get a NWBDataInterface from this ProcessingModule

Parameters:: name (str) – the name of the NWBDataInterface or DynamicTable
Returns:: the NWBDataInterface or DynamicTable with the given name
Return type:: NWBDataInterface or DynamicTable

namespace = 'core'

neurodata_type = 'ProcessingModule'

class pynwb.base.TimeSeries(name, data, unit, resolution=-1.0, conversion=1.0, offset=0.0, timestamps=None, starting_time=None, rate=None, comments='no comments', description='no description', control=None, control_description=None, continuity=None)[source]

Bases: NWBDataInterface

A generic base class for time series data

Create a TimeSeries object

Parameters:

name (str) – The name of this TimeSeries dataset
data (ndarray or list or tuple or Dataset or Array or StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO or TimeSeries) – The data values. The first dimension must be time. Can also store binary data, e.g., image frames
unit (str) – The base unit of measurement (should be SI unit)
resolution (float) – The smallest meaningful difference (in specified unit) between values in data
conversion (float) – Scalar to multiply each element in data to convert it to the specified unit
offset (float) – Scalar to add to each element in the data scaled by ‘conversion’ to finish converting it to the specified unit.
timestamps (ndarray or list or tuple or Dataset or Array or StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO or TimeSeries) – Timestamps for samples stored in data
starting_time (float) – The timestamp of the first sample
rate (float) – Sampling rate in Hz
comments (str) – Human-readable comments about this TimeSeries dataset
description (str) – Description of this TimeSeries dataset
control (Iterable) – Numerical labels that apply to each element in data
control_description (Iterable) – Description of each control value
continuity (str) – 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 time-point. 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”.

DEFAULT_DATA = array([], dtype=uint8)

DEFAULT_UNIT = 'unknown'

DEFAULT_RESOLUTION = -1.0

DEFAULT_CONVERSION = 1.0

DEFAULT_OFFSET = 0.0

property timestamps_unit

property interval

property starting_time: The timestamp of the first sample

property starting_time_unit

property num_samples: Tries to return the number of data samples. If this cannot be assessed, returns None.

property data

property data_link

property timestamps

property timestamp_link

property time_unit

get_timestamps()[source]: Get the timestamps of this TimeSeries. If timestamps are not stored in this TimeSeries, generate timestamps.

get_starting_time()[source]

Get the starting time of this TimeSeries in seconds.

Returns:: The starting time in seconds, or None if no starting time is defined and there is no data.
Return type:: float or None

get_duration()[source]

Get the duration of this TimeSeries in seconds.

Returns the time span from the first sample to the last sample. For a single sample or empty TimeSeries with a defined starting_time, returns 0.

Returns:: The duration in seconds, or None if the TimeSeries has no data and no starting_time defined.
Return type:: float or None

Notes

For rate-based TimeSeries: duration = (n - 1) / rate For timestamp-based TimeSeries: duration = timestamps[-1] - timestamps[0]

The duration represents the time span between sample times, not the total recording time. If you need to account for the last sample’s duration (e.g., for continuous recordings), add 1/rate manually.

get_data_in_units()[source]

Get the data of this TimeSeries in the specified unit of measurement, applying the conversion factor and offset:

\[out = data * conversion + offset\]

If the field ‘channel_conversion’ is present, the conversion factor for each channel is additionally applied to each channel:

\[out_{channel} = data * conversion * conversion_{channel} + offset\]

NOTE: This will read the entire dataset into memory.

Return type:: numpy.ndarray

property comments: Human-readable comments about this TimeSeries dataset

property continuity: 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 time-point. 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”.

property control: Numerical labels that apply to each element in data

property control_description: Description of each control value

property conversion: Scalar to multiply each element in data to convert it to the specified unit

property description: Description of this TimeSeries dataset

namespace = 'core'

neurodata_type = 'TimeSeries'

property offset: Scalar to add to each element in the data scaled by ‘conversion’ to finish converting it to the specified unit.

property rate: Sampling rate in Hz

property resolution: The smallest meaningful difference (in specified unit) between values in data

property unit: The base unit of measurement (should be SI unit)

class pynwb.base.BaseImage(name, data, description=None)[source]

Bases: NWBData, ABC

An abstract base type for image data. Parent type for Image and ExternalImage types.

Parameters:

name (str) – The name of the image
data (None) – The image data (any type) as specified by a subclass.
description (str) – Description of the image

property description: Description of the image

namespace = 'core'

neurodata_type = 'BaseImage'

class pynwb.base.Image(name, data, resolution=None, description=None)[source]

Bases: BaseImage

A base type for storing image data directly. Shape can be 2-D (x, y), or 3-D where the third dimension can have three or four elements, e.g. (x, y, (r, g, b)) or (x, y, (r, g, b, a)).

Parameters:

name (str) – The name of the image
data (ndarray or list or tuple or Dataset or Array or StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO) – Data of image. Shape can be (x, y), (x, y, 3), or (x, y, 4).
resolution (float) – pixels / cm
description (str) – Description of the image

property resolution: pixels / cm

namespace = 'core'

neurodata_type = 'Image'

class pynwb.base.ExternalImage(name, data, image_format, description=None, image_mode=None)[source]

Bases: BaseImage

A type for referencing an external image file.

Parameters:

name (str) – The name of the image
data (str) – Path or URL to the external image file.
image_format (str) – Common name of the image file format. Only widely readable, open file formats are allowed.Allowed values are “PNG”, “JPEG”, and “GIF”.
description (str) – Description of the image
image_mode (str) – Image mode (color mode) of the image, e.g., “RGB”, “RGBA”, “grayscale”, and “LA”.

property image_format: Common name of the image file format. Only widely readable, open file formats are allowed.Allowed values are “PNG”, “JPEG”, and “GIF”.

property image_mode: Image mode (color mode) of the image, e.g., “RGB”, “RGBA”, “grayscale”, and “LA”.

namespace = 'core'

neurodata_type = 'ExternalImage'

class pynwb.base.ImageReferences(name, data)[source]

Bases: NWBData

Ordered dataset of references to Image objects.

Parameters:

name (str) – The name of this ImageReferences object.
data (ndarray or list or tuple or Dataset or Array or StrDataset or HDMFDataset or AbstractDataChunkIterator) – The images in order.

namespace = 'core'

neurodata_type = 'ImageReferences'

class pynwb.base.Images(name, images=None, description='no description', order_of_images=None)[source]

Bases: MultiContainerInterface

An collection of images with an optional way to specify the order of the images using the “order_of_images” dataset. An order must be specified if the images are referenced by index, e.g., from an IndexSeries.

Parameters:

name (str) – The name of this set of images
images (ndarray or list or tuple or Dataset or Array or StrDataset or HDMFDataset or AbstractDataChunkIterator) – image objects
description (str) – description of images
order_of_images (ImageReferences) – Ordered dataset of references to BaseImage objects stored in the parent group.

__getitem__(name=None)

Get a BaseImage from this Images

Parameters:: name (str) – the name of the BaseImage
Returns:: the BaseImage with the given name
Return type:: BaseImage

add_image(images)

Add one or multiple BaseImage objects to this Images

Parameters:: images (list or tuple or dict or BaseImage) – one or multiple BaseImage objects to add to this Images

create_image(name, data, description=None)

Create a BaseImage object and add it to this Images

Parameters:

name (str) – The name of the image
data (None) – The image data (any type) as specified by a subclass.
description (str) – Description of the image

Returns:

the BaseImage object that was created

Return type:

BaseImage

property description: description of images

get_image(name=None)

Get a BaseImage from this Images

Parameters:: name (str) – the name of the BaseImage
Returns:: the BaseImage with the given name
Return type:: BaseImage

property images: a dictionary containing the BaseImage in this Images

namespace = 'core'

neurodata_type = 'Images'

property order_of_images: Ordered dataset of references to BaseImage objects stored in the parent group.

class pynwb.base.TimeSeriesReference(idx_start: int, count: int, timeseries: TimeSeries)[source]

Bases: NamedTuple

Class used to represent data values of a TimeSeriesReferenceVectorData This is a typing.NamedTuple type with predefined tuple components idx_start, count, and timeseries.

Variables:

idx_start
count
timeseries

Create new instance of TimeSeriesReference(idx_start, count, timeseries)

idx_start: int: Start index in time for the timeseries

count: int: Number of timesteps to be selected starting from idx_start

timeseries: TimeSeries: The TimeSeries object the TimeSeriesReference applies to

check_types()[source]

Helper function to check correct types for idx_start, count, and timeseries.

This function is usually used in the try/except block to check for TypeError raised by the function.

See also isvalid to check both validity of types and the reference itself.

Returns:: True if successful. If unsuccessful TypeError is raised.
Raises:: TypeError – If one of the fields does not match the expected type

isvalid()[source]

Check whether the reference is valid. Setting idx_start and count to -1 is used to indicate invalid references. This is useful to allow for missing data in TimeSeriesReferenceVectorData

Returns:

True if the selection is valid. Returns False if both idx_start and count are negative. Raises IndexError in case the indices are bad.

Raises:

IndexError – If the combination of idx_start and count are not valid for the given timeseries.
TypeError – If one of the fields does not match the expected type

property timestamps

Get the floating point timestamp offsets in seconds from the timeseries that correspond to the array. These are either loaded directly from the timeseries timestamps or calculated from the starting time and sampling rate.

Raises:

IndexError – If the combination of idx_start and count are not valid for the given timeseries.
TypeError – If one of the fields does not match the expected type

Returns:

Array with the timestamps.

property data

Get the selected data values. This is a convenience function to slice data from the timeseries based on the given idx_start and count

Raises:

IndexError – If the combination of idx_start and count are not valid for the given timeseries.
TypeError – If one of the fields does not match the expected type

Returns:

Result of self.timeseries.data[self.idx_start: (self.idx_start + self.count)]. Returns None in case the reference is invalid (i.e., if both idx_start and count are negative.

classmethod empty(timeseries)[source]

Creates an empty TimeSeriesReference object to represent missing data.

When missing data needs to be represented, NWB defines None for the complex data type (idx_start, count, TimeSeries) as (-1, -1, TimeSeries) for storage. The exact timeseries object will technically not matter since the empty reference is a way of indicating a NaN value in a TimeSeriesReferenceVectorData column.

An example where this functionality is used is IntracellularRecordingsTable where only one of stimulus or response data was recorded. In such cases, the timeseries object for the empty stimulus TimeSeriesReference could be set to the response series, or vice versa.

returns:

Returns TimeSeriesReference

Parameters:: timeseries (TimeSeries) – the timeseries object to reference.

class pynwb.base.TimeSeriesReferenceVectorData(name='timeseries', description='Column storing references to a TimeSeries (rows). For each TimeSeries this VectorData column stores the start_index and count to indicate the range in time to be selected as well as an object reference to the TimeSeries.', data=[])[source]

Bases: VectorData

Column storing references to a TimeSeries (rows). For each TimeSeries this VectorData column stores the start_index and count to indicate the range in time to be selected as well as an object reference to the TimeSeries.

Representing missing values In practice we sometimes need to be able to represent missing values, e.g., in the IntracellularRecordingsTable we have TimeSeriesReferenceVectorData to link to stimulus and response recordings, but a user can specify either only one of them or both. Since there is no None value for a complex types like (idx_start, count, TimeSeries), NWB defines None as (-1, -1, TimeSeries) for storage, i.e., if the idx_start (and count) is negative then this indicates an invalid link (in practice both idx_start and count must always either both be positive or both be negative). When selecting data via the get or __getitem__ functions, (-1, -1, TimeSeries) values are replaced by the corresponding TIME_SERIES_REFERENCE_NONE_TYPE tuple to avoid exposing NWB storage internals to the user and simplifying the use of and checking for missing values. NOTE: We can still inspect the raw data values by looking at self.data directly instead.

Variables:

TIME_SERIES_REFERENCE_TUPLE
TIME_SERIES_REFERENCE_NONE_TYPE

Parameters:

name (str) – the name of this VectorData
description (str) – a description for this column
data (ndarray or list or tuple or Dataset or Array or StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO) – a dataset where the first dimension is a concatenation of multiple vectors

TIME_SERIES_REFERENCE_TUPLE

Return type when calling get or __getitem__

alias of TimeSeriesReference

TIME_SERIES_REFERENCE_NONE_TYPE = (None, None, None): Tuple used to represent None values when calling get or __getitem__. See also TIME_SERIES_REFERENCE_TUPLE

namespace = 'core'

neurodata_type = 'TimeSeriesReferenceVectorData'

add_row(val)[source]

Append a data value to this column.

Parameters:: val (TimeSeriesReference or tuple) – the value to add to this column. If this is a regular tuple then it must be convertible to a TimeSeriesReference

append(arg)[source]

Append a data value to this column.

Parameters:: arg (TimeSeriesReference or tuple) – the value to append to this column. If this is a regular tuple then it must be convertible to a TimeSeriesReference

get(key, **kwargs)[source]

Retrieve elements from this object.

The function uses TIME_SERIES_REFERENCE_TUPLE to describe individual records in the dataset. This allows the code to avoid exposing internal details of the schema to the user and simplifies handling of missing values by explicitly representing missing values via TIME_SERIES_REFERENCE_NONE_TYPE rather than the internal representation used for storage of (-1, -1, TimeSeries).

Parameters:

key – Selection of the elements
kwargs – Ignored

Returns:

TIME_SERIES_REFERENCE_TUPLE if a single element is being selected. Otherwise return a list of TIME_SERIES_REFERENCE_TUPLE objects. Missing values are represented by TIME_SERIES_REFERENCE_NONE_TYPE in which all values (i.e., idx_start, count, timeseries) are set to None.