Map Annotations To ISXD Data¶

Overview¶

This tool maps frames from one or more experiment annotations files to frames in one or more .isxd files, and generates a single annotations file in a .parquet format that can be used with the following tools:

• Compare Neural Activity Across States
• Compare Neural Circuit Correlations Across States

This tool does two things:

• maps frames from input annotations to an isxd file
• convert those annotations to a format usable by other tools (into a .parquet file)

Parameters¶

Input Data¶

Valid Inputs¶

ISXD File(s)¶

The ISXD input can be one of the following types:

• Movie: The file contains a time series of movie frames and metadata acquired by an Inscopix system.
• Cell set: The file contains time series traces for each cell in the field-of-view of the recording along with the corresponding footprints.

A series of ISXD files can also be used as an input.

Input CSV Annotations File(s)¶

The annotations file can be either a .csv or .parquet file that must satisfy the following:

• It may have any number of columns
• There exists a column that contains timestamps in seconds relative to the start time of the recording. These timestamps are numbers convertible to floats
• There exists a column that contains values representing the event types, and must be of a type convertible to a string
• The number of annotations files should match the number of ISXD files. Alternatively, a single annotations file with timestamps relative to the start time of the first ISXD file may be used.

The content of a sample CSV annotation file is shown below, what could be used to encode behavioral information:

You may also use such a file to specify other sorts of annotations. For example:

For annotations files generated from .isxb files, the contents of the file will have some specific columns containing timing metadata necessary for mapping. For example, here's an annotations file generated by the Compute Locomotion Metrics tool that can be used as input to this tool:

The Time since start (s) and State columns will be specified as the column names for the input to the tool. Additionally, the Hardware counter (us) column will be used to precisely map frames from the annotations to the corresponding synchronized ISXD files.

Parameters¶

Algorithm details¶

This tool will map frames in the annotations file(s) for every frame in the .isxd file(s), by comparing timestamps using the following procedure.

Step 1: Detect hardware counter timestamps¶

The tool first checks if a column named Hardware counter (us) exists within the annotations file. This column contains hardware counter timestamps (also known as tsc values) extracted from the .isxb file which generated the annotations file.

Step 2: Compute annotations timestamps relative to .isxd timestamps¶

If hardware counter timestamps are present, then they are used to compute accurate timestamps of the samples in the annotations file, relative to the start of the reference .isxd file.

Since the start of the reference .isxd file is not the same as the annotations .isxb file, the tool computes the time delta between the first frame of the reference .isxd file and the first frame of the annotations .isxb file, and then adds this time delta to every frame timestamp of the annotations .isxb file.

For example, consider the following .isxd and .isxb files. Each file has four frames, and is recorded at a frequency of 1 Hz, however the .isxb file starts one second after the .isxd file.

>>> isxd_times = [0, 1, 2, 3] # timestamps in s of isxd file, relative to start of isxd file
>>> isxd_tsc = [0, 1000000, 2000000, 3000000] # tsc in us of isxd file

>>> isxb_times = [0, 1, 2, 3] # timestamps in s of isxb file, relative to start of isxb file
>>> isxb_tsc = [1000000, 2000000, 3000000, 4000000] # tsc in us of isxb file

>>> time_delta = (isxb_tsc[0] - isxd_tsc[0]) / 1e6 # compute time delta in s
>>> isxb_times += time_delta # add time delta to every isxb timestamp
>>> isxb_times # timestamps in s of isxb file, relative to start of isxd file
    [1, 2, 3, 4]

Step 3: Map annotations frames using timestamps¶

For every .isxd frame, the tool will find the annotation frame with the closest timestamp. If two annotation frames are equally close to the .isxd frame, then the annotation frame with the nearest even frame number will be selected.

The following pseudocode, demonstrates the steps of this mapping with an .isxd file containing 8 frames recorded at 1 Hz, and an .isxb file containing 4 frames recorded at 0.5 Hz, starting 1 s after the .isxd file:

>>> isxd_times = [0, 1, 2, 3, 4, 5, 6, 7] # timestamps in s of isxd file, relative to start of isxd file
>>> annotations_times = [1, 3, 5, 7] # timestamps in s of isxb file, relative to start of isxd file
>>> annotations_frames = [0, 1, 2, 3] # frame number of annotations file to map to isxd file (i.e., 0, 1, ... n)

# for every frame of the isxd file, find the closest frame in the annotations file
>>> mapped_annotations_frames = np.interp(isxd_times, annotations_times, annotations_frames)
>>> mapped_annotations_frames
array([0. , 0. , 0.5, 1. , 1.5, 2. , 2.5, 3. ])

# need to round to whole integer frame number
>>> mapped_annotations_frames = np.round(mapped_annotations_frames).astype(int)
>>> mapped_annotations_frames
array([0, 0, 0, 1, 2, 2, 2, 3])

# map annotation frames to isxd frames
>>> np.array(annotations_times)[mapped_annotations_frames]
array([1, 1, 1, 3, 5, 5, 5, 7])

Step 4: Map all other columns of the annotations file(s)¶

In the final step, the tool creates output annotations files with every other column in the annotations files, mapped to the .isxd files. Some additional columns are also included in the mapped annotations files, described in the next section.

Output Data¶

The tool will output a parquet file with at least the following columns:

• frame: The frame number in the input ISXD file
• series: The file number in the input ISXD series
• time The timestamps, in seconds, from the input ISXD file. This is in recording time, meaning time delays are not factored between files in an ISXD series.
• time since start (s) The timestamps, in seconds, from the input ISXD file. This is relative to the start of the first ISXD file (i.e., start of experiment), meaning time delays are factored between files in an ISXD series.
• mapped frame: The frame number in the annotations file that maps to the corresponding ISXD file. This frame will have to closest timestamp to the corresponding ISXD frame.
• mapped time since start (s) The timestamps, in seconds, from the input annotations file. This is relative to the start of the first ISXD file (i.e., start of experiment), meaning time delays are factored between files in an annotations series.
• state labels for the state mapped from the input annotations

An example table is shown below: