timing_tool.py


timing_tool.py - for manipulating and evaluating stimulus timing files
(-stim_times format: where each row is a separate run)

purpose:

This program is meant to work with ascii files containing rows of floats
('*' characters are ignored).  This is the format used by 3dDeconvolve
with the -stim_times option.  Some timing files do not need evaluation,
such as those where the timing is very consistent.  However, it may be
important to examine those files from a random timing design.

Recall that an ISI (inter-stimulus interval) is the interval of time
between the end of one stimulus and start of the next.

The basic program operations include:

    o reporting ISI statistics, such as min/mean/max values per run
    o reporting overall ISI statistics for a set of timing files
    o converting stim_times format to stim_file format
    o adding a constant offset to time
    o combining multiple timing files into 1 (like '1dcat' + sort)
    o appending additional timing runs (like 'cat')
    o sort times per row (though 3dDeconvolve does not require this)
    o converting between local and global stim times

A sample stimulus timing file having 3 runs with 4 stimuli per run
might look something like the following.  Note that the file does not
imply the durations of the stimuli, except that stimuli are generally
not allowed to overlap.

   17.3 24.0 66.0 71.6
   11.0 30.6 49.2 68.5
   19.4 28.7 53.8 69.4

The program works on either a single timing element (which can be modified),
or a list of them (which cannot be modified).  The only real use of a list
of timing elements is to show statistics (via -multi_show_isi_stats).

examples:

Example 0. basic commands

timing_tool.py -help
timing_tool.py -hist
timing_tool.py -show_valid_opts
timing_tool.py -ver

Example 1. combine the timing of 2 (or more) files

Extend one timing by another and sort.  Write to a new timing file.

   timing_tool.py -timing stimesB_01_houses.1D         \
                  -extend stimesB_02_faces.1D          \
                  -sort                                \
                  -write_timing stimesB_extended.1D

Example 2. subtract 12 seconds from each stimulus time

For example, subtract 12 seconds to offset TRs dropped prior to
the magnetization steady state.

   timing_tool.py -timing stimesB_01_houses.1D         \
                  -add_offset -12.0                    \
                  -write_timing stimesB1_offset12.1D

Example 2b. similar to 2, but scale times (multiply) by 0.975

Scale, perhaps to account for a different TR or stimulus duration.

   timing_tool.py -timing stimesB_01_houses.1D         \
                  -scale_data 0.975                    \
                  -write_timing stimesB1_scaled.1D

Example 2c. shift times so first event is at start of run

This is like adding a negative offset equal to the first event time
of each run.

   timing_tool.py -timing stimesB_01_houses.1D         \
                  -shift_to_run_offset 0               \
                  -write_timing stimesB1_offset0.1D

Example 3. show timing statistics for task and rest

Show timing statistics for the 3 timing files generated by example 3
from "make_random_timing -help".  To be accurate, specify the run and
stimulus durations.

   timing_tool.py -multi_timing stimesC_*.1D           \
                  -run_len 200 -multi_stim_dur 3.5     \
                  -multi_show_isi_stats

Example 4. show timing stats where durations and run lengths vary

Show timing statistics for the timing files generated by example
6 from "make_random_timing -help".  Since both the run and stimulus
durations vary, 4 run lengths and 3 stimulus durations are given.

   timing_tool.py -multi_timing stimesF_*.1D           \
                  -run_len 200 190 185 225             \
                  -multi_stim_dur 3.5 4.5 3            \
                  -multi_show_isi_stats

Example 5. partition a timing file based on a partition file

Partition the stimulus timing file 'response_times.1D' into
multiple timing files based on the labels in a partition file,
partitions.1D.  If partitions.txt contains (0, correct, incorrect),
there will be 2 output timing files, new_times_correct.1D and
new_times_incorrect.1D.
Times where the partition label is '0' will be skipped.

   timing_tool.py -timing response_times.1D       \
                  -partition partitions.txt new_times

Example 6a. convert a stim_times timing file to 0/1 stim_file format

Suppose the timing is random where each event lasts 2.5 seconds and runs
are of lengths 360, 360 and 400 seconds.  Convert timing.txt to sfile.1D
on a TR grid of 0.5 seconds (oversampling), where a TR gets an event if
at least 30% of the TR is is occupied by stimulus.

    timing_tool.py -timing timing.txt -timing_to_1D sfile.1D      \
                   -tr 0.5 -stim_dur 2.5 -min_frac 0.3            \
                   -run_len 360 360 400

** consider option -timing_to_1D_warn_ok

Example 6b. evaluate the results

Use waver to convolve sfile.1D with GAM and use 3dDeconvolve to
convolve the timing file with BLOCK(2.5).  Then plot.

   waver -GAM -TR 0.5 -peak 1 -input sfile.1D > waver.1D

   3dDeconvolve -nodata 2240 0.5 -concat '1D: 0 720 1440'        \
                -polort -1 -num_stimts 1                         \
                -stim_times 1 timing.txt 'BLOCK(2.5)'            \
                -x1D X.xmat.1D -x1D_stop

   1dplot -sepscl sfile.1D waver.1D X.xmat.1D

