Differences

This shows you the differences between two versions of the page.

--- jvs:fscan:manual:chapter2:reference [2012/05/04 17:35]
voyvodic
+++ jvs:fscan:manual:chapter2:reference [2023/02/23 18:43] (current)
@@ Line 3: / Line 3: @@
 == 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. The complete list is:
+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 ...\\
@@ Line 12: / Line 13: @@
 -reference total TOTALTIME\\
 -reference bin  BINSIZE\\
+-reference offset OFFSETTIME\\
 -reference cycles\\
 -reference events\\
 -reference starts\\
--reference hrf Latency\\
+-reference hrf LATENCY\\
--reference hrf Latency Transition\\
+-reference hrf LATENCY TRANSITION\\
--reference hrf Latency Rise Width Fall [Undershoot Recovery]\\
+-reference hrf LATENCY RISE WIDTH FALL [UNDERSHOOT RECOVERY]\\
--reference hrf Latency Dip Depth Rise Width Fall Undershoot Recovery\\
+-reference hrf LATENCY DIP DEPTH RISE WIDTH FALL UNDERSHOOT RECOVERY\\
 -reference name REFNAME\\
--reference expand [ref0] [Npts]\\
+-reference expand [REF0] [TOTSECS SECSPERPOINT]\\
--reference convolve [ref0] ConvRef\\
+-reference sine CYCLESECS TOTSECS PHASESECS [SECSPERPOINT]\\
--reference mask   [ref0] MskRef\\
+-reference convolve [REF0] CONVREF\\
--reference schedule [group]\\
+-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 how much to shift each data point in time before applying the reference.
+  *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)
-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.)
+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).
-SCHEDULE is used to create a reference time course based on linked "schedule" files (see [[jvs:fscan:manual:chapter2:set|-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:\\
+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.)
-     schXG_NAME          where G is a single letter and X is a number
+====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 '_'
-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.\\
+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_CONDA1.txt           sch_s1_FIRSTGRP_COND1.txt
-   sch6a_conda2.txt           sch_s1_firstgrp_cond2.txt
+   sch6a_CONDA2.txt           sch_s1_FIRSTGRP_COND2.txt
-   sch6b_condb1.txt           sch_s2_scndgrp_cond3.txt
+   sch6b_CONDB1.txt           sch_s2_SECONDGRP_COND3.txt
-   sch6b_condb2.txt           sch_s2_scndgrp_cond4.txt
+   sch6b_CONDB2.txt           sch_s2_SECONDGRP_COND4.txt
-     -reference schedule b name schedb            would include events labeled 'condb1' and 'condb2'
+     -ref schedule b name schedb     (loads events labeled 'CONDB1' and 'CONDB2')
-     -reference schedule 1 name sched1            would include events labeled 'firstgrp_cond1' and 'firstgrp_cond2'
+     -ref schedule 1 name sched1     (loads events labeled 'FIRSTGRP_COND1' & 'FIRSTGRP_COND2'
-   If only the first column (sch6...) files were linked, the default would just include group 'a':
-     -reference schedule                          would include events labeled 'conda1' and 'conda2'
+  The default group depends on what filenames have been linked.
-   If only the second column (sch_s...) files were linked, the default would include all groups.
+  If only the first column (sch6...) files were linked:
-   If both columns above were linked, the default would include groups 'a', 1, and 2.
+     -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:
+<code>
+  -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".
+</code>
+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.
+<code>
+  For example, consider the sample reference time course named MYREF:
+  To view your reference time course use:
+    -show ref myref
+     Time    Value Duratn Label
+.000     1.0   10.0 rest
+.000     2.0   30.0 taskon
+.000     3.0   10.0 rest
+.000     2.0   30.0 taskon
+.000     1.0   10.0 rest
+.000     2.0   30.0 taskon
+.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    10.0   1            10.0   30.0   1
+.0    10.0   1            50.0   30.0   1
+.0    10.0   1            90.0   30.0   1
+.0    10.0   1
+</code>
+====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.
 <code>
@@ Line 55: / Line 105: @@
 </code>
-T-test convolutions are only fixed delays
+T-test convolutions use only fixed delays
-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).
 **See Also:**\\

Brain Imaging & Analysis Center

User Tools

Site Tools

Differences

Page Tools