Pulse Alignment

Syncing events to recording time

First, generate send and receive pulse files for each task run. This will depend on the specific task and the manner in which the pulse files were recorded.

Pulse files should be in .tsv format, with two columns: onset and signal. For send files, the onset field should be in seconds and be relative to the start of each task run. For receive files, the onset field may be in whatever timeline the recording files are in. Note that this differs from standard BIDS format, where all times should be relative to the start of recording. However, practically it may be difficult to rewrite all recording formats to have the correct time in seconds, so this modification can make it easier to work with some different file types.

Pulse files should follow the same naming convention as task events files, but replacing events with send or recv.

Once you have send and receive files, you can determine the mapping between them:

sync-align bids_dir sub ses

This will attempt to determine the shift and scaling necessary to make the TTLs in each send file match up with a corresponding portion of the receive file. The tool uses a regression-based method that should be relatively robust to things like missing pulses or extra pulses, as long as there are enough pulses to work with and there is sufficient random jitter to allow matching to a specific set of receive pulses. This step may take a while. Once it finishes, you will have new .json files for each run giving the mapping computed for that run. This includes an offset (time in seconds to add to task time), slope (multiplier of task time), and scale (scale to apply after applying the offset and slope). Here, the scale is used to translate task time (in seconds) to Neuralynx time (in microseconds).

Update the events files to include the correct onset time within the recordings:

sync-events bids_dir sub ses

This will apply the translation specified in the JSON file to determine the onset time of each event in the recording, and add an ieeg field with that time. That field can be then used to load epochs for each event in the task run.

Because the alignment (mapping pulses) and syncing (updating events with recording onsets) steps are separate, you can quickly update the events (for example, to add more fields, or fix a bug) and then just rerun the sync-events without having to redo the alignment step.

After alignment completes, check the sync performance:

sync-align-check bids_dir sub ses

This will generate a PDF file plotting the send pulses in red, and the receive pulses in blue. Generally, all of the blue pulses should have a red counterpart; if not, there may have been a run that was misaligned and assigned to the wrong time period.