Best Practices

The goal of the following document is to provide users of the NWB standard with additional guidelines on common best practices to facilitate consistent use of the standard and help avoid common problems and most effectively leverage the NWB data standard and its ecosystem of software tools.

To enable NWB to accommodate the needs of the diverse neuroscience community, NWB provides a great degree of flexibility. In particular, the number of instances of a particular neurodata_type and corresponding names are often not fixed, to enable, e.g., storage of data from arbitrary numbers of devices within the same file. While this flexibility is essential to enable coverage of a broad range of use-cases, it can also lead to ambiguity. At the same time, we ultimately have the desire to have the schema as strict-as-possible to provide users and tool builders with a consistent organization of data. As such, we need to strike a fine balance between flexibility to enable support for varying experiments and use-cases and strictness in the schema to enforce standard organization of data. The following “best practices” provide advice from developers and experienced users that outline some of the pitfalls to avoid and common usage patterns to emulate.

Authors: Oliver Ruebel, Andrew Tritt, Ryan Ly, Cody Baker and Ben Dichter

• General
  • Neurodata Types
• NWBFile Metadata
  • File Extensions
  • File Organization
  • File Metadata
  • Subject
• Time Series
  • Data Orientation
  • Units of Measurement
  • Time Series: Time References
  • Subtypes
  • Breaks in Continuity
  • Timestamps without NaNs
  • Timestamps vs. Start & Rate
  • Avoid Negative Timestamps
  • Chunk Data
  • Compress Data
  • Unknown Resolution
  • Zero Rate
  • Positive Rate
• Tables
  • Table Values
  • Empty Tables
  • Tables With Only a Single Row
  • Tables With an Entire Column as NaN
  • Table Region Data
  • Boolean Columns
  • Timing Columns
  • Unique ids
• Behavior
  • SpatialSeries
• Extracellular electrophysiology
  • Electrodes
  • Units Table
  • ElectricalSeries
• Optical physiology
  • Plane Segmentation
  • ImagingPlane
• Intracellular electrophysiology
  • IntracellularElectrode
• Optogenetics
  • OptogeneticSeries
• ImageSeries
  • Storage of ImageSeries
• Images
  • Storage of Images
• Simulated Data
• Extensions
  • Define new neurodata_types at the top-level (do not nest type definitions)
  • Build on and reuse existing neurodata types
  • Strive for backward compatible changes
  • Provide documentation
  • Write the specification to the NWBFile
  • Use Attributes for small metadata related to a particular data object (Group or Dataset)
  • Link data to relevant metadata
  • Best practices for object names
  • Best practices for naming neurodata_types
  • Limit flexibility: Consider data reuse and tool developers
  • Use the ndx-template to create new extensions
  • Get the community involved