Example 6c. like 6a, but per run; leave each run in a separate file

Add option -per_run_file.

   timing_tool.py -timing timing.txt -timing_to_1D sfile.1D      \
                  -tr 0.5 -stim_dur 2.5 -min_frac 0.3            \
                  -run_len 360 360 400 -per_run_file

Example 6d. like 6c, but write amplitude modulators

Add option -timing_to_1D_mods.

   timing_tool.py -timing timing.txt -timing_to_1D smods.1D      \
                  -timing_to_1D_mods                             \
                  -tr 0.5 -stim_dur 2.5 -min_frac 0.3            \
                  -run_len 360 360 400 -per_run_file

Example 7a. truncate stimulus times to the beginning of respective TRs

Given a TR of 2.5 seconds and random stimulus times, truncate those times
to multiples of the TR (2.5).

    timing_tool.py -timing timing.txt -tr 2.5 -truncate_times     \
                   -write_timing trunc_times.txt

Here, 11.83 would get truncated down to 10, the largest multiple of 2.5
less than or equal to the original time.

Example 7b. round time based on TR fraction, rather than truncating

Instead of just truncating the times, round them to the nearest TR,
based on some TR fraction.  In this example, round up to the next TR
when a stimulus occurs at least 70% into a TR, otherwise round down to
the beginning.

    timing_tool.py -timing timing.txt -tr 2.5 -round_times 0.7    \
                   -write_timing round_times.txt

With no rounding, a time of 11.83 would be truncated to 10.0.  But 11.83
is 1.83 seconds into the TR, or is 73.2 percent into the TR.  Since it is
at least 70% into the TR, it is rounded up to the next one.

Here, 11.83 would get rounded up to 12.5.

Example 8a. create an event list from stimulus timing files

The TR is 1.25s, events are ~1 TR long.  Require them to occupy at
least half of the given TR.  Specify that rows should be per run and
the run durations are all 370.

    timing_tool.py -multi_timing stimes.*.txt        \
         -multi_timing_to_events all.events.txt      \
         -tr 1.25 -multi_stim_dur 1 -min_frac 0.5    \
         -per_run -run_len 370

Example 8b. break the event list into events and ISIs

Break the event list into 2, one for a sequence of changing event types,
one for a sequence of ISIs (TRs from one event to the next, including
the TR of the event).  So if the event file from #8 shows:
   0 0 3 0 0 0 0 1 0 2 2 0 0 0 ...
The resulting event/ISI files would read:
  event: 0 3 1 2 2 ...
  ISI:   2 5 2 1 4 ...

    timing_tool.py -multi_timing stimes.*.txt            \
         -multi_timing_to_event_pair events.txt isi.txt  \
         -tr 1.25 -multi_stim_dur 1 -min_frac 0.5        \
         -per_run -run_len 370

Example 9a. convert from global stim times to local

This requires knowing the run lengths, say 4 runs of 200 seconds here.
The result will have 4 rows, each starting at time 0.

   timing_tool.py -timing stim.1D                       \
         -global_to_local local.1D                      \
         -run_len 200 200 200

Note that if stim.1D looks like this ( ** but as a single column ** ):

         12.3 115 555 654 777 890

then local.1D will look like this:

         12.3 115
         155 254 377 490

It will complain about the 3 times after the last run ends (no run
should have times above 200 sec).

Example 9b. convert from local timing back to global

timing_tool.py -timing local.1D                       \
      -local_to_global global.1D                      \
      -run_len 200 200 200

Example 10. display within-TR statistics

Display within-TR statistics of stimulus timing files, to show
when stimuli occur within TRs.  The -tr option must be specified.

a. one file: show offset statistics (using -show_tr_stats)

      timing_tool.py -timing stim01_houses.txt -tr 2.0 -show_tr_stats

b. (one or) many files (use -multi_timing)

      timing_tool.py -multi_timing stim*.txt -tr 2.0 -show_tr_stats

c. only warn about potential problems (use -warn_tr_stats)

      timing_tool.py -multi_timing stim*.txt -tr 2.0 -warn_tr_stats

Example 11. test a file for local/global timing issues

Test a timing file for timing issues, which currently means having
times that are intended to be local but might be read as global.

   timing_tool.py -multi_timing stim*.txt -test_local_timing

Example 12. create a timing style event list

Create a simple horizontal event list (one row per run), where the event
class is the (1-based) index of the given input file.  This is very
similar to the first file output in example 8b, but no TR information is
required here.  Events are simply ordered.

    timing_tool.py -multi_timing stimes.*.txt            \
         -multi_timing_to_event_list index elist12.txt

Example 13a. create a GE (global events) list of ALL fields

Create a vertical GE (global events) list, showing ALL fields.

