Extracellular electrophysiology

Electrodes

Location

The location column of the ElectrodeTable should reflect your best estimate of the recorded brain area. Different labs have different standards for electrode localization. Some use atlases and coordinate maps to precisely place an electrode, and use physiological measures to confirm its placement. Others use histology or imaging processing algorithms to identify regions after-the-fact. You fill this column with localization results from your most accurate method. For instance, if you target electrodes using physiology, and later use histology to confirm placement, we would recommend that you add a new column to the electrodes table called ‘location_target’, set those values to the original intended target, and alter the values of ‘location’ to match the histology results.

The location column of the ElectrodeTable is required. If you do not know the location of an electrode, use “unknown”.

Ontologies

It is preferable to use established ontologies instead of lab conventions for indicating anatomical region. We recommend the Allen Brain Atlas terms for mice, and you may use either the full name or the abbreviation (do not make up your own terms).

Check function: check_electrodes_location_allen_ccf()

Anatomical Coordinates

The x, y, and z columns of the ElectrodeTable are for the precise anatomical coordinates within the Subject. For mice, use the Allen Institute Common Coordinate Framework v3, which follows the convention (+x = posterior, +y = inferior, +z = subject’s right).

Relative Coordinates

For relative position of an electrode on a probe, use rel_x, rel_y, and rel_z columns of the ElectrodeTable. These positions will be used by spike sorting software to determine electrodes that are close enough to share a neuron.

Avoid Duplication of Metadata

The ElectrodeTable should not contain redundant information that is present somewhere else within the NWBFile . Avoid adding columns to the ElectrodeTable that correspond to properties of the ElectricalSeries such as unit, offsets or channel gains These properties should be stored in the corresponding attributes of the ElectricalSeries object.

As a concrete example, the package objects from the SpikeInterface package contain two properties named gain_to_uv and offset_to_uv that are used to convert the raw data to microvolts. These properties should not be stored in the ElectrodeTable but rather in the ElectricalSeries object as channel_conversion and offset respectively.

Units Table

The Units Table contains information about the identified units (putative neurons) from extracellular electrophysiology data.

Spike Times Column Required

The spike_times column is the core data of the Units table. A Units table without spike_times is almost certainly an error or a misuse of the neurodata type — for example, storing only cluster labels or quality metrics without the underlying spike data that gives them meaning. Always include spike_times when creating a Units table.

Check function: check_units_table_has_spikes()

Duration

The spikes associated with each unit are stored in the spike_times column of the table in seconds.

Check function: check_units_table_duration()

Units Resolution

The resolution field on the Units table indicates the smallest possible difference between two spike times, in seconds. Set this to 1/sampling_rate of the recording system (e.g., resolution=1/30000 for a 30 kHz system). This documents the precision of your spike timing data, which is needed by downstream users to determine whether fine-timescale analyses are appropriate.

A common mistake is to set the sampling rate (e.g., 30000) instead of the resolution. To avoid this, invert the quantity: resolution=1/sampling_rate.

Check functions: check_units_resolution_is_set(), check_units_resolution_is_valid()

Spike Times in Seconds

Spike times must be stored in seconds with respect to the timestamps_reference_time of the NWBFile (which by default is the session_start_time).

A common failure is writing spike times in samples instead of seconds. To convert, divide by the sampling rate of the recording. Spike times in samples are integer-valued, while real spike times in seconds have fractional parts at any common electrophysiology sampling rate.

Check function: check_spike_times_not_in_samples()

Negative Spike Times

All spike times should be greater than zero. Being less than zero implies the spikes are either trial-aligned (and should therefore be aligned to the timestamps_reference_time of the NWBFile) or the timestamps_reference_time itself is not set to the earliest recording time during the session.

Check function: check_negative_spike_times()

Observation Intervals

The obs_intervals field of the Units table is used to indicate periods of time where the underlying electrical signal(s) were not observed. This can happen if the recording site moves away from the unit, or if the recording is stopped. Since the channel is not observed, it is not determinable whether a spike occurred during this time. Therefore, there should not be any identified spike times for units matched to those electrical signal(s) occurring outside of the defined obs_intervals. If this variable is not set, it is assumed that all time is observed.

Check function: check_spike_times_not_in_unobserved_interval()

No NaN Spike Times

Spike times are physical event timestamps and must always be valid floating-point numbers. A NaN value in the spike_times column typically indicates a conversion bug or array padding that was not cleaned up before writing to NWB. Unlike missing data in continuous signals, a spike either occurred at a specific time or it did not, so NaN is never meaningful. Clean your spike time arrays to remove any NaN values before adding them to the Units table.

Check function: check_spike_times_without_nans()

Ascending Spike Times

The spike times within each unit of the Units table must be strictly ascending. Descending spike times always indicate a data error, such as trial-concatenated times, a spike sorting bug, or a conversion error. Equal consecutive spike times violate the neural refractory period for single-unit data and are also flagged.

If your recording hardware has limited temporal resolution (e.g., low sampling rate or binned spike sorting output), equal consecutive spike times may be expected. In this case, set the resolution field on the Units table to the smallest resolvable difference between spike times in seconds (e.g., Units(resolution=1/30000) for a 30 kHz sampling rate). When resolution is set, equal consecutive spike times are allowed.

Check function: check_ascending_spike_times()

ElectricalSeries

Data Type and Conversion

When storing raw electrophysiology data in an ElectricalSeries, it is common to use integer data types (e.g., int16, uint16) to save storage space. However, if using integer data types, you must set the conversion and/or offset fields to convert the raw data to Volts.

If the data is stored as an integer type with default values of conversion=1.0 and offset=0.0, this likely indicates that the raw acquisition units are being stored without proper scaling to Volts. This is problematic because the NWB specification expects electrophysiology data to be in Volts (or to have conversion factors that convert to Volts).

For per-channel conversion factors, use the channel_conversion field, which allows specifying different scaling factors for each channel. This is particularly useful when different channels have different gain settings.

Check function: check_electrical_series_unscaled_data()