ndx-events NWB扩展

这是一个NWB扩展，用于存储带时间戳的事件数据和TTL脉冲。

事件可以是

1. 简单事件。这些存储在Events类型中。该类型仅包含名称、描述和一个时间戳的1D数组。当时间序列没有数据时，应使用此类型而不是TimeSeries。
2. 标记事件。这些存储在LabeledEvents类型中。该类型通过添加1)一个与时间戳长度相同的整数值（数据）的1D数组和2)与数据数组中每个唯一整数值相关联的标签的1D数组来扩展Events类型。数据值是标签数组的索引。该类型可以用来编码有关单个事件的额外信息，例如每个奖励事件的奖励值。
3. TTL脉冲。这些存储在TTLs类型中。该类型是专门用于TTL脉冲数据的LabeledEvents类型的子类型。应使用单个实例来存储所有TTL脉冲数据。脉冲值（或通道）应存储在1D数据数组中，与每个脉冲值（或通道）相关联的标签应存储在标签的1D数组中。
4. 注释事件。这些存储在 注释事件表 类型中。注释事件表 类型是 DynamicTable 的子类型，其中每一行对应不同的事件类型。该表具有锯齿形（变长）的 1D 列，表示事件时间，使得每个事件类型（行）都与事件时间数组相关联。与其他事件类型不同，用户可以为每个事件类型或事件时间添加自己的自定义列进行注释。这可以用于存储与数据预处理和分析相关的元数据，例如标记不良事件。

此扩展由 Ryan Ly、Ben Dichter、Oliver Rübel 和 Andrew Tritt 开发。有关此扩展的原理、背景和替代方法的更多信息，请参阅此处：https://docs.google.com/document/d/1qcsjyFVX9oI_746RdMoDdmQPu940s0YtDjb1en1Xtdw

安装

pip install ndx-events

示例用法

from datetime import datetime

from pynwb import NWBFile, NWBHDF5IO
from ndx_events import LabeledEvents, AnnotatedEventsTable


nwb = NWBFile(
    session_description='session description',
    identifier='cool_experiment_001',
    session_start_time=datetime.now().astimezone()
)

# create a new LabeledEvents type to hold events recorded from the data acquisition system
events = LabeledEvents(
    name='LabeledEvents',
    description='events from my experiment',
    timestamps=[0., 0.5, 0.6, 2., 2.05, 3., 3.5, 3.6, 4.],
    resolution=1e-5,  # resolution of the timestamps, i.e., smallest possible difference between timestamps
    data=[0, 1, 2, 3, 5, 0, 1, 2, 4],
    labels=['trial_start', 'cue_onset', 'cue_offset', 'response_left', 'response_right', 'reward']
)

# add the LabeledEvents type to the acquisition group of the NWB file
nwb.add_acquisition(events)

# create a new AnnotatedEventsTable type to hold annotated events
annotated_events = AnnotatedEventsTable(
    name='AnnotatedEventsTable',
    description='annotated events from my experiment',
    resolution=1e-5  # resolution of the timestamps, i.e., smallest possible difference between timestamps
)
# add a custom indexed (ragged) column to represent whether each event time was a bad event
annotated_events.add_column(
    name='bad_event',
    description='whether each event time should be excluded',
    index=True
)
# add an event type (row) to the AnnotatedEventsTable instance
annotated_events.add_event_type(
    label='Reward',
    event_description='Times when the subject received juice reward.',
    event_times=[1., 2., 3.],
    bad_event=[False, False, True],
    id=3
)

# create a processing module in the NWB file to hold processed events data
events_module = nwb.create_processing_module(
    name='events',
    description='processed event data'
)

# add the AnnotatedEventsTable instance to the processing module
events_module.add(annotated_events)

# write nwb file
filename = 'test.nwb'
with NWBHDF5IO(filename, 'w') as io:
    io.write(nwb)

# read nwb file and check its contents
with NWBHDF5IO(filename, 'r', load_namespaces=True) as io:
    nwb = io.read()
    print(nwb)

此扩展使用 ndx-template 创建。