AFNI program: 3dTcat

Output of -help


Concatenate sub-bricks from input datasets into one big 3D+time dataset.
Usage: 3dTcat options
where the options are:
     -prefix pname = Use 'pname' for the output dataset prefix name.
 OR  -output pname     [default='tcat']

     -session dir  = Use 'dir' for the output dataset session directory.
                       [default='./'=current working directory]
     -glueto fname = Append bricks to the end of the 'fname' dataset.
                       This command is an alternative to the -prefix 
                       and -session commands.                        
     -dry          = Execute a 'dry run'; that is, only print out
                       what would be done.  This is useful when
                       combining sub-bricks from multiple inputs.
     -verb         = Print out some verbose output as the program
                       proceeds (-dry implies -verb).
                       Using -verb twice results in quite lengthy output.
     -rlt          = Remove linear trends in each voxel time series loaded
                       from each input dataset, SEPARATELY.  That is, the
                       data from each dataset is detrended separately.
                       At least 3 sub-bricks from a dataset must be input
                       for this option to apply.
             Notes: (1) -rlt removes the least squares fit of 'a+b*t'
                          to each voxel time series; this means that
                          the mean is removed as well as the trend.
                          This effect makes it impractical to compute
                          the % Change using AFNI's internal FIM.
                    (2) To have the mean of each dataset time series added
                          back in, use this option in the form '-rlt+'.
                          In this case, only the slope 'b*t' is removed.
                    (3) To have the overall mean of all dataset time
                          series added back in, use this option in the
                          form '-rlt++'.  In this case, 'a+b*t' is removed
                          from each input dataset separately, and the
                          mean of all input datasets is added back in at
                          the end.  (This option will work properly only
                          if all input datasets use at least 3 sub-bricks!)
                    (4) -rlt can be used on datasets that contain shorts
                          or floats, but not on complex- or byte-valued
                          datasets.
     -relabel      = Replace any sub-brick labels in an input dataset
                       with the input dataset name -- this might help
                       identify the sub-bricks in the output dataset.

     -tpattern PATTERN = Specify the timing pattern for the output
                       dataset, using patterns described in the
                       'to3d -help' output (alt+z, seq, alt-z2, etc).

     -tr TR      = Specify the TR (in seconds) for the output dataset.

     -DAFNI_GLOB_SELECTORS=YES
                     Setting the environment variable AFNI_GLOB_SELECTORS
                     to YES (as done temporarily with this option) means
                     that sub-brick selectors '[..]' will not be used
                     as wildcards.  For example:
 3dTcat -DAFNI_GLOB_SELECTORS=YES -relabel -prefix EPIzero 'rest_*+tlrc.HEAD[0]'
                     will work to make a dataset with the #0 sub-brick
                     from each of a number of 3D+time datasets.
                  ** Note that the entire dataset specification is in quotes
                     to prevent the shell from doing the '*' wildcard expansion
                     -- it will be done inside the program itself, after the
                     sub-brick selector is temporarily detached from the string
                     -- and then a copy of the selector is re-attached to each
                     expanded filename.
                  ** Very few other AFNI '3d' programs do internal
                     wildcard expansion -- most of them rely on the shell.

Command line arguments after the above are taken as input datasets.
A dataset is specified using one of these forms:
   prefix+view
   prefix+view.HEAD
   prefix+view.BRIK
   prefix.nii
   prefix.nii.gz

SUB-BRICK SELECTION:
--------------------
You can also add a sub-brick selection list after the end of the
dataset name.  This allows only a subset of the sub-bricks to be
included into the output (by default, all of the input dataset
is copied into the output).  A sub-brick selection list looks like
one of the following forms:
  fred+orig[5]                     ==> use only sub-brick #5
  fred+orig[5,9,17]                ==> use #5, #9, and #17
  fred+orig[5..8]     or [5-8]     ==> use #5, #6, #7, and #8
  fred+orig[5..13(2)] or [5-13(2)] ==> use #5, #7, #9, #11, and #13
Sub-brick indexes start at 0.  You can use the character '$'
to indicate the last sub-brick in a dataset; for example, you
can select every third sub-brick by using the selection list
  fred+orig[0..$(3)]
You can reverse the order of sub-bricks with a list like
  fred+origh[$..0(-1)]
(Exactly WHY you might want to time-reverse a dataset is a mystery.)

You can also use a syntax based on the usage of the program count.
This would be most useful when randomizing (shuffling) the order of
the sub-bricks. Example:
  fred+orig[count -seed 2 5 11 s] is equivalent to something like:
  fred+orig[ 6, 5, 11, 10, 9, 8, 7] 
You could also do: fred+orig[`count -seed 2 -digits 1 -suffix ',' 5 11 s`]
but if you have lots of numbers, the command line would get too
long for the shell to process it properly. Omit the seed option if
you want the code to generate a seed automatically.
You cannot mix and match count syntax with other selection gimmicks.

If you have a lot of bricks to select in a particular order, you will
also run into name length problems. One solution is to put the indices
in a .1D file then use the following syntax. For example, say you have
the selection in file reorder.1D. You can extract the sub-bricks with:
   fred+orig'[1dcat reorder.1D]' 
As with count, you cannot mix and match 1dcat syntax with other 
selection gimmicks.

NOTES:
------
You can also add a sub-brick selection list after the end of the
* The TR and other time-axis properties are taken from the
  first input dataset that is itself 3D+time.  If no input
  datasets contain such information, then TR is set to 1.0.
  This can be altered later using the 3drefit program.

* The sub-bricks are output in the order specified, which may
  not be the order in the original datasets.  For example, using
     fred+orig[0..$(2),1..$(2)]
  will cause the sub-bricks in fred+orig to be output into the
  new dataset in an interleaved fashion.  Using
     fred+orig[$..0]
  will reverse the order of the sub-bricks in the output.
  If the -rlt option is used, the sub-bricks selected from each
  input dataset will be re-ordered into the output dataset, and
  then this sequence will be detrended.

* You can use the '3dinfo' program to see how many sub-bricks
  a 3D+time or a bucket dataset contains.

* The '$', '(', ')', '[', and ']' characters are special to
  the shell, so you will have to escape them.  This is most easily
  done by putting the entire dataset plus selection list inside
  single quotes, as in 'fred+orig[5..7,9]'.

* You may wish/need to use the 3drefit program on the output
  dataset to modify some of the .HEAD file parameters.

* The program does internal wildcard expansion on the filenames
  provided to define the datasets.  The software first strips the
  sub-brick selector string '[...]' off the end of each filename
  BEFORE wildcard expansion, then re-appends it to the results
  AFTER the expansion; for example, '*+orig.HEAD[4..7]' might
  expand to 'fred+orig.HEAD[4..7]' and 'wilma+orig.HEAD[4..7]'.
 ++ However, the '[...]' construct is also a shell wildcard,
    It is not practicable to use this feature for filename
    selection with 3dTcat if you are also using sub-brick
    selectors.
 ++ Since wildcard expansion looks for whole filenames, you must
    use wildcard expansion in the form (e.g.) of '*+orig.HEAD',
    NOT '*+orig' -- since the latter form doesn't match filenames.
 ++ Don't use '*+orig.*' since that will match both the .BRIK and
    .HEAD files, and each dataset will end up being read in twice!
 ++ If you want to see the filename expansion results, run 3dTcat
    with the option '-DAFNI_GLOB_DEBUG=YES'

++ Compile date = Mar 28 2024 {AFNI_24.0.18:linux_ubuntu_16_64}


This page auto-generated on Thu Mar 28 19:35:46 EDT 2024