Core NWB procedures

NWB files are created and managed through an NWB object. Several parameters are provided to the NWB constructor describing things about the file, and the NWB functions and procedures are used to manipulate the file.

nwb.create_identifier(base_string)

Creates an identifying string for the file, hopefully unique in and between labs, based on the supplied base string, the NWB file version, and the time the file was created. The base string should contain the name of the lab, experimenter and project, or some other string that is unique to a given lab

class nwb.NWB(**vargs)

Represents an NWB file. Calling the NWB constructor creates the file. The following arguments are recognized:

filename (text – mandatory) The name of the to-be-created file

identifier (text – mandatory) A unique identifier for the file, to differentiate it from all other files (even in other labs). A suggested way to create the identifier is to use a lab-specific string and send it to nwb.create_identifier(string). This function returns the supplied string appended by the present date

description (text – mandatory) A one or two sentence description of the experiment and what the data in the file represents

start_time (text – optional) This is the starting time of the experiment. If this isn’t provided, the start time of the experiment will default to the time that the file is created

modify (boolean – optional) Opens the file in append mode if the file exists. If the file exists and this flag (or ‘overwrite’) is not set, an error occurs (to prevent accidentally overwriting or modifying an existing file)

overwrite (boolean – optional) If the specified file exists, it will be overwritten

keep_original (boolean – optional) – If true, a back-up copy of the original file will be kept, named ‘<filename>.prev’

auto_compress (boolean – optional) Data is compressed automatically through the API. Setting ‘auto_compress=False’ disables this behavior

custom_spec (text – optional) A json, yaml or toml file used to customize the format specification (pyyaml or toml must be installed to use those formats)

close()

Finishes and closes an NWB file. This includes writing pending data to disk and adding annotations. NOTE: this procedure must be called to produce a valid NWB file

Arguments:

None

Returns:

Nothing

create_epoch(name, start, stop)

Creates a new Epoch object. Epochs are used to track intervals in an experiment, such as exposure to a certain type of stimuli (an interval where orientation gratings are shown, or of sparse noise) or a different paradigm (a rat exploring an enclosure versus sleeping between explorations)

Arguments:

name (text) The name of the epoch, as it will appear in the file

start (float) The starting time of the epoch

stop (float) The ending time of the epoch

Returns:

Epoch object

create_module(name)

Creates a Module object of the specified name. Interfaces can be created by the module and will be stored inside it

Arguments:

name (text) Name of the module as it will appear in the file (under /processing/)

Returns:

Module object

create_reference_image(stream, name, fmt, desc, dtype=None)

Adds documentation image (or movie) to file. This is stored in /acquisition/images/.

Args:

stream (binary) Data stream of image (eg, binary contents of .png image)

name (text) Name that image will be stored as

fmt (text) Format of the image (eg, “png”, “avi”)

desc (text) Descriptive text describing the image

dtype (text) Optional field specifying the h5py datatype to use to store stream

Returns:

nothing

create_timeseries(ts_type, name, modality='other')

Creates a new TimeSeries object. Timeseries are used to store and associate data or events with the time the data/events occur.

Arguments:

ts_type (text) The type of timeseries to be created. Default options are:

TimeSeries – simple time series

AbstractFeatureSeries – features of a presented stimulus. This is particularly useful when storing the raw stimulus is impractical and only certain features of the stimulus are salient. An example is the visual stimulus of orientation gratings, where the phase, spatial/temporal frequency and contrast are relevant, but the individual video frames are impractical to store, and not as useful

AnnotationSeries – stores strings that annotate events or actions, plus the time the annotation was made

ElectricalSeries – Voltage acquired during extracellular recordings

ImageSeries – storage object for 2D image data. An ImageSeries can represent image data within the file or can point to an image stack in an external file (eg, png or tiff)

IndexSeries – series that is composed of samples in an existing time series, for example images that are pulled from an image stack in random order

ImageMaskSeries – a mask that is applied to a visual stimulus

IntervalSeries – a list of starting and stop times of events

OpticalSeries – a series of image frames, such as for video stimulus or optical recording

OptogeneticSeries – optical stimulus applied during an optogentic experiment

RoiResponseSeries – responses of a region-of-interest during optical recordings, such as florescence or dF/F

SpatialSeries – storage of points in space over time

SpikeEventSeries – snapshots of spikes events in an extracellular recording

TwoPhotonSeries – Image stack recorded from a 2-photon microscope

VoltageClampSeries, CurrentClampSeries – current or voltage recurded during a patch clamp experiment

VoltageClampStimulusSeries, CurrentClampStimulusSeries – voltage or current used as stimulus during a patch clamp experiment

WidefieldSeries – Image stack recorded from wide-field imaging

name (text) the name of the TimeSeries, as it will appear in the file

modality (text) this indicates where in the file the TimeSeries will be stored. Values are:

‘acquisition’ – acquired data stored under /acquisition/timeseries

‘stimulus’ – stimulus data stored under /stimulus/presentations

‘template’ – a template for a stimulus, useful if a stimulus will be repeated as it only has to be stored once

‘other’ (DEFAULT) – TimeSeries is to be used in a module, in which case the module will manage its placement, or it’s up to the user where to place it

Returns:

TimeSeries object

set_metadata(key, value, **attrs)

Creates a field under /general/ and stores the specified information there. NOTE: using the constants defined in nwbco.py is strongly encouraged, as this will help prevent accidental typos and will not require the user to remember where a particular piece of data is to be stored

Arguments:

key (text) Name of the metadata field. Please use the constants and functions defined in nwbco.py

value Value of the data to be stored. This will be text in most cases

attrs (dictionary, or key/value pairs) Attributes that will be created on the metadata field

Returns:

nothing

set_metadata_from_file(key, filename, **attrs)

Creates a field under /general/ and stores the contents of the specified file in that field NOTE: using the constants defined in nwbco.py is strongly encouraged, as this will help prevent accidental typos and will not require the user to remember where a particular piece of data is to be stored

Arguments:

key (text) Name of the metadata field. Please use the constants and functions defined in nwbco.py

filename (text) Name of file containing the data to be stored

attrs (dictionary, or key/value pairs) Attributes that will be created on the metadata field

Returns:

nothing