Skip to content

Standards on Neurodata Without Borders files

Version

0.1.0-draft

Introduction

Neurodata Without Borders (NWB) files are a standard file format for neurophysiology data, however there are many topics where NWB is not opinionated. This documents defines AIND's opinions.

Basics

We also take this opportunity to remind readers about some general NWB basics:

  • Raw data goes in the acquisition group
  • Processed data goes in the processing group
  • The root level session_start_time is a timezone-aware datetime defining the start of acquisition.
  • All timestamps must be relative to the same point in time and require no additional alignment to compare. This is defined in the root level timestamps_reference_time, which defaults to session_start_time.
  • It is not required that timestamps for different data streams be identical (i.e. resample data such that all timeseries have exactly the same timestamps).

HARP

  • At AIND, if there is a HARP board available, timestamps must utilize HARP TTLs to transform timestamps to a common timebase. It is insufficient to store a lookup table.
  • If it is necessary to preserve the original, misaligned timestamps for a timeseries, they can be stored separately in an appropriately named DynamicTable, e.g. ephys_temporal_alignment with an original_timestamps column.

Events

  • Any events should be packaged using the ndx-events NWB extension.
  • We represent all discrete events in a single a EventTable named events.
  • Events in the events table have a timestamp property, along with arbitrary property names (columns) and values.
  • All event property values and their descriptions are stored in single a MeaningsTable table named event_descriptions (e.g. property name "lick" with value "0" means "the mouse licked the left water port").
  • All event property values must be described by HED tags or part of AIND's HED extension.
  • Trials are represented as events, but also fill in the event duration property.
  • Continuous data (e.g. running wheel velocity) are stored in TimeSeries arrays, not event tables.

Application Notes

BIDS and HED have defined two file formats that can generically describe events in a task-agnostic fashion.

First, events.csv, which describes individual events: 

| onset  | duration | HED | <additional columns> | ... |
--------------------------------------------------
| float  | float    | str | ...                  | ... |

Second, event-descriptions.csv, which describes event types and their values: 

| column_name | column_value | description | HED |
--------------------------------------------------
| str         | Any          | str         | str |

BIDS likewise has a standard JSON representations of event descriptions.

A general-purpose, task-agnostic utility for could write this in to NWB without any custom code necessary (for example).

Relationship to aind-data-schema

The AIND HED extension will likely live in the aind-data-schema-models repository.

File Quality Assurances

None.