NWBFile Metadata

An NWBFile object generally contains data from a single experimental session.

File Extensions

NWB file paths should contain .nwb in their file extension to indicate that they are NWB files. To further help tools and users quickly identify the underlying backend type, an additional option is to attach the backend as a second suffix. Recommended file extensions are:

  1. .nwb (minimum recommendation)

  2. .nwb.h5 (also acceptable for NWB HDF5 files)

  3. .nwb.zarr (also acceptable for NWB Zarr stores)

Check function: check_file_extension()

File Organization

Global Date and Time Reference

An NWBFile can have two primary time references. The global date and time reference for all objects in the NWBFile is the timestamps_reference_time. By default, this is set to the session_start_time, but when writing multiple NWBFiles that are all designed to align to the same time reference, the timestamp_reference_time used across all of the NWBFiles may be set separately from the session_start_time.

All time-related data in the NWBFile should be synchronized to the timestamps_reference_time so that future users are able to understand the timing of all events contained within the NWBFile.

The timestamps_reference_time should also be the earliest timestamp in the file, giving all other time references a positive value relative to that. There should be no time references which are negative.

Given the importance of this field within an NWBFile, is it critical that it be set to a proper value. Default values should generally not be used for this field. If the true date is unknown, use your best guess. If the exact start time is unknown, then it is fine to simply set it to midnight on that date.

Check functions: check_session_start_time_old_date(), check_session_start_time_future_date(), check_table_time_columns_are_not_negative()

Acquisition & Processing

The ‘acquisition’ group is specifically for time series measurements that are acquired from an acquisition system, e.g., an ElectricalSeries with the voltages from the recording systems or the raw output of any other environmental sensors.

The ‘processing’ modules are for intermediate data, e.g., if you derive the position of the animal from sensors or video tracking, that would go in /processing/behavior/Position/SpatialSeries. An LFP signal that is a downsampled version of the acquired data would go in /processing/ecephys/LFP/ElectricalSeries.

It may not always be 100% clear whether data is acquired or derived, so in those cases you should just use your best judgement.

Processing Module Names

The name of any given processing module should be chosen from the following types: “ophys”, “ecephys”, “icephys”, “behavior”, “ogen”, “retinotopy”, or “misc”. This helps standardize navigation of NWBFiles generated from labs and modalities. It also helps distinguish components of a given experiment, such as decoupling the intermediate data from neural acquisition systems from behavioral ones.

Check function: check_processing_module_name()

File Metadata

Session ID

An NWBFile has two distinct places for identifiers: NWBFile.session_id and identifier. The session_id field marks unique experimental sessions. The session_id should have a one-to-one relationship with a recording session. Sometimes you may find yourself having multiple NWBFiles that correspond to the same session. This can happen, for instance, if you separate out processing steps across multiple files or if you want to compare different processing outputs. In this case, the session_id should be the same for each file. Each lab should follow a standard structure for their own naming schemes so that sessions are unique within the lab and the IDs are easily human-readable.

The session_id should not contain slash characters (/) as these can cause problems when constructing paths in the DANDI archive. If your session IDs normally include slash characters, consider replacing them with hyphens (-) or underscores (_).

Check function: check_session_id_no_slashes()

Identifier

The identifier tag should be a globally unique value for the NWBFile. Two different NWBFiles from the same session should have different identifier values if they differ in any way. It is recommended that you use a well-established algorithmic generator such as uuid to ensure uniqueness. uuid can be used in PyNWB, and MatNWB will automatically set the field using java.util.UUID.randomUUID().toString(). The identifier field does not need to be easily human-readable.

Experimenter

The experimenter field of an NWBFile should be specified as any of the accepted forms: ‘LastName, Firstname’, ‘LastName, FirstName MiddleInitial.’ or ‘LastName, FirstName MiddleName’.

Check functions: check_experimenter_exists() and check_experimenter_form()

Experiment Description

The experiment_description field of an NWBFile should be specified. This helps provide context for understanding the contents of the file.

Check function: check_experiment_description()

Institution

The institution field should be specified. This allows metadata collection programs, such as those on the DANDI archive to easily scan NWBFiles to deliver summary statistics.

Check function: check_institution()

Keywords

