Text#

Time Intervals#

class TimeIntervalsInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], read_kwargs: dict | None = None, verbose: bool = False)[source]#

Bases: BaseDataInterface

Abstract Interface for time intervals.

Initialize the TimeIntervalsInterface.

Parameters:

  • file_path (FilePath) – The path to the file containing time intervals data (CSV, Excel, etc.).

  • read_kwargs (dict, optional) – Additional keyword arguments passed to the file reading function. For CSV files, these are passed to pandas.read_csv(). For Excel files, these are passed to pandas.read_excel(). Examples: {“sep”: “;”, “encoding”: “utf-8”, “skiprows”: 1} Default is None.

  • verbose (bool, default: False) – Controls verbosity of the interface output.

keywords: tuple[str] = ('table', 'trials', 'epochs', 'time intervals')#
get_metadata() → DeepDict[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

get_metadata_schema() → dict[source]#

Get the metadata schema for the time intervals.

Returns:

The schema dictionary for time intervals metadata.

Return type:

dict

get_original_timestamps(column: str) → ndarray[source]#

Get the original timestamps for a given column.

Parameters:

column (str) – The name of the column containing timestamps.

Returns:

The original timestamps from the specified column.

Return type:

np.ndarray

Raises:

ValueError – If the column name does not end with ‘_time’.

get_timestamps(column: str) → ndarray[source]#

Get the current timestamps for a given column.

Parameters:

column (str) – The name of the column containing timestamps.

Returns:

The current timestamps from the specified column.

Return type:

np.ndarray

Raises:

ValueError – If the column name does not end with ‘_time’.

set_aligned_starting_time(aligned_starting_time: float)[source]#

Align the starting time by shifting all timestamps by the given value.

Parameters:

aligned_starting_time (float) – The aligned starting time to shift all timestamps by.

set_aligned_timestamps(aligned_timestamps: ndarray, column: str, interpolate_other_columns: bool = False)[source]#

Set aligned timestamps for the given column and optionally interpolate other columns.

Parameters:

  • aligned_timestamps (np.ndarray) – The aligned timestamps to set for the given column.

  • column (str) – The name of the column to update with the aligned timestamps.

  • interpolate_other_columns (bool, optional) – If True, interpolate the timestamps in other columns, by default False.

Raises:

ValueError – If the column name does not end with ‘_time’.

align_by_interpolation(unaligned_timestamps: ndarray, aligned_timestamps: ndarray, column: str)[source]#

Align timestamps using linear interpolation.

Parameters:

  • unaligned_timestamps (np.ndarray) – The original unaligned timestamps that map to the aligned timestamps.

  • aligned_timestamps (np.ndarray) – The target aligned timestamps corresponding to the unaligned timestamps.

  • column (str) – The name of the column containing the timestamps to be aligned.

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None, tag: str = 'trials', column_name_mapping: dict[str, str] = None, column_descriptions: dict[str, str] = None) → NWBFile[source]#

Add time intervals data from the CSV/Excel file to an NWBFile object.

Parameters:

  • nwbfile (NWBFile) – An in-memory NWBFile object to add the time intervals data to.

  • metadata (dict, optional) – Metadata dictionary containing time intervals configuration. If not provided, uses default metadata from get_metadata().

    Expected structure under metadata[“TimeIntervals”][tag]:

    • table_namestr

      Name of the time intervals table. Determines storage location in NWB: * “trials” → nwbfile.trials * “epochs” → nwbfile.epochs * Other names → nwbfile.intervals[table_name]

    • table_descriptionstr

      Description of the time intervals data.

    Example:
    metadata = {
    “TimeIntervals”: {
    “tag”: {

    “table_name”: “trials”, “table_description”: “Experimental trials”

    }

    }

    }

    To add as epochs instead:

    metadata[“TimeIntervals”][“tag”][“table_name”] = “epochs”

  • tag (str, default: “trials”) – Key to use when looking up time intervals metadata in metadata[“TimeIntervals”][tag]. By default, looks for metadata[“TimeIntervals”][“trials”].

  • column_name_mapping (dict of str to str, optional) – Dictionary to rename columns from the source file. Keys are original column names, values are new names. Example: {“condition”: “trial_type”, “start”: “start_time”}

  • column_descriptions (dict of str to str, optional) – Dictionary providing descriptions for columns (after any renaming). Keys are column names (after mapping), values are descriptions. If not provided, column names are used as descriptions. Example: {“trial_type”: “Type of trial”, “correct”: “Response accuracy”}

Returns:

The NWBFile object with time intervals data added.

Return type:

NWBFile

Notes

  • The time intervals are added to nwbfile.intervals and also set as direct properties for “trials” and “epochs” to enable in-memory access (e.g., nwbfile.trials).

  • All timing columns must be in seconds.

  • The ‘start_time’ column is required; ‘stop_time’ is auto-generated if missing.

CSV#

class CsvTimeIntervalsInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], read_kwargs: dict | None = None, verbose: bool = False)[source]#

Bases: TimeIntervalsInterface

Interface for adding data from a .csv file as a TimeIntervals object.

Initialize the TimeIntervalsInterface.

Parameters:

  • file_path (FilePath) – The path to the file containing time intervals data (CSV, Excel, etc.).

  • read_kwargs (dict, optional) – Additional keyword arguments passed to the file reading function. For CSV files, these are passed to pandas.read_csv(). For Excel files, these are passed to pandas.read_excel(). Examples: {“sep”: “;”, “encoding”: “utf-8”, “skiprows”: 1} Default is None.

  • verbose (bool, default: False) – Controls verbosity of the interface output.

display_name: str | None = 'CSV time interval table'#
associated_suffixes: tuple[str] = ('.csv',)#
info: str | None = 'Interface for writing a time intervals table from a comma separated value (CSV) file.'#

Excel#

class ExcelTimeIntervalsInterface(file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], read_kwargs: dict | None = None, verbose: bool = False)[source]#

Bases: TimeIntervalsInterface

Interface for adding data from an Excel file to NWB as a TimeIntervals object.

Parameters:

  • file_path (FilePath)

  • read_kwargs (dict, optional) – Passed to pandas.read_excel()

  • verbose (bool, default: False)

display_name: str | None = 'Excel time interval table'#
associated_suffixes: tuple[str] = ('.xlsx', '.xls', '.xlsm')#
info: str | None = 'Interface for writing a time intervals table from an excel file.'#