CSV Events data conversion

CSVEventsInterface is a general-purpose reader for discrete events (e.g. TTL pulses) stored in a CSV file. You point it at one CSV and assign each column a role: timestamps_column gives each event’s onset (seconds), event_type_column names the type of each event (pass None for a single-type file), value_columns carries extra columns along as per-event values, and durations_column writes per-event durations. Any column you do not assign a role is omitted, so event payloads are opt-in – only the columns you name in value_columns are carried along. The resulting pynwb.event.EventsTable objects land in nwbfile.events.

How the event types map onto tables – one table per type by default, or several types merged into a single table – is driven entirely by the editable events metadata. See How to Annotate Discrete Events Metadata for the full metadata format.

CSV events need only NeuroConv’s core dependencies, but the csv_events extra is available for a consistent install command.

pip install "neuroconv[csv_events]"

CSV recordings carry no embedded recording-start timestamp, so session_start_time must be supplied explicitly in the metadata.

>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo

>>> import pandas as pd

>>> from neuroconv.datainterfaces import CSVEventsInterface

>>> # This format is just a CSV; here we write a small example event file with a single
>>> # ``timestamps`` column holding the event timestamps (seconds).
>>> file_path = output_folder / "ttl.csv"
>>> pd.DataFrame({"timestamps": [1.5, 2.5, 3.5, 4.5]}).to_csv(file_path, index=False)

>>> interface = CSVEventsInterface(
...     file_path=file_path, timestamps_column="timestamps", event_type_column=None, verbose=False
... )
>>> metadata = interface.get_metadata()
>>> # CSV recordings have no embedded start time, so it must be set explicitly.
>>> metadata["NWBFile"]["session_start_time"] = datetime.now(tz=ZoneInfo("US/Pacific"))
>>> # Add subject information (required for DANDI upload)
>>> metadata["Subject"] = dict(subject_id="subject1", species="Mus musculus", sex="M", age="P30D")

>>> # Choose a path for saving the nwb file and run the conversion
>>> nwbfile_path = f"{path_to_save_nwbfile}"
>>> interface.run_conversion(nwbfile_path=nwbfile_path, metadata=metadata, overwrite=True)