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

__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.

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 timestamps
property time_unit
get_timestamps()[source]

Get the timestamps of this TimeSeries. If timestamps are not stored in this TimeSeries, generate timestamps.

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.

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.Image(name, data, resolution=None, description=None)[source]

Bases: NWBData

Abstract image class. It is recommended to instead use pynwb.image.GrayscaleImage or pynwb.image.RGPImage where appropriate.

Parameters:
namespace = 'core'
neurodata_type = 'Image'
class pynwb.base.ImageReferences(name, data)[source]

Bases: NWBData

Ordered dataset of references to Image objects.

Parameters:
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:
__getitem__(name=None)

Get an Image from this Images

Parameters:

name (str) – the name of the Image

Returns:

the Image with the given name

Return type:

Image

add_image(images)

Add one or multiple Image objects to this Images

Parameters:

images (list or tuple or dict or Image) – one or multiple Image objects to add to this Images

create_image(name, data, resolution=None, description=None)

Create an Image object and add it to this Images

Parameters:
Returns:

the Image object that was created

Return type:

Image

property description

description of images

get_image(name=None)

Get an Image from this Images

Parameters:

name (str) – the name of the Image

Returns:

the Image with the given name

Return type:

Image

property images

a dictionary containing the Image in this Images

namespace = 'core'
neurodata_type = 'Images'
property order_of_images

Ordered dataset of references to Image 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:
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.