timing_tool.py -multi_timing stim.* -multi_timing_to_event_list GE:ALL -

Note: for convenience, one can also use -show_events, as in:

  timing_tool.py -multi_timing stim.* -show_events

This is much easier to remember, and it is a very common option.

Example 13b. like 13a, but restrict the output

Restrict global events list to:

       event index (i), duration (d), offset from previous (o),
       start time (t), and stim file (f)

 Also, write the output to elist13b.txt, rather than the screen.

    timing_tool.py -multi_timing stimes.*.txt            \
         -multi_timing_to_event_list GE:idotf elist13b.txt

Example 14. partition one stimulus class based on others

Class '1' (from the first input) is partitioned based on the class that
precedes it.  If none precede an early class 1 event, event INIT is used
as the default (else consider '-part_init 2', for example).

    timing_tool.py -multi_timing stimes.*.txt            \
         -multi_timing_to_event_list part part1.pred.txt

The result could be applied to actually partition the first timing file,
akin to Example 5:

   timing_tool.py -timing stimes.1.txt                   \
                  -partition part1.pred.txt stimes.1.part

Example 15. add a simple linear modulator

For modulation across a run, add the event modulator as the event
time divided by the run length, meaning the fraction the run that
has passed before the event time.

   timing_tool.py -timing stim_times.txt -run_len 300     \
                  -marry_AM lin_run_fraq -write_timing stim_mod.txt

Example 16. use end times to imply event durations

Given timing files A.txt and B.txt, suppose that B always follows A
and that there is no rest between them.  Then the durations of the A
events would be defined by the B-A differences.  To apply durations
to class A events as such, use -apply_end_times_as_durations.

   timing_tool.py -timing A.txt -apply_end_times_as_durations B.txt \
                  -write_timing A_with_durs.txt

Example 17. show duration statistics

Given a timing file with durations, show the min, mean, max and stdev
of the list of event durations.

   timing_tool.py -timing stimes.txt -show_duration_stats

Example 18a. convert FSL formatted timing files to AFNI timing format

A set of FSL timing files (for a single class), one file per run,
can be read using -fsl_timing_files (rather than -timing, say).  At
that point, it internally becomes like a normal timing element.

If the files have varying durations, the result will be in AFNI
duration modulation format.  If the files have amplitudes that are not
constant 0 or constant 1, the result will have amplitude modulators.

   timing_tool.py -fsl_timing_files fsl_r1.txt fsl_r2.txt fsl_r3.txt \
                  -write_timing combined.txt

Example 18b. force to married format, via -write_as_married

timing_tool.py -fsl_timing_files fsl_r1.txt fsl_r2.txt fsl_r3.txt \
               -write_timing combined.txt -write_as_married

Example 18c. apply one FSL run as run 3 of a 4-run timing file

timing_tool.py -fsl_timing_files fsl_r1.txt \
               -select_runs 0 0 1 0 -write_timing NEW.txt

Example 18d. apply two FSL runs as run 3 and 4 of a 5-run timing file

The original runs can be duplicated, put into a new order or omitted.
Also, truncate the event times to 1 place after the decimal (-nplaces),
and similarly truncate the married terms (durations and/or amplitudes)
to 1 place after the decimal (-mplaces).

   timing_tool.py -fsl_timing_files fsl_r1.txt fsl_r2.txt \
                  -nplaces 1 -mplaces 1 -write_as_married \
                  -select_runs 0 0 1 2 0 -write_timing NEW.txt

Example 19a. convert TSV formatted timing files to AFNI timing format

A tab separated value file contains events for all classes for a single
run.  Such files might exist in a BIDS dataset.  Convert a single run
to multiple AFNI timing files (or convert multiple runs).

   timing_tool.py -multi_timing_3col_tsv sing_weather.run*.tsv \
                  -write_multi_timing AFNI_timing.weather

Consider -write_as_married, if useful.

Example 19b. extract ISI/duration/TR stats from TSV files

timing_tool.py -multi_timing_3col_tsv sing_weather.run*.tsv \
               -multi_show_isi_stats -multi_show_duration_stats

timing_tool.py -multi_timing_3col_tsv sing_weather.run*.tsv \
               -tr 2 -show_tr_stats

Example 19c. convert non-standard formatted TSV timing files to AFNI

The default column labels were assumed in the prior examples:
   onset duration trial_type
in this example, RT is used for duration, and participant_response is
used for trial_type.  These TSV files are from the ds001205 dataset from
openneuro.org.

Output is just to an event list.

   timing_tool.py -tsv_labels onset RT participant_response           \
                  -multi_timing_3col_tsv sub-001_task-MGT_run*.tsv    \
                  -write_multi_timing timing.sub-001.C.

Example 19d. as 19c, but include amplitude modulators

