AFNI program: make_random_timing.py
Output of -help
===========================================================================
Create random stimulus timing files.
The object is to create a set of random stimulus timing files, suitable
for use in 3dDeconvolve. These times will not be TR-locked (unless the
user requests it). Stimulus presentation times will never overlap, though
their responses can.
This can easily be used to generate many sets of random timing files to
test via "3dDeconvolve -nodata", in order to determine good timing, akin
to what is done in HowTo #3 using RSFgen. Note that the -save_3dd_cmd
can be used to create a sample "3dDeconvolve -nodata" script.
given:
num_stim - number of stimulus classes
num_runs - number of runs
num_reps - number of repetitions for each class (same each run)
stim_dur - length of time for each stimulus, in seconds
run_time - total amount of time, per run
pre_stim_rest - time before any first stimulus (same each run)
post_stim_rest - time after last stimulus (same each run)
This program will create one timing file per stimulus class, num_runs lines
long, with num_stim stimulus times per line.
Time for rest will be run_time minus all stimulus time, and can be broken
into pre_stim_rest, post_stim_rest and randomly distributed rest. Consider
the sum, assuming num_reps and stim_dur are constant (per run and stimulus
class).
num_stim * num_reps * stim_dur (total stimulus duration for one run)
+ randomly distributed rest (surrounding stimuli)
+ pre_stim_rest
+ post_stim_rest (note: account for response time)
-----------
= run_time
Other controlling inputs include:
across_runs - distribute num_reps across all runs, not per run
min_rest - time of rest to immediately follow each stimulus
(this is internally added to stim_dur)
seed - optional random number seed
t_gran - granularity of time, in seconds (default 0.1 seconds)
tr_locked - make all timing locked with the accompanying TR
The internal method used is similar to that of RSFgen. For a given run, a
list of num_reps stimulus intervals for each stimulus class is generated
(each interval is stim_dur seconds). Appended to this is a list of rest
intervals (each of length t_gran seconds). This accounts for all time
except for pre_stim_rest and post_stim_rest.
This list (of numbers 0..num_stim, where 0 means rest) is then randomized.
Timing comes from the result.
Reading the list (still for a single run), times are accumulated, starting
with pre_stim_rest seconds. As the list is read, a 0 means add t_gran
seconds to the current time. A non-zero value means the given stimulus
type occurred, so the current time goes into that stimulus file and the
time is incremented by stim_dur seconds.
* Note that stimulus times will never overlap, though response times can.
* The following options can be specified as one value or as a list:
-run_time : time for each run, or a list of run times
-stim_dur : duration of all stimuli, or a list of every duration
-num_reps : nreps for all stimuli, or a list of nreps for each
Note that varying these parameters can lead to unbalanced designs. Use
the list forms with caution.
Currently, -pre_stim_rest and -post_stim_rest cannot vary over runs.
----------------------------------------
getting TR-locked timing
If TR-locked timing is desired, it can be enforced with the -tr_locked
option, along with which the user must specify "-tr TR". The effect is
to force stim_dur and t_gran to be equal to (or a multiple of) the TR.
It is illegal to use both -tr_locked and -t_gran (since -tr is used to
set t_gran).
----------------------------------------
distributing stimuli across all runs at once (via -across_runs)
The main described use is where there is a fixed number of stimlus events
in each run, and of each type. The -num_reps option specifies that number
(or those numbers). For example, if -num_reps is 8 and -num_runs is 4,
each stimulus class would have 8 repetitions in each of the 4 runs (for a
total of 32 repetitions).
That changes if -across_runs is applied.
With the addition of the -across_runs option, the meaning of -num_reps
changes to be the total number of repetitions for each class across all
runs, and the randomization changes to occur across all runs. So in the
above example, with -num_reps equal to 8, 8 stimluli (of each class) will
be distributed across 4 runs. The average number of repetitions per run
would be 2.
In such a case, note that it would be possible for some runs not to have
any stimuli of a certain type.
----------------------------------------------------------------------
examples:
1. Create a timing file for a single stimulus class for a single run.
The run will be 100 seconds long, with (at least) 10 seconds before
the first stimulus. The stimulus will occur 20 times, and each lasts
1.5 seconds.
The output will be written to 'stimesA_01.1D'.
make_random_timing.py -num_stim 1 -num_runs 1 -run_time 100 \
-stim_dur 1.5 -num_reps 20 -pre_stim_rest 10 -prefix stimesA
2. A typical example.
Make timing files for 3 stim classes over 4 runs of 200 seconds. Every
stimulus class will have 8 events per run, each lasting 3.5 seconds.
Require 20 seconds of rest before the first stimulus in each run, as
well as after the last.
Also, add labels for the 3 stimulus classes: houses, faces, donuts.
They will be appended to the respective filenames. And finally, display
timing statistics for the user.
The output will be written to stimesB_01.houses.1D, etc.
make_random_timing.py -num_stim 3 -num_runs 4 -run_time 200 \
-stim_dur 3.5 -num_reps 8 -prefix stimesB \
-pre_stim_rest 20 -post_stim_rest 20 \
-stim_labels houses faces donuts \
-show_timing_stats
Consider adding the -save_3dd_cmd option.
3. Distribute stimuli over all runs at once.
Similar to #2, but distribute the 8 events per class over all 4 runs.
In #2, each stim class has 8 events per run (so 24 total events).
Here each stim class has a total of 8 events. Just add -across_runs.
make_random_timing.py -num_stim 3 -num_runs 4 -run_time 200 \
-stim_dur 3.5 -num_reps 8 -prefix stimesC \
-pre_stim_rest 20 -post_stim_rest 20 \
-across_runs -stim_labels houses faces donuts
4. TR-locked example.
Similar to #2, but make the stimuli TR-locked. Set the TR to 2.0
seconds, along with the length of each stimulus event. This adds
options -tr_locked and -tr, and requires -stim_dur to be a multiple
(or equal to) the TR.
make_random_timing.py -num_stim 3 -num_runs 4 -run_time 200 \
-stim_dur 2.0 -num_reps 8 -prefix stimesD \
-pre_stim_rest 20 -post_stim_rest 20 -tr_locked -tr 2.0
5. Esoteric example.
Similar to #2, but require an additional 0.7 seconds of rest after
each stimulus (exactly the same as adding 0.7 to the stim_dur), set
the granularity of random sequencing to 0.001 seconds, apply a random
number seed of 31415, and set the verbose level to 2.
Save a 3dDeconvolve -nodata command in @cmd.3dd .
make_random_timing.py -num_stim 3 -num_runs 4 -run_time 200 \
-stim_dur 3.5 -num_reps 8 -prefix stimesE \
-pre_stim_rest 20 -post_stim_rest 20 \
-min_rest 0.7 -t_gran 0.001 -seed 31415 -verb 2 \
-show_timing_stats -save_3dd_cmd @cmd.3dd
6. Example with varying number of events, durations and run times.
** Note that this does not make for a balanced design.
Similar to #2, but require each stimulus class to have a different
number of events. Class #1 will have 8 reps per run, class #2 will
have 10 reps per run and class #3 will have 15 reps per run. The
-num_reps option takes either 1 or -num_stim parameters. Here, 3
are supplied.
make_random_timing.py -num_stim 3 -num_runs 4 \
-run_time 200 190 185 225 \
-stim_dur 3.5 4.5 3 -num_reps 8 10 15 \
-pre_stim_rest 20 -post_stim_rest 20 \
-prefix stimesF
7. Catch trials.
If every time a main stimulus 'M' is presented it must follow another
stimulus 'C', catch trials can be used to separate them. If the TRs
look like ...CM.CM.....CM...CMCM, it is hard to separate the response
to M from the response to C. When separate C stimuli are also given,
the problem becomes simple : C..CM.CM...C.CM...CMCM. Now C and M can
be measured separately.
In this example we have 4 8-second main classes (A1, A2, B1, B2) that
always follow 2 types of 8-second catch classes (A and B). The times
of A1 are always 8 seconds after the times for A, for example.
Main stimuli are presented 5 times per run, and catch trials are given
separately an additional 4 times per run. That means, for example, that
stimulus A will occur 14 times per run (4 as 'catch', 5 preceeding A1,
5 preceeding A2). Each of 3 runs will last 9 minutes.
Initially we will claim that A1..B2 each lasts 16 seconds. Then each of
those events will be broken into a 'catch' event at the beginning,
followed by a 'main' event after another 8 seconds. Set the minumum
time between any 2 events to be 1.5 seconds.
Do this in 3 steps:
a. Generate stimulus timing for 6 classes: A, B, A1, A2, B1, B2.
Stim lengths will be 8, 8, and 16, 16, 16, 16 seconds, at first.
Note that both the stimulus durations and frequencies will vary.
make_random_timing.py -num_stim 6 -num_runs 3 -run_time 540 \
-stim_dur 8 8 16 16 16 16 -num_reps 4 4 5 5 5 5 \
-stim_labels A B A1 A2 B1 B2 -min_rest 1.5 -seed 54321 \
-prefix stimesG
b. Separate 'catch' trials from main events. Catch trails for A will
occur at the exact stim times of A1 and A2. Therefore all of our
time for A/A1/A2 are actually times for A (and similarly for B).
Concatenate the timing files and save them.
1dcat stimesG_??_A.1D stimesG_??_A?.1D > stimesG_A_all.1D
1dcat stimesG_??_B.1D stimesG_??_B?.1D > stimesG_B_all.1D
c. To get stim times for the 'main' regressors we need to add 8
seconds to every time. Otherwise, the times will be identical to
those in stimesG.a_03_A?.1D (and B).
There are many ways to add 8 to the timing files. In this case,
just run the program again, with the same seed, but add an offset
of 8 seconds to all times. Then simply ignore the new files for
A and B, while keeping those of A1, A2, B1 and B2.
Also, save the 3dDeconvolve command to run with -nodata.
make_random_timing.py -num_stim 6 -num_runs 3 -run_time 540 \
-stim_dur 8 8 16 16 16 16 -num_reps 4 4 5 5 5 5 \
-stim_labels A B A1 A2 B1 B2 -min_rest 1.5 -seed 54321 \
-offset 8.0 -save_3dd_cmd @cmd.3dd.G -prefix stimesG
d. Finally, fix the 3dDeconvolve command in @cmd.3dd.G.
1. Use the timing files stimesG_A_all.1D and stimesG_B_all.1D from
step b, replacing files stimesG_01_A.1D and stimesG_01_B.1D.
2. Update the stimulus durations of A1, A2, B1 and B2 from 16
seconds to the correct 8 seconds (the second half of the 16
second intervals).
This is necessary because the command in step (c) does not know
about the updated A/B files from step (b). The first half of each
16 second A1/A2 stimulus is actually stimulus A, while the second
half is really A1 or A2. Similarly for B.
The resulting files are kept (and applied in and 3dDeconvolve commands):
stimesG_[AB]_all.1D : the 'catch' regressors, 14 stimuli per run
(from step b)
stimesG_*_[AB][12].1D : the 4 main regressors (at 8 sec offsets)
(from step c)
--- end of (long) example #7 ---
----------------------------------------------------------------------
informational arguments:
-help : display this help
-hist : display the modification history
-show_valid_opts : display all valid options (short format)
-ver : display the version number
----------------------------------------
required arguments:
-num_runs NRUNS : set the number of runs
e.g. -num_runs 4
Use this option to specify the total number of runs. Output timing
files will have one row per run (for -local_times in 3dDeconvolve).
-run_time TIME : set the total time, per run (in seconds)
e.g. -run_time 180
e.g. -run_time 180 150 150 180
This option specifies the total amount of time per run, in seconds.
This time includes all rest and stimulation. This time is per run,
even if -across_runs is used.
-num_stim NSTIM : set the number of stimulus classes
e.g. -num_stim 3
This specifies the number of stimulus classes. The program will
create one output file per stimulus class.
-num_reps REPS : set the number of repetitions (per class?)
e.g. -num_reps 8
e.g. -num_reps 8 15 6
This specifies the number of repetitions of each stimulus type, per run
(unless -across_runs is used). If one parameter is provided, every
stimulus class will be given that number of repetitions per run (unless
-across_runs is given, in which case each stimulus class will be given
a total of that number of repetitions, across all runs).
The user can also specify the number of repetitions for each of the
stimulus classes separatly, as a list.
see also: -across_runs
-prefix PREFIX : set the prefix for output filenames
e.g. -prefix stim_times
--> might create: stim_times_001.1D
The option specifies the prefix for all output stimulus timing files.
The files will have the form: PREFIX_INDEX[_LABEL].1D, where PREFIX
is via this option, INDEX is 01, 02, ... through the number of stim
classes, and LABEL is optionally provided via -stim_labels.
Therefore, output files will be sorted alphabetically, regardless of
any labels, in the order that they are given to this program.
see also -stim_labels
-show_timing_stats : show statistics from the timing
e.g. -show_timing_stats
If this option is set, the program will output statistical information
regarding the stimulus timing, and on ISIs (inter-stimulus intervals)
in particular. One might want to be able to state what the min, mean,
max and stdev of the ISI are.
-stim_dur TIME : set the duration for a single stimulus
e.g. -stim_dur 3.5
e.g. -stim_dur 3.5 1.0 4.2
This specifies the length of time taken for a single stimulus, in
seconds. These stimulation intervals never overlap (with either rest
or other stimulus intervals) in the output timing files.
If a single TIME parameter is given, it applies to all of the stimulus
classes. Otherwise, the user can provide a list of durations, one per
stimulus class.
----------------------------------------
optional arguments:
-across_runs : distribute stimuli across all runs at once
e.g. -across_runs
By default, each of -num_stim stimuli are randomly distributed within
each run separately, per class. But with the -across_runs option,
these stimuli are distributed across all runs at once (so the number
of repetitions per run will vary).
For example, using -num_stim 2, -num_reps 24 and -num_runs 3, assuming
-across_runs is _not_used, there would be 24 repetitions of each stim
class per run (for a total of 72 repetitions over 3 runs). However, if
-across_runs is applied, then there will be only the 24 repetitions
over 3 runs, for an average of 8 per run (though there will probably
not be exactly 8 in every run).
-min_rest REST_TIME : specify extra rest after each stimulus
e.g. -min_rest 0.320
--> would add 320 milliseconds of rest after each stimulus
There is no difference between applying this option and instead
adding the REST_TIME to that of each regressor. It is merely another
way to partition the stimulus time period.
For example, if each stimulus lasts 1.5 seconds, but it is required
that at least 0.5 seconds separates each stimulus pair, then there
are 2 equivalent ways to express this:
A: -stim_dur 2.0
B: -stim_dur 1.5 -min_rest 0.5
These have the same effect, but perhaps the user wants to keep the
terms logically separate.
However the program simply adds min_rest to each stimulus length.
-offset OFFSET : specify an offset to add to every stim time
e.g. -offset 4.5
Use this option to offset every stimulus time by OFFSET seconds.
-pre_stim_rest REST_TIME : specify minimum rest period to start each run
e.g. -pre_stim_rest 20
Use this option to specify the amount of time that should pass at
the beginning of each run before the first stimulus might occur.
The random placing of stimuli and rest will occur after this time in
each run.
As usual, the time is in seconds.
-post_stim_rest REST_TIME : specify minimum rest period to end each run
e.g. -post_stim_rest 20
Use this option to specify the amount of time that should pass at
the end of each run after the last stimulus might occur.
One could consider using -post_stim_rest of 12.0, always, to account
for the decay of the BOLD response after the last stimulus period ends.
Note that the program does just prevent a stimulus from starting after
this time, but the entire stimulation period (described by -stim_dur)
will end before this post_stim_rest period begins.
For example, if the user provides "-run_time 100", "-stim_dur 2.5"
and "-post_stim_rest 15", then the latest a stimulus could possibly
occur at is 82.5 seconds into a run. This would allow 2.5 seconds for
the stimulus, plus another 15 seconds for the post_stim_rest period.
-save_3dd_cmd FILENAME : save a 3dDeconvolve -nodata example
e.g. -save_3dd_cmd sample.3dd.command
Use this option to save an example of running "3dDeconvolve -nodata"
with the newly created stim_times files. The saved script includes
creation of a SUM regressor (if more than one stimulus was given) and
a suggestion of how to run 1dplot to view the regressors created from
the timing files.
The use of the SUM regressor is to get a feel for what the expected
response might look at a voxel that response to all stimulus classes.
If, for example, the SUM never goes to zero in the middle of a run,
one might wonder whether it is possible to accurately separate each
stimulus response from the baseline.
-seed SEED : specify a seed for random number generation
e.g. -seed 3141592
This option allows the user to specify a seed for random number
generation in the program. The main reason to do so is to be able
to duplicate results.
By default, the seed is based on the current system time.
-stim_labels LAB1 LAB2 ... : specify labels for the stimulus classes
e.g. -stim_labels houses faces donuts
Via this option, one can specify labels to become part of the output
filenames. If the above example were used, along with -prefix stim,
the first stimulus timing would be written to stim_01_houses.1D.
The stimulus index (1-based) is always part of the filename, as that
keeps the files alphabetical in the order that the stimuli were
specified to the program.
There must be exactly -num_stim labels provided.
-t_digits DIGITS : set the number of decimal places for times
e.g. -t_digits 3
Via this option one can control the number of places after the
decimal that are used when writing the stimulus times to each output
file.
The default is 1, printing times in tenths of a second. But if a
higher time granularity is requested via -t_gran, one might want
more places after the decimal.
Note that if a user-supplied -t_gran does not round to a tenth of a
second, the default t_digits changes to 3, to be in milliseconds.
-t_gran GRANULARITY : set the time granularity
e.g. -t_gran 0.001
The default time granularity is 0.1 seconds, and rest timing is
computed at that resolution. This option can be applied to change
the resolution. There are good reasons to go either up or down.
One might want to use 0.001 to obtain a temporal granularity of a
millisecond, as times are often given at that resolution.
Also, one might want to use the actual TR, such as 2.5 seconds, to
ensure that rest and stimuli occur on the TR grid. Note that such a
use also requires -stim_dur to be a multiple of the TR.
-tr TR : set the scanner TR
e.g. -tr 2.5
The TR is needed for the -tr_locked option (so that all times are
multiples of the TR), and for the -save_3dd_cmd option (the TR must
be given to 3dDeconvolve).
see also: -save_3dd_cmd, -tr_locked
-verb LEVEL : set the verbose level
e.g. -verb 2
The default level is 1, and 0 is consider 'quiet' mode, only reporting
errors. The maximum level is currently 4.
- R Reynolds May 7, 2008 motivated by Ikuko Mukai
===========================================================================
This page auto-generated on
Fri Jan 30 20:02:48 EST 2009