**fScan Reference Manual, Chapter 2 (CmdLineOptions): reference**
===== Reference -- Specify timing information=====
== usage: -reference length LENG1 LENG2 ... labels LABEL1 LABEL2 ... delay DELAYTIME skip SKIPTIME (etc.) ==
==== ====
REFERENCE has many modifiers, which can be combined in a single -ref command or listed in separate -ref commands within a single command line. The "usage" line above shows only a few common modifiers. Arguments in lower case are reserved words entered as shown (or abbreviated); arguments in upper case are numbers or names that you supply.\\
**The complete option list is:**\\
-reference labels LABEL1 LABEL2 ...\\
-reference codes CODE1 CODE2 ...\\
-reference length LENG1 LENG2 ...\\
-reference skip SKIPTIME\\
-reference delay DELAYTIME\\
-reference total TOTALTIME\\
-reference bin BINSIZE\\
-reference offset OFFSETTIME\\
-reference cycles\\
-reference events\\
-reference starts\\
-reference hrf LATENCY\\
-reference hrf LATENCY TRANSITION\\
-reference hrf LATENCY RISE WIDTH FALL [UNDERSHOOT RECOVERY]\\
-reference hrf LATENCY DIP DEPTH RISE WIDTH FALL UNDERSHOOT RECOVERY\\
-reference name REFNAME\\
-reference expand [REF0] [TOTSECS SECSPERPOINT]\\
-reference sine CYCLESECS TOTSECS PHASESECS [SECSPERPOINT]\\
-reference convolve [REF0] CONVREF\\
-reference mask [REF0] MASKREF\\
-reference correlate REF2\\
-reference response [FLAG]\\
-reference schedule [GROUP]\\
-reference new\\
-reference REFNAME write schedule [PREFIX]
==== ====
*SKIP -The amount of time to ignore at the beginning of the time series
*DELAY -Indicates the expected delay between the reference time and the signal response (e.g. hemodynamic delay)
*OFFSET -A fixed time offset to be added to every reference time point (e.g to correct global synchronization)
Note: Times for SKIP, DELAY, TOTAL, BIN, & LENGTH can be followed by 's' or 'i' (or 'S'/'I') to specify seconds or images (seconds is default).
For blocks or cycles, only 1 full cycle needs to be specified; it will be expanded by repetition to fill the total time series being analyzed. (EXPAND can be specified to force expansion during creation.)
====Reading Schedule-format timing files====
SCHEDULE is used to create a reference time course based on linked "schedule" files (see [[jvs:fscan:manual:chapter2:setschedule|-set schedule]]). Schedule files are typically in a 3-column text format indicating the onset and duration of different events; each file corresponds to a different type of event. Schedule files can be organized in groups to allow the events for a task to be separated in different ways. Within a group, events should not overlap in time. Schedule groups can be specified by either a number or a single letter. Three naming conventions are recognized for grouping schedules:\\
schXG_NAME where X is a number and G is a single letter
sch_G_NAME where G is a number or a single letter
sch_TG_NAME where G is a number and T is any text not including '_'
NAME above can be any condition label that makes sense to you. If the filename ends in ".txt" that suffix will not be included in the label names.
The default schedule group includes any schedule files that do not match the above naming convention, or for which G is either a number or the letter 'a'. In general, if schedule files are organized in analysis groups the group should be specified explicitly when using the '-ref schedule' command.
Examples of schedule file groupings would be:
sch6a_CONDA1.txt sch_s1_FIRSTGRP_COND1.txt
sch6a_CONDA2.txt sch_s1_FIRSTGRP_COND2.txt
sch6b_CONDB1.txt sch_s2_SECONDGRP_COND3.txt
sch6b_CONDB2.txt sch_s2_SECONDGRP_COND4.txt
-ref schedule b name schedb (loads events labeled 'CONDB1' and 'CONDB2')
-ref schedule 1 name sched1 (loads events labeled 'FIRSTGRP_COND1' & 'FIRSTGRP_COND2'
The default group depends on what filenames have been linked.
If only the first column (sch6...) files were linked:
-ref schedule (loads only events labeled 'CONDA1' and 'CONDA2')
If the second column (sch_s...) files were linked the default would include multiple groups ('a', 1, and 2)
which is almost certainly not what you want. If you link multiple schedule file groups to your data sets
you should probably explicitly specify which group you want when creating a new reference time course.
====Writing Schedule files====
To write out a reference time course as a set of 3-column "schedule" files, use the following command:
-ref REFNAME write schedule [PREFIX]
Where REFNAME is the name of an existing reference time course (use $lastref to get the current active time course).
PREFIX is the filename prefix you want to use; the default PREFIX is "sch".
The REFNAME time course must have labels specified for the different conditions. For each condition label (CONDLABEL), a separate schedule file will be created, named: PREFIX_CONDLABEL.txt.
For example, consider the sample reference time course named MYREF:
To view your reference time course use:
-show ref myref
Time Value Duratn Label
0.000 1.0 10.0 rest
10.000 2.0 30.0 taskon
40.000 3.0 10.0 rest
50.000 2.0 30.0 taskon
80.000 1.0 10.0 rest
90.000 2.0 30.0 taskon
120.000 3.0 10.0 rest
To write MYREF out as schedule files you could use:
-ref myref write schedule sch3a
which would 2 generate files, sch3a_rest.txt and sch3a_taskon.txt:
sch3a_rest.txt sch3a_taskon.txt
0.0 10.0 1 10.0 30.0 1
40.0 10.0 1 50.0 30.0 1
80.0 10.0 1 90.0 30.0 1
120.0 10.0 1
====Expanding or convolving a reference time course====
For some statistics (t-test, correl), reference time course may be convolved with a canonical response function (e.g. hemodynamic response) before being used. The RF can be specified globally using '-set convolve REFNAME', in which case the named REFNAME will be used automatically when appropriate. A convolution can also be specified explicitly using '-reference convolve' as part of the reference definition.
E.g.: -ref hrffunc.txt name MyHRFunc
-ref 10 10s convolve MyHRFunc name MyTask
T-test convolutions use only fixed delays
**See Also:**\\
[[jvs:fscan:manual:chapter1:ilists|ILists]],
[[jvs:fscan:manual:chapter1:eventlists|EventLists]],
[[jvs:fscan:manual:chapter1:ilists|ILists]],
[[jvs:fscan:manual:chapter1:queries|Queries]]
[[jvs:fscan|fScan Home]],
[[jvs:fscan:manual|fScan Manual]],
[[jvs:fscan:manual:chapter2|CmdLineOptions]],
[[jvs:fscan:manual:help|Manual Help]]