* NAME
NAME
zil_soas.pl - parses DMDX input and .zil files to output times in TRs
If you have an input file myexp.rtf, and an output file my_exp.zil in the same directory. You want the stim / response times from the second subject. The first 6 scans were dummy scans, and the pulse from the scanner occurs at the beginning of the scan. The subjects potential responses were button press 1 (+Bit0 in DMDX), and button press 2.
zil_soas.pl myexp.zil -subject 2 -dummies 6 -pdelay 0 -respstr +Bit0 -respstr +Bit1
will output the stimulus and response times in TRs relative to the onset of the first non-dummy scan, as a text file myexp_sub2.txt
See ZilUtility for more information.
Note: requires RTF::Parser, available via CPAN: http://search.cpan.org/author/PVERD/RTF-Parser-1.07/
DESCRIPTION
zil_soas.pl takes a DMDX .rtf input file, and an output .zil file, and outputs the recorded stimulus and response events in terms of TRs for use - in particular - with SPM.
FEATURES
zil_soas parses the rtf and zil files to estimate the onset times of the first event relative to the beginning of the experiment. It uses scanner pulses recorded in the zil file to calculate a best estimate of the TR, if required. Outputs are text files for each subject in the zil file, specifying stimulus and response times in terms of the beginning of the first non-dummy TR.
SYNOPSIS
zil_soas.pl [options] input_file.zil
Options:
-help print help message and quit
-man full documentation and quit
-verbose more messages, more detailed help output
-quiet no messages during operation
-clobber overwrite preexisting files
-rtf specify input rtf file
-subject one or more subjects to convert
-all convert all subjects
-outdir directory to output files
-outroot root name of files to output
-pdelay time (ms) from start of scan to pulse
-tr TR (usually calculated)
-esttr starting guess for TR if calculated
-limit margin by which estimated TR may be incorrect
-tol allowable error in ms for estimated TR
-misstrs TRs to miss (any spacebar events, preceding pulses)
-dummies dummy scans
-scanpulses strings defining scan pulse events
-respstrs strings defining responses
-omititem item numbers to omit
-nullval string to signal null value
-version returns version no
OPTIONS
- -help
- Print a long help message and exit.
- -man
- Prints the manual page and exit.
- -verbose
- Gives out moderately helpful warning and other messages during image conversion. Adding -verbose to -help outputs more help.
- -rtf
Specify input rtf file. If not specified, the rtf file is assumed to have the same name (and directory) as the .zil file. If this is not correct, use the rtf option thus: zil_soas.pl myexp.zil -rtf ../myexp.rtf
- -showvals
- Prints out the output of stimulus, response times to the screen for review
- -quiet
- Turn off any messages during conversion
- -clobber
Will overwrite preexisting files. If there are preexisting files, and you do not use -clobber, will exit with an error message.
- -subject
- Specify to convert, e.g. zil_soas.pl myexp.zil -subject 1 -subject 3 will convert subject 1 and 3 only. Defaults to all subjects if not set.
- -all
- Convert all subjects in the file. This is the default.
- -outdir
Directory to output files to; e.g. zil_soas.pl myexp.zil -all -outdir /home/me/exp_onsets The default output directory is the current directory.
- -outroot
- Root name of files to output (extension ignored); e.g.
zil_soas.pl myexp.zil -subject 1 -subject 2 -outname myfile will create output files: ./myfile_sub1.txt ./myfile_sub2.txt. zil_soas derives the default file name from the name of the input data file. Thus zil_soas.pl myexp.zil -subject 1 will generate files: ./myexp_sub1.txt
- -pdelay
- Sets delay in onset of scanner pulse after the start of the TR. Value is in milliseconds. For example, if the TR is 3 seconds, and the pulse is right at the end to fthe TR, and lasts 50 ms, then the command line might be: zil_soas.pl myexp.zil -subject 1 -pdelay 2950
- -tr
- Set the exact TR (in milliseconds) by hand, rather than calculating from the .zil file - e.g.: zil_soas.pl myexp.zil -subject 1 -tr 3000
- -esttr
- Give starting estimate for TR, to help in calculating the correct TR, e.g.: zil_soas.pl myexp.zil -subject 1 -esttr 3000
- -limit
- Give limits within which to search for exact TR; for example: zil_soas.pl myexp.zil -subject 1 -esttr 3000 -limit 100 will search between 2900 and 3100 for the best TR. Default is 200.
- -tol
- Required accuracy of TR estimate in ms. For example: zil_soas.pl myexp.zil -subject 1 -esttr 3000 -tol 0.1 will allow a 100 microsecond error in the TR estimate. Default is 0.05;
- -misstrs
- Sometimes, you may wish to start the experiment with one or more spacebar presses, rather than letting the scanner trigger the start of the experiment; this will show up as extra '0' events in your DMDX file which do not correspond to a scanner pulse. You can tell the program not to treat these intial '0' events as a pulse using this option, e.g.: zil_soas.pl myexp.zil -subject 1 -misstrs 1
- -dummies
- A scanning session usually begins with several dummy scans. The TR values needed for the analysis are in relation to the beginning of the first non-dummy TR (where 0 = the beginning the the first TR). Use this option to set the number of dummy scans and therefore the number of TRs to subtract from the TR values in the output file, relative to the start of the experiment: zil_soas.pl myexp.zil -subject 1 -dummies 6
- -scanpulses
- Strings in the zil file signifying scanner pulse events - onset, offset or both. For example, if the scanner pulse is recorded as 'Bit1' in the zil file, use: zil_soas.pl myexp.zil -subject 1 -scanpulses +Bit1 -scanpulses -Bit1
The default corresponds to -scanpulses +Bit0 -scanpulses -Bit0
- -respstrs
- Strings in the zil file signifying response events. For example, if the response can be on button 1 or button 2, and these are recorded as '+Bit2' and '+Bit3' in the zil file, use: zil_soas.pl myexp.zil -subject 1 -respstrs +Bit2 -respstrs +Bit3
The default corresponds to -respstrs +Bit1
- -omititem
- Event numbers in the DMDX file which should not be noted in the output file. For example, you might not want to model the onset of a fixation cross in the output file, and you may have signalled this in your DMDX file by giving the fixation cross and event number of 1000. In this case, to omit these events from the output: zil_soas.pl myexp.zil -subject 1 -omititem 1000 You can specify more than one number to omit, with several repeats: e.g. zil_soas.pl myexp.zil -subject 1 -omititem 1000 -omititem 2000
- -nullval
- String / number to signal null value in the output file. Default is 'NaN' for use with matlab. If you prefer (e.g.) 0: zil_soas.pl myexp.zil -subject 1 -nullval 0
- -version
- Returns version no to the console.