Events

CSV Events

class CSVEventsInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], *, timestamps_column: str | int, event_type_column: str | int | None, metadata_key: str | None = None, read_kwargs: dict | None = None, verbose: bool = False)

Bases: BaseDataInterface

Data Interface for converting discrete events from a single CSV file.

This is a general-purpose CSV events reader: the caller points at one CSV file and names the column holding the event timestamps in seconds (timestamps_column) and, optionally, the column that tells the event types apart (event_type_column).

Two layouts are supported:

• A single event type (event_type_column=None): every row is one occurrence of the same event, and the file becomes one ndx_events.Events object named after the file stem.

• Several event types in one file (event_type_column set): each row carries a label in that column, and the file becomes one ndx_events.LabeledEvents object named after the file stem – the timestamps plus a per-event integer code into the label vocabulary. This mirrors how TDTEventsInterface writes a labeled (strobe) store.

Columns other than timestamps_column and event_type_column are ignored; only timestamps (and, for the labeled case, the event labels) are written.

Notes

CSV recordings carry no embedded recording-start timestamp, so get_metadata() does NOT populate NWBFile/session_start_time. The user must supply it via editable metadata.

Initialize the CSVEventsInterface.

Parameters:

• file_path (FilePath) – The path to the CSV file holding the events.

• timestamps_column (str or int) – The column holding the event timestamps (seconds). A column name for a CSV with a header row, or a positional index (0-based) for a header-less CSV.

• event_type_column (str, int, or None) – The column, if any, that names the type of each event. Pass a column name or index when the file holds several event types told apart by that column, so that the file is written as a single LabeledEvents with one label per distinct value. Pass None when the file is a single event type with no such column, in which case the file is written as a plain Events named after the file stem.

• metadata_key (str, optional) – The key under metadata["Events"] that namespaces this interface’s events metadata. If None (default), "csv_events" is used.

• read_kwargs (dict, optional) – Additional keyword arguments forwarded to pandas.read_csv, used to handle format quirks such as sep, encoding, decimal, or skiprows. Any value given here overrides the interface’s own defaults (header, float_precision, and keep_default_na=False – the latter keeps label tokens such as 'None', 'NA', or 'null' from collapsing into a single missing label). Default is None.

• verbose (bool, optional) – Whether to print status messages, default = False.

keywords: tuple[str] = ('events', 'CSV')

display_name: str | None = 'CSVEvents'

info: str | None = 'Data Interface for converting discrete events from a single CSV file.'

associated_suffixes: tuple[str] = ('csv',)

get_metadata() → DeepDict

Get metadata for the CSVEventsInterface.

NWBFile/session_start_time is intentionally left unset: CSV recordings carry no embedded recording-start timestamp, so it must be supplied by the user via editable metadata.

Returns:

The metadata dictionary for this interface.

Return type:

DeepDict

get_metadata_schema() → dict

Get the metadata schema for the CSVEventsInterface.

Returns:

The metadata schema for this interface.

Return type:

dict

add_to_nwbfile(nwbfile: NWBFile, metadata: dict) → None

Add the events to the NWBFile as an ndx_events.Events or LabeledEvents object.

Parameters:

• nwbfile (NWBFile) – The NWB file to add the events to.

• metadata (dict) – Metadata dictionary. The single entry in metadata["Events"][metadata_key]["event_columns"] holds the output object’s column_name and description. A column_categories["labels"] map (raw value -> display label) marks the file as labeled and is written as LabeledEvents; its absence writes a plain Events.

TDT Events

class TDTEventsInterface(folder_path: Annotated[pathlib._local.Path, PathType(path_type='dir')], *, exclude_events: list[str] | None = None, metadata_key: str | None = None, verbose: bool = False)

Bases: TDTLoadMixin, BaseEventsInterface

Data Interface for converting discrete events (epocs) from a TDT output folder.

The TDT tank stores discrete events as epocs (e.g. camera TTL pulses, port entries, nose pokes). This interface reads those epocs via tdt.read_block and writes each selected epoc as one pynwb.event.EventsTable inside nwbfile.events.

Most epoc stores are onset-type epocs whose data array is a meaningless incrementing counter, so only the onsets are written (a timestamp-only table). A store whose data carries real strobe codes (e.g. the PAB_ store’s [16, 2064, 0] cycle) additionally gets a categorical strobe column, with the codes as per-event labels. The offset array of an onset-type epoc is a synthesized fill (offset[i] == onset[i + 1], last value inf) and is not written. Epocs that carry real offset (STROFF) durations are written as durative events, with each event’s duration (offset minus onset) in the table’s duration column.

Initialize the TDTEventsInterface.

Parameters:

• folder_path (DirectoryPath) – The path to the folder containing the TDT data.

• exclude_events (list[str], optional) – The names of the TDT epocs to skip. If None (default), every epoc in the tank is stored.

• metadata_key (str, optional) – The key under metadata["Events"] that namespaces this interface’s events metadata. If None (default), "tdt_events" is used.

• verbose (bool, optional) – Whether to print status messages, default = False.

keywords: tuple[str] = ('events', 'TDT')

display_name: str | None = 'TDTEvents'

info: str | None = 'Data Interface for converting discrete events (epocs) from TDT files.'

associated_suffixes: tuple[str] = ('Tbk', 'Tdx', 'tev', 'tin', 'tsq')

get_metadata() → DeepDict

Get metadata for the TDTEventsInterface.

Returns:

The metadata dictionary for this interface.

Return type:

DeepDict