Like 19c, but include "gain" and "loss" as amplitude modulators.

   timing_tool.py -tsv_labels onset RT participant_response gain loss \
                  -multi_timing_3col_tsv sub-001_task-MGT_run*.tsv    \
                  -write_multi_timing timing.sub-001.D.

Example 19e. as 19d, but specify the same columns with 0-based indices

timing_tool.py -tsv_labels 0 4 5 2 3                               \
               -multi_timing_3col_tsv sub-001_task-MGT_run*.tsv    \
               -write_multi_timing timing.sub-001.E.

Example 19f. if duration is n/a, specify backup column

In some cases (e.g. as reaction_time), duration might have a value
of "n/a".  Specify an alternate column to use for duration when this
occurs.

   timing_tool.py -tsv_labels onset reaction_time task            \
                  -tsv_def_dur_label duration                     \
                  -multi_timing_3col_tsv s10517-pamenc_events.tsv \
                  -write_multi_timing timing.sub-001.F.

Example 19g. just show the TSV label information

   timing_tool.py -tsv_labels onset reaction_time task            \
                  -tsv_def_dur_label duration                     \
                  -multi_timing_3col_tsv s10517-pamenc_events.tsv \
                  -show_tsv_label_details

Consider "-show_events" to view event list.

Notes:

1. Action options are performed in the order of the options.
   Note: -chrono has been removed.

2. One of -timing or -multi_timing or -fsl_timing_files is required
   for processing.

3. Option -run_len applies to single or multiple stimulus classes.  A single
   parameter would be used for all runs.  Otherwise one duration per run
   should be supplied.

basic informational options:

-help                        : show this help
-help_basis                  : describe various basis functions
-hist                        : show the module history
-show_valid_opts             : show all valid options
-ver                         : show the version number

options with both single and multi versions (all single first):

-timing TIMING_FILE : specify a stimulus timing file to load

e.g. -timing stimesB_01_houses.1D

Use this option to specify a single stimulus timing file.  The user
can modify this timing via some of the action options listed below.
-show_isi_stats
 : display timing and ISI statistics

With this option, the program will display timing statistics for the
single (possibly modified) timing element.

If -tr is included, TR offset statistics are also shown.
-show_timing_ele
 : display info on the main timing element

With this option, the program will display information regarding the
single (possibly modified) timing element.

-stim_dur DURATION : specify the stimulus duration, in seconds

e.g. -stim_dur 3.5

This option allows the user to specify the duration of the stimulus,
as applies to the single timing element.  The only use of this is
in conjunction with -show_isi_stats.

    Consider '-show_isi_stats' and '-run_len'.

-fsl_timing_files F1 F2 … : read a list of FSL formatted timing files

e.g. -fsl_timing_files fsl.s1.run1.txt fsl.s1.run2.txt fsl.s1.run3.txt
e.g. -fsl_timing_files fsl.stim.class.A.run.*.txt

This is essentially an alternative to -timing, as the result is a
single multi-run timing element.

Each input file should have FSL formatted timing for a single run,
and all for the same stimulus class.  Each file should contain a list
of entries like:

    event_time  duration  amplitude

e.g. with varying durations and amplitudes (fully married)

        0         5         3
        17.4      4.6       2.5

e.g. with constant durations and (ignored) amplitudes (so not married)

        0         2         1
        17.4      2         1

e.g. empty (no events)

        0         0         0

If all durations are the same, the result will not have duration
modulators.

If all amplitudes are 0 or all are 1, the result will not have
amplitude modulators.

An empty file or one with a single line of '0 0 0' is considered to
have no events (note that 0 0 0 means duration and amplitude of zero).

