AFNI program: 3drefit

Output of -help

++ 3drefit: AFNI version=AFNI_24.3.06 (Oct 31 2024) [64-bit]
++ Authored by: RW Cox
Changes some of the information inside a 3D dataset's header. ~1~
Note that this program does NOT change the .BRIK file at all;
the main purpose of 3drefit is to fix up errors made when
using to3d.
To see the current values stored in a .HEAD file, use the command
'3dinfo dataset'.  Using 3dinfo both before and after 3drefit is
a good idea to make sure the changes have been made correctly!

20 Jun 2006: 3drefit will now work on NIfTI datasets (but it will write
             out the entire dataset, into the current working directory)

Usage: 3drefit [options] dataset ... ~1~
where the options are
  -quiet          Turn off the verbose progress messages

  -orient code    Sets the orientation of the 3D volume(s) in the .BRIK.
                  The code must be 3 letters, one each from the
                  pairs {R,L} {A,P} {I,S}.  The first letter gives
                  the orientation of the x-axis, the second the
                  orientation of the y-axis, the third the z-axis:
                     R = right-to-left         L = left-to-right
                     A = anterior-to-posterior P = posterior-to-anterior
                     I = inferior-to-superior  S = superior-to-inferior
               ** WARNING: when changing the orientation, you must be sure
                  to check the origins as well, to make sure that the volume
                  is positioned correctly in space.

  -xorigin distx  Puts the center of the edge voxel off at the given
  -yorigin disty  distance, for the given axis (x,y,z); distances in mm.
  -zorigin distz  (x=first axis, y=second axis, z=third axis).
                  Usually, only -zorigin makes sense.  Note that this
                  distance is in the direction given by the corresponding
                  letter in the -orient code.  For example, '-orient RAI'
                  would mean that '-zorigin 30' sets the center of the
                  first slice at 30 mm Inferior.  See the to3d manual
                  for more explanations of axes origins.
               ** SPECIAL CASE: you can use the string 'cen' in place of
                  a distance to force that axis to be re-centered.

  -xorigin_raw xx Puts the center of the edge voxel at the given COORDINATE
  -yorigin_raw yy rather than the given DISTANCE.  That is, these values
  -zorigin_raw zz directly replace the offsets in the dataset header,
                  without any possible sign changes.

  -duporigin cset Copies the xorigin, yorigin, and zorigin values from
                  the header of dataset 'cset'.

  -dxorigin dx    Adds distance 'dx' (or 'dy', or 'dz') to the center
  -dyorigin dy    coordinate of the edge voxel.  Can be used with the
  -dzorigin dz    values input to the 'Nudge xyz' plugin.
               ** WARNING: you can't use these options at the same
                  time you use -orient.
               ** WARNING: consider -shift_tags if dataset has tags

  -xdel dimx      Makes the size of the voxel the given dimension,
  -ydel dimy      for the given axis (x,y,z); dimensions in mm.
  -zdel dimz   ** WARNING: if you change a voxel dimension, you will
                  probably have to change the origin as well.
  -keepcen        When changing a voxel dimension with -xdel (etc.),
                  also change the corresponding origin to keep the
                  center of the dataset at the same coordinate location.
  -xyzscale fac   Scale the size of the dataset voxels by the factor 'fac'.
                  This is equivalent to using -xdel, -ydel, -zdel together.
                  -keepcen is used on the first input dataset, and then
                  any others will be shifted the same amount, to maintain
                  their alignment with the first one.
               ** WARNING: -xyzscale can't be used with any of the other
                  options that change the dataset grid coordinates!
               ** N.B.: 'fac' must be positive, and using fac=1.0 is stupid.

  -TR time        Changes the TR time to a new value (see 'to3d -help').
               ** You can also put the name of a dataset in for 'time', in
                  which case the TR for that dataset will be used.
               ** N.B.: If the dataset has slice time offsets, these will
                  be scaled by the factor newTR/oldTR. This scaling does not
                  apply if you use '-Tslices' in the same 3drefit run.
  -notoff         Removes the slice-dependent time-offsets.
  -Torg ttt       Set the time origin of the dataset to value 'ttt'.
                  (Time origins are set to 0 in to3d.)
               ** WARNING: These 3 options apply only to 3D+time datasets.
                   **N.B.: Using '-TR' on a dataset without a time axis
                           will add a time axis to the dataset.

  -Tslices a b c d ...
                  Reset the slice time offsets to be 'a', 'b', 'c', ...
                  (in seconds). The number of values following '-Tslices'
                  should be the same as the number of slices in the dataset,
                  but 3drefit does NOT check that this is true.
               ** If any offset time is < 0 or >= TR, a warning will be
                  printed (to stderr), but this is not illegal even though
                  it is a bad idea.
               ** If the dataset does not have a TR set, then '-Tslices'
                  will fail. You can use '-TR' to set the inter-volume time
                  spacing in the same 3drefit command.
               ** If you have the slices times stored (e.g., from DICOM) in
                  some other units, you can scale them to be in seconds by
                  putting a scale factor after the '-Tslices' option as follows:
                    -Tslices '*0.001' 300 600 900 ...
                  which would be used to scale from milliseconds to seconds.
                  The format is to start the scale factor with a '*' to tell
                  3drefit that this number is not a slice offset but is to be
                  used a a scale factor for the rest of the following values.
                  Since '*' is a filename wildcard, it needs to be in quotes!
               ** The program stops looking for number values after '-Tslices'
                  when it runs into something that does not look like a number.
                  Here, 'look like a number' means a character string that:
                    * starts with a digit 0..9
                    * starts with a decimal point '.' followed by a digit
                    * starts with a minus sign '-' followed by a digit
                    * starts with '-.' followed by a digit
                  So if the input dataset name starts with a digit, and the
                  last command line option '-Tslices', 3drefit will think
                  the filename is actually a number for a slice offset time.
                  To avoid this problem, you can do one of these things:
                    * Put in an option that is just the single character '-'
                    * Don't use '-Tslices' as the last option
                    * Put a directory name before the dataset name, as in
                      './Galacticon.nii'
                ** If you have the slice time offsets stored in a text file
                   as a list of values, then you can input these values on
                   the command line using the Unix backquote operator, as in
                     -Tslices `cat SliceTimes.1D`
                ** For example, if the slice time offsets are in a JSON
                   sidecar (a la BIDS), you might be able to something like
                   the following to extract the timings into a file:
  abids_json_tool.py -json2txt -input sub-10506_task-pamenc_bold.json -prefix junk.txt
  grep SliceTiming junk.txt | sed -e 's/^SliceTiming *://' > SliceTimes.1D
  \rm junk.txt

  -newid          Changes the ID code of this dataset as well.

  -nowarp         Removes all warping information from dataset.

  -apar aset      Set the dataset's anatomy parent dataset to 'aset'
               ** N.B.: The anatomy parent is the dataset from which the
                  transformation from +orig to +acpc and +tlrc coordinates
                  is taken.  It is appropriate to use -apar when there is
                  more than 1 anatomical dataset in a directory that has
                  been transformed.  In this way, you can be sure that
                  AFNI will choose the correct transformation.  You would
                  use this option on all the +orig dataset that are
                  aligned with 'aset' (i.e., that were acquired in the
                  same scanning session).
               ** N.B.: Special cases of 'aset'
                   aset = NULL --> remove the anat parent info from the dataset
                   aset = SELF --> set the anat parent to be the dataset itself

  -wpar wset      Set the warp parent (the +orig version of a +tlrc dset).
                  This option is used by @auto_tlrc. Do not use it unless
                  you know what you're doing. 

  -clear_bstat    Clears the statistics (min and max) stored for each sub-brick
                  in the dataset.  This is useful if you have done something to
                  modify the contents of the .BRIK file associated with this
                  dataset.
  -redo_bstat     Re-computes the statistics for each sub-brick.  Requires
                  reading the .BRIK file, of course.  Also does -clear_bstat
                  before recomputing statistics, so that if the .BRIK read
                  fails for some reason, then you'll be left without stats.

  -statpar v ...  Changes the statistical parameters stored in this
                  dataset.  See 'to3d -help' for more details.

  -markers        Adds an empty set of AC-PC markers to the dataset,
                  if it can handle them (is anatomical, is in the +orig
                  view, and isn't 3D+time).
               ** WARNING: this will erase any markers that already exist!

  -shift_tags     Apply -dxorigin (and y and z) changes to tags.

  -dxtag dx       Add dx to the coordinates of all tags.
  -dytag dy       Add dy to the coordinates of all tags.
  -dztag dz       Add dz to the coordinates of all tags.

  -view code      Changes the 'view' to be 'code', where the string 'code'
                  is one of 'orig', 'acpc', or 'tlrc'.
               ** WARNING: The program will also change the .HEAD and .BRIK
                  filenames to match.  If the dataset filenames already
                  exist in the '+code' view, then this option will fail.
                  You will have to rename the dataset files before trying
                  to use '-view'.  If you COPY the files and then use
                  '-view', don't forget to use '-newid' as well!
               ** WARNING2: Changing the view without specifying the new 
                  might lead to conflicting information. Consider specifying
                  the space along with -view
  -space spcname  Associates the dataset with a specific template type, e.g.
                  TLRC, MNI, ORIG. The default assumed for +tlrc datasets is
                  'TLRC'. One use for this attribute is to use MNI space
                  coordinates and atlases instead of the default TLRC space.
               ** See WARNING2 for -view option.
  -cmap cmaptype  Associate colormap type with dataset. Available choices are
                  CONT_CMAP (the default), INT_CMAP (integer colormap display)
                  and SPARSE_CMAP (for sparse integer colormaps). INT_CMAP is
                  appropriate for showing ROI mask datasets or Atlas datasets
                  where the continuous color scales are not useful.

  -label2 llll    Set the 'label2' field in a dataset .HEAD file to the
                  string 'llll'.  (Can be used as in AFNI window titlebars.)
  -labeltable TTT Inset the label table TTT in the .HEAD file.
                  The label table format is described in README.environment
                  under the heading: 'Variable: AFNI_VALUE_LABEL_DTABLE'
              See also -copytables

  -denote         Means to remove all possibly-identifying notes from
                  the header.  This includes the History Note, other text
                  Notes, keywords, and labels.

  -deoblique      Replace transformation matrix in header with cardinal matrix.
                  This option DOES NOT deoblique the volume. To do so
                  you should use 3dWarp -deoblique. This option is not 
                  to be used unless you really know what you're doing.

  -oblique_origin
                  assume origin and orientation from oblique transformation
                  matrix rather than traditional cardinal information

  -oblique_recenter
                  Adjust the origin so that the cardinalized 0,0,0 is in
                  the same brain location as that of the original (oblique?)
                  (scanner?) coordinates.
                  Round this to the nearest voxel center.
                * Even if cardinal, rounding might cause an origin shift
                  (see -oblique_recenter_raw).

  -oblique_recenter_raw
                  Like -oblique_recenter, but do not round.
                  So coordinate 0,0,0 is in the exact same location, even
                  if not at a voxel center.

  -byteorder bbb  Sets the byte order string in the header.
                  Allowable values for 'bbb' are:
                     LSB_FIRST   MSB_FIRST   NATIVE_ORDER
                  Note that this does not change the .BRIK file!
                  This is done by programs 2swap and 4swap.

  -checkaxes      Doesn't alter the input dataset; rather, this just
                  checks the dataset axes orientation codes and the
                  axes matrices for consistency.  (This option was
                  added primarily to check for bugs in various codes.)

  -appkey ll      Appends the string 'll' to the keyword list for the
                  whole dataset.
  -repkey ll      Replaces the keyword list for the dataset with the
                  string 'll'.
  -empkey         Destroys the keyword list for the dataset.

  -atrcopy dd nn  Copy AFNI header attribute named 'nn' from dataset 'dd'
                  into the header of the dataset(s) being modified.
                  For more information on AFNI header attributes, see
                  documentation file README.attributes. More than one
                  '-atrcopy' option can be used.
          **N.B.: This option is for those who know what they are doing!
                  Without the -saveatr option, this option is
                  meant to be used to alter attributes that are NOT
                  directly mapped into dataset internal structures, since
                  those structures are mapped back into attribute values
                  as the dataset is being written to disk.  If you want
                  to change such an attribute, you have to use the
                  corresponding 3drefit option directly or use the 
                  -saveatr option.

                  If you are confused, try to understand this: 
                  Option -atrcopy was never intended to modify AFNI-
                  specific attributes. Rather, it was meant to copy
                  user-specific attributes that had been added to some
                  dataset using -atrstring option. A cursed day came when
                  it was convenient to use -atrcopy to copy an AFNI-specific
                  attribute (BRICK_LABS to be exact) and for that to
                  take effect in the output, the option -saveatr was added.
                  Contact Daniel Glen and/or Rick Reynolds for further 
                  clarification and any other needs you may have.

                  Do NOT use -atrcopy or -atrstring with other modification
                  options.
          See also -copyaux

  -atrstring n 'x' Copy the string 'x' into the dataset(s) being
                   modified, giving it the attribute name 'n'.
                   To be safe, the 'x' string should be in quotes.
          **N.B.: You can store attributes with almost any name in
                  the .HEAD file.  AFNI will ignore those it doesn't
                  know anything about.  This technique can be a way of
                  communicating information between programs.  However,
                  when most AFNI programs write a new dataset, they will
                  not preserve any such non-standard attributes.
          **N.B.: Special case: if the string 'x' is of the form
                  'file:name', then the contents of the file 'name' will
                  be read in as a single string and stored in the attribute.
  -atrfloat name 'values'
  -atrint name 'values'
                  Create or modify floating point or integer attributes.
                  The input values may be specified as a single string
                  in quotes or as a 1D filename or string. For example,
     3drefit -atrfloat IJK_TO_DICOM_REAL '1 0.2 0 0 -0.2 1 0 0 0 0 1 0' dset+orig
     3drefit -atrfloat IJK_TO_DICOM_REAL flipZ.1D dset+orig
     3drefit -atrfloat IJK_TO_DICOM_REAL \ 
       '1D:1,0.2,2@0,-0.2,1,2@0,2@0,1,0' \ 
       dset+orig
                  Almost all afni attributes can be modified in this way
  -saveatr        (default) Copy the attributes that are known to AFNI into 
                  the dset->dblk structure thereby forcing changes to known
                  attributes to be present in the output.
                  This option only makes sense with -atrcopy
          **N.B.: Don't do something like copy labels of a dataset with 
                  30 sub-bricks to one that has only 10, or vice versa.
                  This option is for those who would deservedly earn a
                  hunting license.
  -nosaveatr      Opposite of -saveatr
     Example: 
     3drefit -saveatr -atrcopy WithLabels+tlrc BRICK_LABS NeedsLabels+tlrc

  -'type'         Changes the type of data that is declared for this
                  dataset, where 'type' is chosen from the following:
       ANATOMICAL TYPES
         spgr == Spoiled GRASS             fse == Fast Spin Echo  
         epan == Echo Planar              anat == MRI Anatomy     
           ct == CT Scan                  spct == SPECT Anatomy   
          pet == PET Anatomy               mra == MR Angiography  
         bmap == B-field Map              diff == Diffusion Map   
         omri == Other MRI                abuc == Anat Bucket     
       FUNCTIONAL TYPES
          fim == Intensity                fith == Inten+Thr       
         fico == Inten+Cor                fitt == Inten+Ttest     
         fift == Inten+Ftest              fizt == Inten+Ztest     
         fict == Inten+ChiSq              fibt == Inten+Beta      
         fibn == Inten+Binom              figt == Inten+Gamma     
         fipt == Inten+Poisson            fbuc == Func-Bucket     

  -copyaux auxset Copies the 'auxiliary' data from dataset 'auxset'
                  over the auxiliary data for the dataset being
                  modified.  Auxiliary data comprises sub-brick labels,
                  keywords, statistics codes, nodelists, and labeltables
                  AND/OR atlas point lists.
                  '-copyaux' occurs BEFORE the '-sub' operations below,
                  so you can use those to alter the auxiliary data
                  that is copied from auxset.


  -copytables tabset Copies labeltables AND/OR atlas point lists, if any,
                  from tabset to the input dataset.
                  '-copyaux' occurs BEFORE the '-sub' operations below,
                  so you can use those to alter the auxiliary data
                  that is copied from tabset. 

  -relabel_all xx  Reads the file 'xx', breaks it into strings,
                   and puts these strings in as the sub-brick
                   labels.  Basically a batch way of doing
                   '-sublabel' many times, for n=0, 1, ...
                 ** This option is executed BEFORE '-sublabel',
                    so any labels from '-sublabel' will over-ride
                    labels from this file.
                 ** Strings in the 'xx' file are separated by
                    whitespace (blanks, tabs, new lines).

  -relabel_all_str 'lab0 lab1 ... lab_p': Just like -relabel_all
                   but with labels all present in one string

  -sublabel_prefix PP: Prefix each sub-brick's label with PP
  -sublabel_suffix SS: Suffix each sub-brick's label with SS

The options below attach auxiliary data to sub-bricks in the dataset. ~1~
Each option may be used more than once so that
multiple sub-bricks can be modified in a single run of 3drefit.

  -sublabel  n ll  Attach to sub-brick #n the label string 'll'.
  -subappkey n ll  Add to sub-brick #n the keyword string 'll'.
  -subrepkey n ll  Replace sub-brick #n's keyword string with 'll'.
  -subempkey n     Empty out sub-brick #n' keyword string

  -substatpar n type v ...
                  Attach to sub-brick #n the statistical type and
                  the auxiliary parameters given by values 'v ...',
                  where 'type' is one of the following:
         Stat Types: ~2~
         type  Description  PARAMETERS
         ----  -----------  ----------------------------------------
         fico  Cor          SAMPLES  FIT-PARAMETERS  ORT-PARAMETERS
         fitt  Ttest        DEGREES-of-FREEDOM
         fift  Ftest        NUMERATOR and DENOMINATOR DEGREES-of-FREEDOM
         fizt  Ztest        N/A
         fict  ChiSq        DEGREES-of-FREEDOM
         fibt  Beta         A (numerator) and B (denominator)
         fibn  Binom        NUMBER-of-TRIALS and PROBABILITY-per-TRIAL
         figt  Gamma        SHAPE and SCALE
         fipt  Poisson      MEAN

You can also use option '-unSTAT' to remove all statistical encodings
from sub-bricks in the dataset.  This operation would be desirable if
you modified the values in the dataset (e.g., via 3dcalc).
 ['-unSTAT' is done BEFORE the '-substatpar' operations, so you can  ]
 [combine these options to completely redo the sub-bricks, if needed.]
 [Option '-unSTAT' also implies that '-unFDR' will be carried out.   ]

The following options allow you to modify VOLREG fields: ~1~
  -vr_mat val1 ... val12  Use these twelve values for VOLREG_MATVEC_index.
  -vr_mat_ind index       Index of VOLREG_MATVEC_index field to be modified.
                          Optional, default index is 0.
NB: You can only modify one VOLREG_MATVEC_index at a time
  -vr_center_old x y z    Use these 3 values for VOLREG_CENTER_OLD.
  -vr_center_base x y z   Use these 3 values for VOLREG_CENTER_BASE.


The following options let you modify the FDR curves stored in the header: ~1~

 -addFDR = For each sub-brick marked with a statistical code, (re)compute
           the FDR curve of z(q) vs. statistic, and store in the dataset header
           * '-addFDR' runs as if '-new -pmask' were given to 3dFDR, so that
              stat values == 0 will be ignored in the FDR algorithm.

 -FDRmask mset = load dataset 'mset' and use it as a mask
 -STATmask mset  for the '-addFDR' calculations.
                 * This can be useful if you ran 3dDeconvolve/3dREMLFIT
                    without a mask, and want to apply a mask to improve
                    the FDR estimation procedure.
                 * If '-addFDR' is NOT given, then '-FDRmask' does nothing.
                 * 3drefit does not generate an automask for FDR purposes
                    (unlike 3dREMLfit and 3dDeconvolve), since the input
                    dataset may contain only statistics and no structural
                    information about the brain.

 -unFDR  = Remove all FDR curves from the header
           [you will want to do this if you have done something to ]
           [modify the values in the dataset statistical sub-bricks]

++ Last program update: 27 Mar 2009

++ Compile date = Oct 31 2024 {AFNI_24.3.06:linux_ubuntu_24_64}
This page auto-generated on Thu Oct 31 09:42:30 PM EDT 2024