Event timing files#

Event timing "fidl" files are simple text files that specify the event sequence in a BOLD run. They can refer to a single image or a set of images joined in a conc file.

The first line in a fidl file provides information on the TR used when acquiring functional images and a list of event types used in the data part of the file. Values in the header are separated by whitespace (either spaces or tabs). Each following line provides information on a single event. For each coded event at least three values are to be provided separated by whitespace in the following order: onset of the event, event code, event duration. Onset of the event is to be specified in seconds from the start of the first run. Event code has to match the provided list of events in the first line. The first listed event has code 0, the second code 1, etc. The duration of the event is again provided in seconds. Additional columns can specify additional values (e.g. behavioral coregressors) that can be utilized in the preprocessing or analyses.

Besides events, fidl files can also provide information on frames that are to be ignored in analyses. These are coded by two values only—the first is the onset of the first frame to be ignored, the second a negative value expressing the number of frames to ignore.

Example#

2.0 cue stimulus response
6.0  0 1 315
10.0 1 3 315
14.4 2 1 315
18.0 0 1 421
12.0 1 3 421
16.8 2 1 421
18.0 -6
34.0 0 1 374
36.0 1 3 374
41.1 2 1 374
...

This file specifies a TR of 2 seconds and three events, cue, stimulus, and response. Cue has a duration of 1 second and appears 6, 18, and 34 seconds into the run. Stimulus has a duration of 3 seconds and appears 10, 12, and 36 seconds into the run, similarly for response. There should be 6 frames omitted from the analysis starting 18 seconds into the run. For each event the reaction time of the corresponding response is listed and can be used as a coregressor in the analysis.

Note that when a fidl file refers to multiple concatenated files (as specified by a conc file), the onset time for an event that occurs in the second functional image should be provided as the sum of the duration of the first functional image and time of the event within the second functional image. Similarly, the onset time for an event in the third functional image should be provided as the sum of the lengths of the first two functional images and the event onset time within the third functional image. E.g., if an event occurs at 15 seconds into the third functional image and the two images before each lasted 300 seconds, then the onset time of that event within the concatenated functional timeseries should be specified as 615 seconds.

By convention fidl files end with .fidl extension.

Note: Due to varieties of ways that events can be described for different studies and tasks, no command exists that would enable automatic generation of fidl files. There are two utilities functions that enable joining fidl files across multiple functional images as specified in conc files, or separating a joint fidl file back into fidl files for each functional image separately. The available fidl related commands are:

  • join_fidl

    creates a joint fidl file based on separate fidl files for each functional image and a related conc file. For example, when fidl files were generated for each BOLD image separately, this command enables combining of fidl files for all the relevant BOLD images into a single fidl file. When combining the fidl files the times are recomputed to correctly match the concatenated BOLD signal timeseries.

  • join_fidl_folder

    creates a set of joint fidl files based on separate fidl files for each functional image and a related conc file. For example, it enables automatic combining fidl files for multiple sessions in a single step, simplifying the process. It expects a specific organisation and naming of conc and fidl files.

  • split_fidl

    splits a joint fidl file into separate fidl files for each functional image as specified in the conc file. For example, it can be used when a combined fidl file needs to be split into individual files that match the individual acquired BOLD image files rather than the concatenated BOLD signal timeseries.

  • check_fidl

    creates a visual overview of the events and their durations based on the provided fidl file. Specifically, it creates a plot of events and their durations and saves them in PDF files for quick visual review.

Please check each command's in-line documentation for specific parameters and usage.