The keywords field should be specified. This allows metadata collection programs, such as those on the DANDI archive to easily scan NWBFiles to enhance keyword-based search functionality. Try to think of what combination of words might make your file(s) unique or descriptive to help users trying to search for it. This could include the general modality or approach, the general region of cortex you wanted to study, or the type of neural data properties you were examining. Some examples are "neuropixel", "hippocampus", "lateral septum", "waveforms", "cell types", "granule cells", etc.

If you are unsure of what keywords to use, try searching existing datasets on the DANDI archive for an approach similar to yours and try to align your own keywords to that while adding a couple that make your file(s) distinguishable.

Subject

It is recommended to always include as many details about the experimental subject as possible. If the data is simulated, a simple ID of “simulated_subject” would be sufficient.

Check function: check_subject_exists()

Subject ID

A subject_id is required for upload to the DANDI archive. Even if the goal of a given NWBFile is not intended for DANDI upload, if the Subject is specified at all it should be given a subject_id for reference.

In the special case of in vitro studies where the ‘subject’ of scientific interest was not a tissue sample obtained from a living subject but was instead a purified protein, this will be annotated by prepending the keyphrase “protein” to the subject ID; e.g, “proteinCaMPARI3”. In the case where the in vitro experiment is performed on an extracted or cultured biological sample, the other subject attributes (such as age and sex) should be specified as their values at the time the sample was collected.

Similar to session IDs, the subject_id should not contain slash characters (/) as these can cause problems when constructing paths in the DANDI archive. If your subject IDs normally include slash characters, consider replacing them with hyphens (-) or underscores (_).

Check functions: check_subject_id_exists() and check_subject_id_no_slashes()

Subject Sex

The sex of the Subject should be specified as a single upper-case character among the following four possibilities: “M” (male), “F” (female), “U” (unknown), or “O” (other, for asexual species).

  1. elegans are an exception to this rule. For C. elegans, the sex should either be “XO” (male) or “XX” (hermaphrodite).

Check function: check_subject_sex()

Subject Species

The species of a Subject should be set to the proper Latin binomial or otherwise a full link to the Term IRI for the NCBI Taxonomy, which can be easily found at the Ontobee database. E.g., a rat would be “Rattus norvegicus” or “http://purl.obolibrary.org/obo/NCBITaxon_10116”.

Check function: check_subject_species_form()

Subject Strain

The strain of a Subject should be set to further indicate the subspecies or breed or common genetic modification. E.g., common strains for species “Rattus norvegicus” might include “Long Evans”, “Sprague-Dawley”, “Wistar”, or “C57BL/6”. If no specific strain is used, then simply indicate “Wild Type”.

Subject Weight

The weight of a Subject should follow the form ‘[numeric] [unit]’, e.g. ‘2.3 kg’. The weight should include a numeric value followed by a space and a unit string. Without a unit, the weight is ambiguous. The unit should follow standard SI unit conventions (see The International System of Units, 9th edition), e.g. ‘kg’ for kilograms, ‘g’ for grams, ‘mg’ for milligrams, etc. The unit should be one of: ‘kg’, ‘g’, ‘mg’, ‘ug’, ‘μg’, ‘ng’, ‘pg’.

Check function: check_subject_weight()

Subject Age

The age of a Subject should use the ISO 8601 Duration format. For instance indicating an age of 90 days would be ‘P90D’. It is not necessary to include both age and date_of_birth, but at least one of them is required by the DANDI Archive and recommended in general.

If the precise age is unknown, an age range can be given by “[lower bound]/[upper bound]” e.g. “P10D/P20D” would mean that the age is in between 10 and 20 days. If only the lower bound is known, then including only the slash after that lower bound can be used to indicate a missing bound. For instance, “P90Y/” would indicate that the age is 90 years or older.

The age is measured relative to a reference point, controlled by the age__reference field of the Subject. The only supported values are "birth" (the default) and "gestational". Use "gestational" when the age is measured from conception rather than from birth, as is common for embryonic or prenatal preparations.

Check functions: check_subject_age() and check_subject_age_reference()

Date of Birth

The date_of_birth of a Subject should use the ISO 8601 format. For instance, indicating 30 minutes after noon on April 5th, 2007 would be “2007-04-05T12:30”. It is not necessary to include both age and date_of_birth, but at least one of them is recommended.