Modules are separate groups stored in the root ‘processing/’ group. Modules are designed to store the results of intermediate data processing that is required before scientific analysis can be performed on experimental data (e.g., spike sorting or image segmentation). Each module publishes one or more ‘interfaces’, which are units that present a specific aspect of the data. For example, the Clustering interface provides the time of an event with its cluster number. See the standard documentation for a description of each interface and a list of what data each interface publishes.
Many interfaces share the same API, while some more complex interfaces require additional functions and procedures. Each interface is described below, followed by the API.
BehavioralEvents
BehavioralEpochs
BehavioralTimeSeries
The objective of these interfaces is to provide generic hooks for software tools/scripts. This allows a tool/script to take the output one specific interface (e.g., UnitTimes) and plot that data relative to another modality data (e.g., behavioral events) without having to define all possible modalities in advance. Declaring one of these interfaces means that one or more TimeSeries of the specified type is published. These TimeSeries should reside in a folder having the same name as the interface. For example, if a BehavioralTimeSeries interface is declared, the module will have one or more TimeSeries defined in the module sub-folder “BehavioralTimeSeries”. BehavioralEpochs should use IntervalSeries. BehavioralEvents is used for irregular events. BehavioralTimeSeries is for continuous data.
Clustering
Clustered spike data, whether from automatic clustering tools (e.g., klustakwik) or as a result of manual sorting. A Clustering module publishes the following datasets:
| Name | API call to set | Description |
|---|---|---|
| times, number, peak_over_rms | set_clusters() ...) | Convenience function to set fields ‘num’, ‘times’ and peak_over_rms (see API description below) |
| description (text) | set_value(“description”, ...) | Description of clusters or clustering (e.g., cluster 0 is electrical noise, clusters curated using Klusters, etc) |
ClusterWaveforms
The mean waveform shape, including standard deviation, of the different clusters. Ideally, the waveform analysis should be performed on data that is only high-pass filtered. This is a separate module because it is expected to require updating. For example, IMEC probes may require different storage requirements to store/display mean waveforms, requiring a new interface or an extension of this one. A ClusterWaveform module publishes the following datasets:
| Name | API call to set | Description |
|---|---|---|
| waveform_mean (float array) | set_value(“waveform_mean”, ...) | The mean waveform for each cluster, using the same indices for each wave as cluster numbers in the associated Clustering module (i.e, cluster 3 is in array slot [3]). Waveforms corresponding to gaps in cluster sequence should be empty (e.g., zero-filled) |
| waveform_sd (float array) | set_value(“waveform_sd”, ...) | Times of events that features correspond to (can be a link). Array structure: [# events] |
| waveform_filtering (text) | set_value(“waveform_filtering” , ...) | Filtering applied to data before generating mean/sd |
| clustering_interface (Clustering object or text path) | set_value_as_link( “clustering_interface”, ...) | HDF5 link to Clustering interface that was the source of the clustered data |
CompassDirection
With a CompassDirection interface, a module publish one or more SpatialSeries objects that store a floating point value for theta. The SpatialSeries::reference_frame field should indicate what direction corresponds to “0” and which is the direction of rotation (this should be “clockwise”). The si_unit for the SpatialSeries should be “radians” or “degrees”.
DfOverF
dF/F information about a region of interest (ROI). Each DfOverF interface publishes one or more RoiResponseSeries. Storage hierarchy of dF/F should be the same as for segmentation (ie, same names for ROIs and for image planes).
EventDetection
Detected spike events from voltage trace(s).
| Name | API call to set | Description |
|---|---|---|
| times (double array) | set_value(“times”, ...) or set_value_as_link(“times”,...) | Times of events that features correspond to (can be a link). Array structure: [# events] |
| detection_method (text) | set_value(“detection_method”, ...) | Description of how events were detected, such as voltage or dV/dT threshold, plus relevant values |
| source_electricalseries (TimeSeries object or text path) | set_value_as_link(” source_electricalseries”, ...) | HDF5 link to TimeSeries that this data was calculated from. Metadata about electrodes and their position can be read from that TimeSeries so necessary to store that information here |
EventWaveform
Represents either the waveforms of detected events, as extracted from a raw data trace in /acquisition, or the event waveforms that were stored during experiment acquisition. Each EventWaveform interface publishes one or more SpikeEventSeries.
EyeTracking
Eye-tracking data. Each interface publishes one or more SpatialSeries that store direction of gaze.
FeatureExtraction Features, such as PC1 and PC2, that are extracted from signals stored in a SpikeEvent TimeSeries or other source.
| Name | API call to set | Description |
|---|---|---|
| features (float array) | set_value(“features”, ...) | Array of features extracted for each event Array structure: [# events][# channels] [# features] |
| times (double array) | set_value(“times”, ...) or set_value_as_link(“times”,...) | Times of events that features correspond to (can be a link). Array structure: [# events] |
| description (text array) | set_value(“description”, ...) | Description of features (eg, “PC1”) for each of the extracted features. Array structure: [# features] |
| electrode_idx (int array) | set_value(“electrode_idx”, ...) | Indices to electrodes described in the experiment’s electrode map array in general/extracellular_ephys. Array structure: [# channels] |
FilteredEphys
Ephys data from one or more channels that has been subjected to filtering. Examples of filtered data include Theta and Gamma (LFP has its own interface). FilteredEphys modules publish an ElectricalSeries for each filtered channel or set of channels. The name of each ElectricalSeries is arbitrary but should be informative. The source of the filtered data, whether this is from analysis of another time series or as acquired by hardware, should be noted in each’s TimeSeries::description field. There is no assumed 1::1 correspondence between filtered ephys signals and electrodes, as a single signal can apply to many nearby electrodes, and one electrode may have different filtered (e.g., theta and/or gamma) signals represented. Each interface hase one or more ElectricalSeries.
Fluorescence
Fluorescence information about a region of interest (ROI). Each Fluorescence interface has one or more RoiResponseSeries. Storage hierarchy of fluorescence should be the same as for segmentation (ie, same names for ROIs and for image planes).
ImageSegmentation
Stores pixels in an image that represent different regions of interest (ROIs). Pixels are stored in both lists and 2D maps representing image intensity. All segmentation data is stored in a “segmentation” subfolder. Each ROI is stored in its own subfolder within ImageSegmentation, with the ROI folder containing both a 2D mask and a list of pixels that make up this mask. Also for masking neuropil. If segmentation is allowed to change with time, a new interface is required (e.g., use the former version of this one, with img_mask_0 and start_time_0).
| Name | API call to set | Description |
|---|---|---|
| img_mask, pix_mask, roi_description | add_roi_mask_img() or add_roi_mask_pixels() | Creates the definition of a region of interest |
| reference_image | add_reference_image() or add_reference_image_as_link() | Adds a reference image that ROIs are based on |
| imaging_plane | create_imaging_plane() | Creates space to store data from one imaging plane |
LFP
LFP data from one or more channels. Each LFP interface has one or more ElectricalSeries. The electrode map in each published ElectricalSeries will identify which channels are providing LFP data. Filter properties should be noted in the ElectricalSeries description or comments field.
MotionCorrection
Publishes an image stack where all frames are shifted (registered) to a common coordinate system, to account for movement and drift between frames.
| Name | API call to set | Description |
|---|---|---|
| original, corrected images; xy_translation | add_corrected_image() | Adds a motion-corrected image to the interface |
Position
Position data, whether along the x, x/y or x/y/z axis. Each interface stores one or more SpatialSeries storing position.
PupilTracking
Eye-tracking data. Each PupilTracking interface has one or more TimeSeries storing pupil size.
UnitTimes
Event times in observed units (eg, cell, synapse, etc). The UnitTimes folder contains a folder for each unit. Name of the folder should match value in source module, if that is possible/relevant (e.g., name of ROIs from Segmentation module).
| Name | API call to set | Description |
|---|---|---|
| times, description and source | add_unit() | Defines a unit, including event times and description |
Processing module. This is a container for one or more interfaces that provide data at intermediate levels of analysis
Modules should be created through calls to NWB.create_module(). They should not be instantiated directly
Creates an interface within the module. Each module can have multiple interfaces. Standard interface options are:
BehavioralEpochs – general container for storing and publishing intervals (IntervalSeries)
BehavioralEvents – general container for storing and publishing event series (TimeSeries)
BehavioralTimeSeries – general container for storing and publishing time series (TimeSeries)
Clustering – clustered spike data, whether from automatic clustering tools or as a result of manual sorting
ClusterWaveform – mean event waveform of clustered data
CompassDirection – publishes 1+ SpatialSeries storing direction in degrees (or radians)
DfOverF – publishes 1+ RoiResponseSeries showing dF/F in observed ROIs
EventDetection – information about detected events
EventWaveform – publishes 1+ SpikeEventSeries of extracellularly recorded spike events
EyeTracking – publishes 1+ SpatialSeries storing direction of gaze
FeatureExtraction – salient features of events
FilteredEphys – publishes 1+ ElectricalSeries storing data from digital filtering
Fluorescence – publishes 1+ RoiResponseSeries showing fluorescence of observed ROIs
ImageSegmentation – publishes groups of pixels that represent regions of interest in an image
LFP – a special case of FilteredEphys, filtered and downsampled for LFP signal
MotionCorrection – publishes image stacks whos frames have been corrected to account for motion
Position – publishes 1+ SpatialSeries storing physical position. This can be along x, xy or xyz axes
PupilTracking – publishes 1+ standard TimeSeries that stores pupil size
UnitTimes – published data about the time(s) spikes were detected in an observed unit
Completes the module and writes changes to disk.
Returns HDF5 path of module
Set description field in module
Adds a custom key-value pair (ie, dataset) to the root of the module.
key (string) A unique identifier within the TimeSeries
value (any) The value associated with this key
attrs (dict) Dictionary of key-value pairs to be stored as attributes
Interfaces represent particular processing tasks and they publish (ie, make available) specific types of data. Each is required to supply a minimum of specifically named data, but all can store data beyond this minimum
Interfaces should be created through Module.create_interface(). They should not be created directly
Adds a TimeSeries to the interface, setting the storage path of the TimeSeries. When a TimeSeries is added to an interface, the interface manages storage and finalization of it
Add a previously-defined TimeSeries to the interface. It will be added as an HDF5 link
ts_name (text) name of time series as it will appear in the interface
path (text) path to the time series
Finish off the interface and write pending operations to disk
Returns HDF5 path to this interface
Identify source(s) for the data provided in the module. This can be one or more other modules, or time series in acquisition or stimulus
Adds a custom key-value pair (ie, dataset) to the interface
key (string) A unique identifier within the TimeSeries
value (any) The value associated with this key
Create a link to another NWB object
key (text) Name of link as it will appear in TimeSeries
value (text, TimeSeries or Interface) The object to be linked to, or the path to that object
Conveninece function to set interface values. Includes sanity checks for array lengths
times (double array) Times of clustered events, in seconds. This may be a link to times field in associated FeatureExtraction module. Array structure: [num events]
num (int array) Cluster number for each event Array structure: [num events]
description (text) Description of clusters or clustering (e.g., cluster 0 is electrical noise, clusters curated using Klusters, etc)
peak_over_rms (float array) Maximum ratio of waveform peak to RMS on any channel in the cluster (provides a basic clustering metric). Array structure: [num clusters]
Add a reference image to the segmentation interface
plane (text) name of imaging plane
name (text) name of reference image
img (byte array) raw pixel map of image, 8-bit grayscale
Adds an ROI to the module, with the ROI defined within a 2D image.
image_plane (text) name of imaging plane
roi_name (text) name of ROI
desc (text) description of ROI
img (2D float array) description of ROI in a pixel map (float[y][x])
Adds an ROI to the module, with the ROI defined using a list of pixels.
image_plane (text) name of imaging plane
roi_name (text) name of ROI
desc (text) description of ROI
pixel_list (2D int array) array of [x,y] pixel values
weights (float array) array of pixel weights
width (int) width of reference image, in pixels
height (int) height of reference image, in pixels
Defines imaging manifold. This can be a simple 1D or 2D manifold, a complex 3D manifold, or even random access. The manifold defines the spatial coordinates for each pixel. If multi-planar manifolds are to be defined separately, a separate imaging plane should be used for each. Non-planar manifolds should be stored as a vector.
Pixels in the manifold must have a 1:1 correspondence with image segmentation masks and the masks and manifold must have the same dimensions.
Adds a motion-corrected image to the module, including the original image stack, the x,y delta necessary to shift the image frames for registration, and the corrected image stack. NOTE 1: All 3 timeseries use the same timestamps and so can share/ link timestamp arrays
NOTE 2: The timeseries passed in as ‘xy_translation’ and ‘corrected’ will be renamed to these names, if they are not links to existing timeseries
NOTE 3: The timeseries arguments can be either TimeSeries objects (new or old in case of latter 2 args) or strings. If they are new TimeSeries objects, they will be stored within the module. If they are existing objects, a link to those objects will be created
orig (ImageSeries or text) ImageSeries object or text path to original image time series
xy_translation TimeSeries storing displacements of x and y direction in the data[] field
corrected Motion-corrected ImageSeries
Adds data about a unit to the module, including unit name, description and times.
unit_name (text) Name of the unit, as it will appear in the file
unit_times (double array) Times that the unit spiked
description (text) Information about the unit
source (text) Name, path or description of where unit times originated
Add auxiliary information (key-value) about a unit. Data will be stored in the folder that contains data about that unit.
unit_name (text) Name of unit, as it appears in the file
key (text) Key under which the data is added
value (any) Data to be added
Extended (subclassed) finalize procedure. It creates and stores a list of all units in the module and then calls the superclass finalizer.