AFNI program: timing_tool.py
Output of -help
=============================================================================
timing_tool.py - for manipulating and evaluating stimulus timing files
(-stim_times format: where each row is a separate run)
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 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)
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:
0. Basic commands:
timing_tool.py -help
timing_tool.py -hist
timing_tool.py -show_valid_opts
timing_tool.py -ver
1. Combine the timing of 2 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
2. Subtract 12 seconds from each stimulus time (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
3. 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
4. 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
--------------------------------------------------------------------------
Notes:
1. Action options are performed in the order of the options. If
the -chrono option is given, everything (but -chrono) is.
2. Either -timing or -multi_timing is required for processing.
3. Option -run_len applies to single or multiple stimulus classes.
--------------------------------------------------------------------------
basic informational options:
-help : show this help
-hist : show the module history
-show_valid_opts : show all valid options
-ver : show the version number
------------------------------------------
single/multiple timing options:
-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.
-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'.
--------------------
-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
-multi_show_isi_stats : display timing and ISI statistics
With this option, the program will display timing statistics for the
multiple timing files.
-multi_show_timing_ele : display info on the multiple timing elements
With this option, the program will display information regarding the
multiple timing element list.
-multi_stim_dur DUR1 ... : specify the 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'.
------------------------------------------
action options (apply to single timing element, only):
** Note that these options are processed in the order they are read.
See '-chrono' for similar notions.
-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 modifed EPI data.
Consider '-write_timing'.
-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 the 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'.
-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.
-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'.
-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'.
-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.
------------------------------------------
general options:
-chrono : process options chronologically
While the action options are already processed in order, general and
-timing options are not, unless the chrono option is given. This
allows one to do things like scripting a sequence of operations
within a single command.
-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 3.
Consider '-show_timing' and '-write_timing'.
-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'.
-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.
-----------------------------------------------------------------------------
R Reynolds December 2008
=============================================================================
This page auto-generated on
Fri Jan 30 20:02:52 EST 2009