Comment lines are okay (starting with #).

    Consider -write_as_married.

-multi_timing FILE1 FILE2 … : specify multiple timing files to load

e.g. -timing stimesB_*.1D

Use this option to specify a list of stimulus timing files.  The user
cannot modify this data, but can display the overall ISI statistics
from it.

Options that pertain to this timing list include:

    -multi_show_isi_stats
    -multi_show_timing_ele
    -multi_stim_dur
    -run_len
    -write_all_rest_times

-multi_timing_3col_tsv FILE1 FILE2 … : read TSV files into multi timing

e.g. -multi_timing_3col_tsv sing_weather_run*.tsv
e.g. -multi_timing_3col_tsv tones.tsv

Tab separated value (TSV) files, as one might find in OpenFMRI data,
are formatted with a possible header line and 3 tab-separated columns:

    onset   duration    stim_class

Timing for all event classes is contained in a single file, per run.
-multi_show_duration_stats
 : display min/mean/max/stdev of durations

Show the minimum, mean, maximum and standard deviation of the list of
all event durations, for each timing element.
-multi_show_isi_stats
 : display timing and ISI statistics

With this option, the program will display timing statistics for the
multiple timing files.

If -tr is included, TR offset statistics are also shown.

If -write_all_rest_times is included, write a file of rest durations.
-multi_show_timing_ele
 : display info on multiple timing elements

With this option, the program will display information regarding the
multiple timing element list.

-multi_stim_dur DUR1 … : specify stimulus duration(s), in seconds

e.g. -multi_stim_dur 3.5
e.g. -multi_stim_dur 3.5 4.5 3

This option allows the user to specify the durations of the stimulus
classes, as applies to the multiple timing elements.  The only use of
this is in conjunction with -multi_show_isi_stats.

If only one duration is specified, it is applied to all elements.
Otherwise, there should be as many stimulus durations as files
specified with -multi_timing.

    Consider '-multi_show_isi_stats' and '-run_len'.

-write_multi_timing PREFIX : write timing instances to new files

e.g. -write_multi_timing MT.

After modifying the timing data, the multiple timing instances
can be written out.

    Consider '-write_as_married'.

action options (apply to single timing element, only):

** Note that these options are processed in the order they are read.

-add_offset OFFSET : add OFFSET to every time in main element

e.g. -add_offset -12.0

Use this option to add a single offset to all of the times in the main
timing element.  For example, if the user deletes 3 4-second TRs from
the EPI data, they may wish to subtract 12 seconds from every stimulus
time, so that the times match the modified EPI data.

    Consider '-write_timing'.

-apply_end_times_as_durations NEW_FILE : compute durations from offsets

e.g. -apply_end_times_as_durations next_events.txt

Treat each NEW_FILE event time as the ending of the corresponding
INPUT (via -timing) event time to create a duration list.  So they
should have the same number of events, and each NEW_FILE time should
be just after the corresponding INPUT time.

    Consider '-write_timing' and '-show_duration_stats'.
    Consider example 16.

-add_rows NEW_FILE : append these timing rows to main element

e.g. -add_rows more_times.1D

Use this option to append rows from NEW_FILE to those of the main
timing element.  If the user then wrote out the result, it would be
identical to using cat: "cat times1.txt times2.txt > both_times.txt".

    Consider '-write_timing'.

-extend NEW_FILE : extend timing rows with those in NEW_FILE

e.g. -extend more_times.1D

Use this option to extend each row (run) with the times in NEW_FILE.
This has an effect similar to that of '1dcat'.  Sorting the times is
optional, done via '-sort'.  Note that 3dDeconvolve does not need the
times to be sorted, though it is more understandable to the user.

    Consider '-sort' and '-write_timing'.

-global_to_local LOCAL_NAME.1D : convert from global timing to local

e.g. -global_to_local local_times.1D

Use this option to convert from global stimulus timing (in a single
column format) to local stimulus timing.  Run durations must be given
of course, to determine which run each stimulus occurs in.  Each
stimulus time will be adjusted to be an offset into the current run,
e.g. if each run is 120 s, a stimulus at time 143.6 would occur in run
#2 (1-based) at time 23.6 s.

    Consider example 9a and options '-run_len' and '-local_to_global'.

-local_to_global GLOBAL_NAME.1D : convert from local timing to global

e.g. -local_to_global global_times.1D

Use this option to convert from local stimulus timing (one row of times
per run) to global stimulus timing (a single column of times across the
runs, where time is considered continuous across the runs).

Run durations must be given of course, to determine which run each
stimulus occurs in.  Each stimulus time will be adjusted to be an
offset from the beginning of the first run, as if there were no breaks
between the runs.
e.g. if each run is 120 s, a stimulus in run #2 (1-based) at time
23.6 s would be converted to a stimulus at global time 143.6 s.

    Consider example 9b and options '-run_len' and '-global_to_local'.

-marry_AM MTYPE : add event modulators based on MTYPE

e.g. -marry_AM lin_run_fraq
e.g. -marry_AM lin_event_index

Use this option to add a simple amplitude modulator to events.
Current modulator types are:

   linear modulators (across events or time):

      lin_event_index   : event index, per run (1, 2, 3, ...)
      lin_run_fraq      : event time, as fractional offset into run
                          (in [0,1])

Non-index modulators require use of -run_len.

    Consider example 15.

-partition PART_FILE PREFIX : partition the stimulus timing file

e.g. -partition partitions.txt new_times

Use this option to partition the input timing file into multiple
timing files based on the labels in a partition file, PART_FILE.
The partition file would have the same number of rows and entries on
each row as the timing file, but would contain labels to use in
partitioning the times into multiple output files.

A label of 0 will cause that timing entry to be dropped.  Otherwise,
each distinct label will have those times put into its timing file.

e.g.

        timing file:
            23.5     46.0     79.3     84.9      116.2
            11.4     38.2     69.7     93.5      121.8

        partition file:
            correct  0        0        incorrect incorrect
            0        correct  0        correct   correct

    ==> results in new_times_good.1D and new_times_bad.1D

        new_times_correct.1D:
            23.5     0        0        0         0
            0        38.2     0        93.5      121.8

        new_times_incorrect.1D:
            0        0        0        84.9      116.2

-round_times FRAC : round times to multiples of the TR

                          0.0 <= FRAC <= 1.0

e.g. -round_times 0.7

All stimulus times will be rounded to a multiple TR, rounding down if
the fraction of the TR that has passed is less than FRAC, rounding up
otherwise.

Using the example of FRAC=0.7, if the TR is 2.5 seconds, then times are
rounded down if they occur earlier than 1.75 seconds into the TR.  So
11.83 would get rounded up to 12.5, while 11.64 would be rounded down
to 10.

FRAC = 1.0 is essentially floor() (as in -truncate_times), while
FRAC = 0.0 is essentially ceil().

This option requires -tr.

    Consider example 7b.  See also -truncate_times.

-scale_data SCALAR : multiply every stim time by SCALAR

e.g. -scale_data 0.975

Use this option to scale (multiply) all times by a single value.
This might be useful in effectively changing the TR, or changing
the stimulus frequency, if it is regular.

    Consider '-write_timing'.
-show_duration_stats
 : display min/mean/max/stdev of durations

Show the minimum, mean, maximum and standard deviation of the list of
all event durations.
-show_timing : display the current single timing data

This prints the current (possibly modified) single timing data to the
terminal.  If the user is making multiple modifications to the timing
data, they may wish to display the updated timing after each step.
-show_tr_stats : display within-TR statistics of stimuli

This displays the mean, max and stdev of stimulus times modulo the TR,
both in seconds and as fractions of the TR.

    See '-warn_tr_stats' for more details.
-show_tsv_label_details
 : display column label info for TSV files

Use this option to display label information for TSV files.  It should
be used in conjunction with -multi_timing_3col_tsv and related options.
-warn_tr_stats : display within-TR stats only for warnings

This is akin to -show_tr_stats, but output is only displayed if there
might be a warning based on the timing.

Warnings occur when the minimum fraction is positive and the maximum
fraction is small (less than -min_frac, 0.3).  If such warnings are
encountered, particularly in the case of TENT basis functions used in
the linear regression, they can affect the X-matrix, essentially
scaling beta #0 by the reciprocal of the fraction (noise dependent).

In such a case the stimuli are almost TR-locked, and the user might be
better off making them exactly TR-locked (by creating new timing files
using "timing_tool.py -round_times").

    See also '-show_tr_stats', '-min_frac' and '-round_times'.
-sort : sort the times, per row (run)

This will cause each row (run) of the main timing element to be
sorted (from smallest to largest).  Such a step may be highly desired
after using '-extend', or after some external manipulation that causes
the times to be unsorted.

Note that 3dDeconvolve does not require sorted timing.

    Consider '-write_timing'.
-test_local_timing
 : test for problems with local timing

The main purpose of this is to test for timing files that are intended
to be interpreted by 3dDeconvolve as being LOCAL TIMES, but might
actually be interpreted as being GLOBAL TIMES.

Note that as of 18 Feb, 2014, any '*' in a timing file will cause it
to be interpreted by 3dDeconvolve as LOCAL TIMES, even if the file is
only a single column.

-timing_to_1D output.1D : convert stim_times format to stim_file

e.g. -timing_to_1D stim_file.1D

This action is used to convert stimulus times to set (i.e. 1) values
in a 1D stim_file.

Besides an input -timing file, -tr is needed to specify the timing grid
of the output 1D file, -stim_dur is needed to specify the duration of
each stimulus (which might cross many output TRs), and -run_len is
needed to specify the duration of each (or all) of the runs.

The -min_frac option may be applied to give a minimum cutoff for the
fraction of a TR occupied by a stimulus required to label that TR as a
1.  If not, the default cutoff is 0.3.

For example, assume options: '-tr 2', '-stim_dur 4.2', '-min_frac 0.2'.
A stimulus at time 9.7 would last until 13.9.  TRs 0..4 would certainly
be 0, TR 5 would also be 0 as the stimulus covers only .15 of the TR
(.3 seconds out of 2 seconds).  TR 6 would be 1 since it is completely
covered, and TR 7 would be 1 since .95 (1.9/2) would be covered.

So the resulting 1D file would start with:


The main use of this operation is for PPI analysis, to partition the
time series (maybe on a fine grid) with 1D files that are 1 when the
given stimulus is on and 0 otherwise.

    Consider -timing_to_1D_warn_ok.
    Consider -tr, -stim_dur, -min_frac, -run_len, -per_run_file.

    Consider example 6a or 6c.
-timing_to_1D_mods
 : write amp modulators to 1D, not binary

For -timing_to_1D, instead of writing a binary 0/1 file, write the
(first) amplitude modulators to the 1D file.

This only applies to -timing_to_1D.
-timing_to_1D_warn_ok
 : make some conversion issues non-fatal

Conditions from -timing_to_1D that this makes non-fatal:

   o  stimuli ending after the end of a run
   o  stimuli overlapping

This only applies to -timing_to_1D.
-transpose : transpose the data (only if rectangular)

This works exactly like 1dtranspose, and requires each row to have
the same number of entries (rectangular data).  The first row would
be swapped with the first column, etc.

    Consider '-write_timing'.
-truncate_times
 : truncate times to multiples of the TR

All stimulus times will be truncated to the largest multiple of the TR
that is less than or equal to each respective time.  That is to say,
shift each stimulus time to the beginning of its TR.

This is particularly important when stimulus times are at a constant
offset into each TR and at the same time using TENT basis functions
for regression (in 3dDeconvolve, say).  The shorter the (non-zero)
offset, the more correlated the first two tent regressors will be,
possibly leading to unpredictable results.

This option requires -tr.

    Consider example 7.
-write_as_married
 : if possible, output in married format

e.g. -write_as_married

If all durations are equal, the default is to not write with duration
modulation (as the constant duration would likely be provided as part
of a basis function).  Use -write_as_married to include any constant
duration as a modulator.

-write_timing NEW_FILE : write the current timing to a new file

e.g. -write_timing new_times.1D

After modifying the timing data, the user will probably want to write
out the result.  Alternatively, the user could use -show_timing and
cut-and-paste to write such a file.

    Consider '-write_as_married'.

action options (apply to multi timing elements, only):

-multi_timing_to_events FILE : create event list from stimulus timing

e.g. -multi_timing_to_events all.events.txt

Decide which TR each stimulus event belongs to and make an event file
(of TRs) containing a sequence of values between 0 (no event) and N
(the index of the event class, for the N timing files).

This option requires -tr, -multi_stim_dur, -min_frac and -run_len.

   Consider example 8.

-multi_timing_to_event_pair Efile Ifile : break event file into 2 pieces

e.g. -multi_timing_to_event_pair events.txt isi.txt

Similar to -multi_timing_to_events, but break the output event file
into 2 pieces, an event list and an ISI list.  Each event E followed by
K zeros in the previous events file would be broken into a single E (in
the new event file) and K+1 (in the ISI file).  Note that K+1 is
appropriate from the assumption that events are 0-duration.  The ISI
entries should sum to the total number of TRs per run.

Suppose the event file shows 2 TRs of rest, event type 3 followed by 4
TRs of rest, event type 1 followed by 1 TR of rest, type 2 and no rest,
type 2 and 3 TRs of rest.  So it would read:

   all events:  0 0 3 0 0 0 0 1 0 2 2 0 0 0 ...

Then the event_pair files would read:

   events:      0 3 1 2 2 ...
   ISIs:        2 5 2 1 4 ...

Note that the only 0 events occur at the beginnings of runs.
Note that the ISI is always at least 1, for the TR of the event.

This option requires -tr, -multi_stim_dur, -min_frac and -run_len.

   Consider example 8b.

-multi_timing_to_event_list STYLE FILE : make an event list file

  e.g. -multi_timing_to_event_list index events.txt
  e.g. -multi_timing_to_event_list GE:itodf event.list.txt

  Similar to -multi_timing_to_events, but make a more simple event list
  that does not require knowing the TR or run lengths.

  The output is written to FILE, where 'stdout' or '-' mean to write to
  the terminal window.

  The information and format is specified by the STYLE field:

     index        : write event index classes, in order, one row per run

     part         : partition the first class of events according to the
                    predecessor classes - the output is a list of class
                    indices for events the precede those of the first
                    class
                    (this STYLE is esoteric, written for W Tseng)

     GE:TYPE      : write a vertical list of events, according to TYPE

        TYPE is a list comprised of the following specifiers, where
        column output is in order specified (e.g. if i comes first, then
        the first column of output will be the class index).

           i : event class index
           p : previous event class index
           t : event onset time
           d : event duration
           o : offset from previous event (including previous duration)
           f : event class file name

* note: -show_events is short for '-multi_timing_to_event_list GE:ALL -'
  See also -show_events.

general options:

-chrono : process options chronologically

This option has been removed.

-min_frac FRAC : specify minimum TR fraction

e.g. -min_frac 0.1

This option applies to either -timing_to_1D action or -warn_tr_stats.

For -warn_tr_stats (or -show), if the maximum tr fraction is below this
limit, TRs are considered to be approximately TR-locked.

For -timing_to_1D, when a random timing stimulus is converted to part
of a 0/1 1D file, if the stimulus occupies at least FRAC of a TR, then
that TR gets a 1 (meaning it is "on"), else it gets a 0 ("off").

FRAC is required to be within [0,1], though clearly 0 is not very
useful.  Also, 1 is not recommended unless that TR can be stored
precisely as a floating point number.  For example, 0.1 cannot be
stored exactly, so 0.999 might be safer to basically mean 1.0.

    Consider -timing_to_1D.

-part_init NAME : specify a default partition NAME

e.g.     -part_init 2
e.g.     -part_init frogs
default: -part_init INIT

This option applies to '-multi_timing_to_event_list part'.  In the
case of generating a partition based on the previous events, this
option allow the user to specify the partition class to be used when
the class in question comes first (i.e. there is no previous event).

The default class is the label INIT (the other classes will be
small integers, from 1 to #inputs).

-nplaces NPLACES : specify # decimal places used in printing

e.g. -nplaces 1

This option allows the user to specify the number of places to the
right of the decimal that are used when printing a stimulus time
(to the screen via -show_timing or to a file via -write_timing).
The default is -1, which uses the minimum needed for accuracy.

    Consider '-show_timing' and '-write_timing'.

-mplaces NPLACES : specify # places used for married fields

e.g. -mplaces 1

Akin to -nplaces, this option controls the number of places to the
right of the decimal that are used when printing stimulus event
modulators (amplitude and duration modulators).
The default is -1, which uses the minimum needed for accuracy.

    Consider '-nplaces', '-show_timing' and '-write_timing'.

-select_runs OLD1 OLD2 … : make new timing from runs of an old one

example a: Convert a single run into the second of 4 runs.

   -select_runs 0 1 0 0

example b: Get the last 2 runs out of a 4-run timing file.

   -select_runs 3 4

example c: Reverse the order of a 4 run timing file.

   -select_runs 4 3 2 1

example d: Make a 6 run timing file, where they are all the same
           as the original run 2, except the new run 4 is empty.

   -select_runs 2 2 2 0 2 2

example e: Convert 3 runs into positions 4, 5 and 2 of 5 runs.
           So 1 -> posn 4, 2 -> posn 5, and 3 -> posn 2.
           The other 2 runs are empty.

   -select_runs 0 3 0 1 2


Use this option to create a new timing element by selecting runs of an
old one.  Runs are 1-based (from 1 to #runs), and 0 means to use an
empty run (no events).  For example, if the original timing element has
5 runs, then use 1..5 to select them, and 0 to select an empty run.

Original runs can be any number of times, and in any order.

The number of runs in the result is equal to the number of runs
listed as parameters to this option.

    Consider '-nplaces', '-show_timing' and '-write_timing'.
-per_run : perform relevant operations per run

e.g. -per_run

This option applies to -timing_to_1D, so that each 0/1 array is
one row per run, as opposed to a single column across runs.
-per_run_file : per run, but output multiple files

e.g. -per_run_file

This option applies to -timing_to_1D, so that the 0/1 array goes in a
separate file per run.  With -per_run, each run is just a separate row.

-run_len RUN_TIME … : specify the run duration(s), in seconds

e.g. -run_len 300
e.g. -run_len 300 320 280 300

This option allows the user to specify the duration of each run.
If only one duration is provided, it is assumed that all runs are of
that length of time.  Otherwise, the user must specify the same number
of runs that are found in the timing files (one run per row).

This option applies to both -timing and -multi_timing files.

The run durations only matter for displaying ISI statistics.

    Consider '-show_isi_stats' and '-multi_show_isi_stats'.
-show_events : see -multi_timing_to_event_list GE:ALL -

This option, since it is so useful, it shorthand for

    -multi_timing_to_event_list GE:ALL -

This option works for both -timing and -multi_timing.
It is terminal.

See also -multi_timing_to_event_list.

-tr TR : specify the time resolution in 1D output

                          (in seconds)
e.g. -tr 2.0
e.g. -tr 0.1

For any action that write out 1D formatted data (currently just the
-timing_to_1D action), this option is used to set the temporal
resolution of the data.  For example, given -run_len 200 and -tr 0.5,
one run would be 400 time points.

    Consider -timing_to_1D and -run_len.

-tsv_labels L1 L2 … : specify column labels for TSV files

e.g.     -tsv_labels onset RT response
e.g.     -tsv_labels onset RT response gain loss
e.g.     -tsv_labels 0 4 5 2 3
default: -tsv_labels onset duration trial_type

Use this option to specify columns to be used for:

   stimulus onset time
   stimulus duration
   stimulus class
   optionally: any amplitude modulators ...

TSV (tab separated value) event timing files typically have column
headers, including stimulus timing information such as event onset
time, duration, stimulus type, response time, etc.  Unless specified,
the default column headers that are processed are:

    onset duration trial_type

But in some cases they do not exist, so the user must specify alternate
headers (or indices).

Columns can be specified by labels, or 0-based indices.

-verb LEVEL : set the verbosity level

e.g. -verb 3

This option allows the user to specify how verbose the program is.
The default level is 1, 0 is quiet, and the maximum is (currently) 4.
-write_all_rest_times
 : write all rest durations to ‘timing’ file

        e.g. -write_all_rest_times all_rest.txt

        In the case of a show_isi_stats option, the user can opt to save all
        rest (pre-stim, isi, post-stim) durations to a timing-style file.  Each
        row (run) would have one more entry than the number of stimuli (for
        pre- and post- rest).  Note that pre- and post- might be 0.

R Reynolds    December 2008