AFNI program: Dimon

Output of -help


Dimon - monitor real-time acquisition of DICOM image files
    (or GEMS 5.x I-files, as 'Imon')

    This program is intended to be run during a scanning session
    on a scanner, to monitor the collection of image files.  The
    user will be notified of any missing slice or any slice that
    is acquired out of order.

    When collecting DICOM files, it is recommended to run this
    once per run, only because it is easier to specify the input
    file pattern for a single run (it may be very difficult to
    predict the form of input filenames runs that have not yet
    occurred.

    This program can also be used off-line (away from the scanner)
    to organize the files, run by run.  If the DICOM files have
    a correct DICOM 'image number' (0x0020 0013), then Dimon can
    use the information to organize the sequence of the files, 
    particularly when the alphabetization of the filenames does
    not match the sequencing of the slice positions.  This can be
    used in conjunction with the '-GERT_Reco' option, which will
    write a script that can be used to create AFNI datasets.

    See the '-dicom_org' option, under 'other options', below.

    If no -quit option is provided (and no -no_wait), the user should
    terminate the program when it is done collecting images according
    to the input file pattern.

    Dimon can be terminated using <ctrl-c>.

  ---------------------------------------------------------------
  comments for using Dimon with various image file types

     DICOM : this is the intended and default use
             - provide at least -infile_prefix

     GEMS 5x. : GE Medical Systems I-files
             - requires -start_dir and -file_type GEMS
             - works as the original Imon program

     AFNI : AFNI/NIFTI volume datasets
             - requires -file_type AFNI
             - use -sp to specify slice timing pattern
             - if datasets are 4D, please use rtfeedme

  ---------------------------------------------------------------
  realtime notes for running afni remotely:

    - The afni program must be started with the '-rt' option to
      invoke the realtime plugin functionality.

    - If afni is run remotely, then AFNI_TRUSTHOST will need to be
      set on the host running afni.  The value of that variable
      should be set to the IP address of the host running Dimon.
      This may set as an environment variable, or via the .afnirc
      startup file.

    - The typical default security on a Linux system will prevent
      Dimon from communicating with afni on the host running afni.
      The iptables firewall service on afni's host will need to be
      configured to accept the communication from the host running
      Dimon, or it (iptables) will need to be turned off.
  ---------------------------------------------------------------
  usage: Dimon [options] -infile_prefix PREFIX
     OR: Dimon [options] -infile_pattern "PATTERN"
     OR: Dimon [options] -infile_list FILES.txt

  ---------------------------------------------------------------
  notes regarding Siemens mosaic images:

    - Final run slices will be reported as 1 (since there is only 1
      actual image), but mos_nslices will show the mosaic slice count.

    - Acquisition timing for the slices will depend on the number of
      slices (parity), as well as the mosiac ordering.  So users may
      need to rely on reading slice timing from the DICOM headers.

    - If slice timing is detected, 

  ---------------------------------------------------------------
  examples:

  A. no real-time options:

    Dimon -infile_prefix   s8912345/i -no_wait
    Dimon -infile_pattern 's8912345/i*' -no_wait
    Dimon -infile_list     my_files.txt
    Dimon -help
    Dimon -infile_prefix   s8912345/i  -quit
    Dimon -infile_prefix   s8912345/i  -nt 120 -quit
    Dimon -infile_prefix   s8912345/i  -debug 2
    Dimon -infile_prefix   s8912345/i  -dicom_org -GERT_Reco -quit
  basic sorting example, and save optional sorting details
    Dimon -infile_prefix '*.dcm' -gert_create_dataset -dicom_org \
          -save_details D

  A2. investigate a list of files: 

    Dimon -infile_pattern '*' -dicom_org -show_sorted_list -quit
    Dimon -infile_prefix run1/im -sort_by_num_suffix -quit \
          -save_details DETAILS -save_errors

  A3. save a sorted list of files and check it later: 

    Dimon -infile_prefix data/im -dicom_org -save_file_list sorted.files
    Dimon -infile_list sorted.files ... 

  A4. sort by geme_index with 3-echo EPI data
      (and check sort against iuid 0008,0018)

    Dimon -infile_pre data/im -sort_by_num_suffix -no_wait -num_chan 3 \
          -sort_method geme_index

  A5. sort by geme_rin with 3-echo EPI data
      (sub-sort RIN by echo/RIN in groups of necho*nslices)

    Dimon -infile_pre data/im -sort_by_num_suffix -no_wait \
          -sort_method geme_rin

  A6. like geme_index, but pre-sort by RIN (not alphabetically)

    Dimon -infile_pre data/im -dicom_org -num_chan 3 \
          -sort_method geme_xnat


  B. for GERT_Reco:

    Dimon -infile_prefix run_003/image -gert_create_dataset
    Dimon -infile_prefix run_003/image -dicom_org -GERT_Reco -no_wait
    Dimon -infile_prefix 'run_00[3-5]/image' -GERT_Reco -quit
    Dimon -infile_prefix anat/image -GERT_Reco -no_wait
    Dimon -infile_prefix epi_003/image -dicom_org -no_wait \
          -GERT_Reco -gert_to3d_prefix run3 -gert_nz 42

  B2. Deal with Philips data (names are not sorted, and image numbers
      are in slice-major order).

      a. Sort by acq time, then inst num.
         See -sort_by_acq_time in help output for details.

         Dimon -infile_pattern 'data/*.dcm' -GERT_Reco -quit \
               -use_last_elem -use_slice_loc -dicom_org -sort_by_acq_time

      b. If the acquisition time is not appropriate, the slice vs time
         (zt) ordering can be reversed.
         Save ordering details for review (in DET* text files).

         Dimon -infile_pattern 'data/IM_*'                    \
               -gert_create_dataset -use_last_elem -dicom_org \
               -order_as_zt save_det DET

  B3. Simple examples for NIH scanners (GE or Siemens).

      o  create GERT_Reco script to put data into AFNI format
      o  create GERT_Reco script AND execute it (running to3d)
         (-gert_create_dataset implies -GERT_Reco and -quit)
      o  create and execute script, but make a NIfTI dataset
      o  also, store the datasets under a 'MRI_dsets' directory

    Dimon -infile_pattern 'mr_0015/*.dcm' -GERT_Reco -quit 
    Dimon -infile_prefix 'mr_0003/image' -gert_create_dataset
    Dimon -infile_pattern 'mr_0003/*.dcm' -gert_create_dataset
          -gert_write_as_nifti 
    Dimon -infile_pattern 'mr_0003/*.dcm' -gert_create_dataset
          -gert_outdir MRI_dsets -gert_to3d_prefix EPI_003.nii

  C. with real-time options:

    Dimon -infile_prefix s8912345/i -rt 

    Dimon -infile_pattern 's*/i*' -rt 
    Dimon -infile_pattern 's*/i*' -rt -nt 120
    Dimon -infile_pattern 's*/i*' -rt -quit
    Dimon -infile_prefix s8912345/i -rt -num_chan 2 -quit

    Dimon -infile_pre run1/i -rt -num_chan 3 -quit -sort_method geme_index

    ** detailed real-time example:

    Dimon                                    \
       -infile_pattern 's*/i*'               \
       -rt -nt 120                           \
       -host some.remote.computer            \
       -rt_cmd "PREFIX 2005_0513_run3"     \
       -num_slices 32                        \
       -max_quiet_trs 3                      \
       -sleep_frac 0.4                       \
       -quit                                 

    This example scans data starting from directory 003, expects
    120 repetitions (TRs), and invokes the real-time processing,
    sending data to a computer called some.remote.computer.name
    (where afni is running, and which considers THIS computer to
    be trusted - see the AFNI_TRUSTHOST environment variable).
    The time to wait for new data is 1.1*TR, and 32 slices are
    required for a volume

    Note that -num_slices can be important in a real-time setup,
    as scanners do not always write the slices in order.   Slices
    from volume #1 can appear on disk before all slices from volume
    #0, in which case Dimon might determine an incorrect number of
    slices per volume.

  -------------------------------------------
    Multiple DRIVE_AFNI commands are passed through '-drive_afni'
    options, one requesting to open an axial image window, and
    another requesting an axial graph, with 160 data points.

    Also, '-drive_wait' options may be used like '-drive_afni',
    except that the real-time plugin will wait until the first new
    volume is processed before executing those DRIVE_AFNI commands.
    One advantage of this is opening an image window for a dataset
    _after_ it is loaded, allowing afni to appropriately set the
    window size.

    See README.driver for acceptable DRIVE_AFNI commands.

    Also, multiple commands specific to the real-time plugin are
    passed via '-rt_cmd' options.  The PREFIX command sets the
    prefix for the datasets output by afni.  The GRAPH_XRANGE and
    GRAPH_YRANGE commands set the graph dimensions for the 3D
    motion correction graph (only).  And the GRAPH_EXPR command
    is used to replace the 6 default motion correction graphs with
    a single graph, according to the given expression, the square
    root of the average squared entry of the 3 rotation params,
    roll, pitch and yaw, ignoring the 3 shift parameters, dx, dy
    and dz.

    See README.realtime for acceptable DRIVE_AFNI commands.

  example D (drive_afni):

    Dimon                                                   \
       -infile_pattern 's*/i*.dcm'                         \
       -nt 160                                             \
       -rt                                                 \
       -host some.remote.computer.name                     \
       -drive_afni 'OPEN_WINDOW axialimage'                \
       -drive_afni 'OPEN_WINDOW axialgraph pinnum=160'     \
       -rt_cmd 'PREFIX eat.more.cheese'                    \
       -rt_cmd 'GRAPH_XRANGE 160'                          \
       -rt_cmd 'GRAPH_YRANGE 1.02'                         \
       -rt_cmd 'GRAPH_EXPR sqrt(d*d+e*e+f*f)'

  -------------------------------------------

  example E (drive_wait):

    Close windows and re-open them after data has arrived.

    Dimon                                                    \
       -infile_prefix EPI_run1/8HRBRAIN                      \
       -rt                                                   \
       -drive_afni 'CLOSE_WINDOW axialimage'                 \
       -drive_afni 'CLOSE_WINDOW sagittalimage'              \
       -drive_wait 'OPEN_WINDOW axialimage geom=+20+20'      \
       -drive_wait 'OPEN_WINDOW sagittalimage geom=+520+20'  \
       -rt_cmd 'PREFIX brie.would.be.good'                   \

  -------------------------------------------
  example F (for testing a complete real-time system):

    ** consider AFNI_data6/realtime.demos/demo.2.fback.*
    ** consider also: @Install_APMULTI_Demo2_realtime

    Use Dimon to send volumes to afni's real-time plugin, simulating
    TR timing with Dimon's -pause option.  Motion parameters and ROI
    averages are then sent on to realtime_receiver.py (for subject
    feedback).
    
    a. Start afni in real-time mode, but first set some environment
       variables to make it explicit what might be set in the plugin.
       Not one of these variables is actually necessary, but they 
       make the process more scriptable.
    
       See Readme.environment for details on any variable.
    
           setenv AFNI_TRUSTHOST              localhost
           setenv AFNI_REALTIME_Registration  3D:_realtime
           setenv AFNI_REALTIME_Graph         Realtime
           setenv AFNI_REALTIME_MP_HOST_PORT  localhost:53214
           setenv AFNI_REALTIME_SEND_VER      YES
           setenv AFNI_REALTIME_SHOW_TIMES    YES
           setenv AFNI_REALTIME_Mask_Vals     ROI_means
    
           afni -rt
    
       Note: in order to send ROI averages per TR, the user must
             choose a mask in the real-time plugin.
    
    b. Start realtime_receiver.py to show received data.
    
           realtime_receiver.py -show_data yes
    
    c. Run Dimon from the AFNI_data3 directory, in real-time mode,
       using a 2 second pause to simulate the TR.  Dicom images are
       under EPI_run1, and the files start with 8HRBRAIN.
    
           Dimon -rt -pause 2000 -infile_prefix EPI_run1/8HRBRAIN
    
       Notes:
         - Dimon can be run many times at this point.
         - At the scanner, -pause might be replaced with either
           -sleep_vol or -sleep_frac.
         - It is common to apply an appropriate -sort_method here.

    --------------------

    c2. alternately, set some env vars via Dimon

         Dimon -rt -pause 2000 -infile_prefix EPI_run1/8          \
           -drive_afni 'SETENV AFNI_REALTIME_Mask_Vals=ROI_means' \
           -drive_afni 'SETENV AFNI_REALTIME_SEND_VER=Yes'        \
           -drive_afni 'SETENV AFNI_REALTIME_SHOW_TIMES=Yes'

       Note that plugout_drive can also be used to set vars at
       run-time, though plugouts must be enabled to use it.


  -------------------------------------------
  example G: when reading AFNI datasets

    Note that single-volume AFNI datasets might not contain the.
    TR and slice timing information (since they are not considered
    to be time series).  So it may be necessary to specify such
    information on the command line.

    Dimon -rt                                                  \
       -infile_pattern EPI_run1/vol.*.HEAD                     \
       -file_type AFNI -sleep_vol 1000 -sp alt+z -tr 2.0 -quit

  ---------------------------------------------------------------
  notes:

    - Once started, unless the '-quit' option is used, this
      program exits only when a fatal error occurs (single
      missing or out of order slices are not considered fatal).
      Otherwise, it keeps waiting for new data to arrive.

      With the '-quit' option, the program will terminate once
      there is a significant (~2 TR) pause in acquisition.

    - To terminate this program, use <ctrl-c>.

  ---------------------------------------------------------------
  main options:

    For DICOM images, either -infile_pattern or -infile_prefix
    is required.

    -infile_pattern PATTERN : specify pattern for input files

        e.g. -infile_pattern 'run1/i*.dcm'

        This option is used to specify a wildcard pattern matching
        the names of the input DICOM files.  These files should be
        sorted in the order that they are to be assembled, i.e.
        when the files are sorted alphabetically, they should be
        sequential slices in a volume, and the volumes should then
        progress over time (as with the 'to3d' program).

        The pattern for this option must be within quotes, because
        it will be up to the program to search for new files (that
        match the pattern), not the shell.

    -infile_prefix PREFIX   : specify prefix matching input files

        e.g. -infile_prefix run1/i

        This option is similar to -infile_pattern.  By providing
        only a prefix, the user need not use wildcard characters
        with quotes.  Using PREFIX with -infile_prefix is
        equivalent to using 'PREFIX*' with -infile_pattern (note
        the needed quotes).

        Note that it may not be a good idea to use, say 'run1/'
        for the prefix, as there might be a readme file under
        that directory.

        Note also that it is necessary to provide a '/' at the
        end, if the prefix is a directory (e.g. use run1/ instead
        of simply run1).

    -infile_list MY_FILES.txt : filenames are in MY_FILES.txt

        e.g. -infile_list subject_17_files

        If the user would rather specify a list of DICOM files to
        read, those files can be enumerated in a text file, the
        name of which would be passed to the program.

        This option implies -no_wait, making the assumption that
        all input files exist.

  ---------------------------------------------------------------
  real-time options:

    -rt                : specify to use the real-time facility

        With this option, the user tells 'Dimon' to use the real-time
        facility, passing each volume of images to an existing
        afni process on some machine (as specified by the '-host'
        option).  Whenever a new volume is acquired, it will be
        sent to the afni program for immediate update.

        Note that afni must also be started with the '-rt' option
        to make use of this.

        Note also that the '-host HOSTNAME' option is not required
        if afni is running on the same machine.

    -drive_afni CMND   : send 'drive afni' command, CMND

        e.g.  -drive_afni 'OPEN_WINDOW axialimage'

        This option is used to pass a single DRIVE_AFNI command
        to afni.  For example, 'OPEN_WINDOW axialimage' will open
        such an axial view window on the afni controller.

        Note: the command 'CMND' must be given in quotes, so that
              the shell will send it as a single parameter.

        Note: this option may be used multiple times.

        See README.driver for more details.

    -drive_wait CMND   : send delayed 'drive afni' command, CMND

        e.g.  -drive_wait 'OPEN_WINDOW axialimage'

        This option is used to pass a single DRIVE_AFNI command
        to afni.  For example, 'OPEN_WINDOW axialimage' will open
        such an axial view window on the afni controller.

        This has the same effect as '-drive_afni', except that
        the real-time plugin will wait until the next completed
        volume to execute the command.

        An example of where this is useful is so that afni 'knows'
        about a new dataset before opening the given image window,
        allowing afni to size the window appropriately.

    -fast              : process data very quickly

        short for:  -sleep_init 50 -sleep_vol 50

    -host HOSTNAME     : specify the host for afni communication

        e.g.  -host mycomputer.dot.my.network
        e.g.  -host 127.0.0.127
        e.g.  -host mycomputer
        the default host is 'localhost'

        The specified HOSTNAME represents the machine that is
        running afni.  Images will be sent to afni on this machine
        during the execution of 'Dimon'.

        Note that the environment variable AFNI_TRUSTHOST must be
        set on the machine running afni.  Set this equal to the
        name of the machine running Imon (so that afni knows to
        accept the data from the sending machine).

    -num_chan CHANNELS : specify number of channels to send over

        e.g.  -num_chan 8

        This option tells the realtime plugin how many channels to
        break incoming data into.  Each channel would then get its
        own dataset.

        Note that this simply distributes the data as it is read
        across multiple datasets.  If 12 volumes are seen in some
        directory and -num_chan 2 is specified, then volumes 0, 2,
        4, 6, 8 and 10 would go to one dataset (e.g. channel 1),
        while volumes 1,3,5,7,9,11 would go to another.

        A sample use might be for multi-echo data.  If echo pairs
        appear to Dimon sequentially over the TRs, then -num_chan
        could be used to send each echo type to its own dataset.
        This option was added for J Evans.

        Currently, -num_chan only affects the realtime use.

    -pause TIME_IN_MS : pause after each new volume

        e.g.  -pause 200

        In some cases, the user may wish to slow down a real-time
        process.  This option will cause a delay of TIME_IN_MS
        milliseconds after each volume is found.

    -rev_byte_order   : pass the reverse of the BYTEORDER to afni

        Reverse the byte order that is given to afni.  In case the
        detected byte order is not what is desired, this option
        can be used to reverse it.

        See the (obsolete) '-swap' option for more details.

    -rt_cmd COMMAND   : send COMMAND(s) to realtime plugin

        e.g.  -rt_cmd 'GRAPH_XRANGE 120'
        e.g.  -rt_cmd 'GRAPH_XRANGE 120 \n GRAPH_YRANGE 2.5'

        This option is used to pass commands to the realtime
        plugin.  For example, 'GRAPH_XRANGE 120' will set the
        x-scale of the motion graph window to 120 (repetitions).

        Note: the command 'COMMAND' must be given in quotes, so
        that the shell will send it as a single parameter.

        Note: this option may be used multiple times.

        See README.realtime for more details.

    -show_sorted_list  : display -dicom_org info and quit

        After the -dicom_org has taken effect, display the list
        of run index, image index and filenames that results.
        This option can be used as a simple review of the files
        under some directory tree, say.

        See the -show_sorted_list example under example A2.

    -sleep_init MS    : time to sleep between initial data checks

        e.g.  -sleep_init 500

        While Dimon searches for the first volume, it checks for
        files, pauses, checks, pauses, etc., until some are found.
        By default, the pause is approximately 3000 ms.

        This option, given in milliseconds, will override that
        default time.

        A small time makes the program seem more responsive.  But
        if the time is too small, and no new files are seen on
        successive checks, Dimon may think the first volume is
        complete (with too few slices).

        If the minimum time it takes for the scanner to output
        more slices is T, then 1/2 T is a reasonable -sleep_init
        time.  Note: that minimum T had better be reliable.

        The example shows a sleep time of half of a second.

        See also -fast.

    -sleep_vol MS     : time to sleep between volume checks

        e.g.  -sleep_vol 1000

        When Dimon finds some volumes and there still seems to be
        more to acquire, it sleeps for a while (and outputs '.').
        This option can be used to specify the amount of time it
        sleeps before checking again.  The default is 1.5*TR.

        The example shows a sleep time of one second.

        See also -fast.

    -sleep_frac FRAC  : new data search, fraction of TR to sleep

        e.g.  -sleep_frac 0.5

        When Dimon finds some volumes and there still seems to be
        more to acquire, it sleeps for a while (and outputs '.').
        This option can be used to specify the amount of time it
        sleeps before checking again, as a fraction of the TR.
        The default is 1.5 (as the fraction).

        The example shows a sleep time of one half of a TR.

    -swap  (obsolete) : swap data bytes before sending to afni

        Since afni may be running on a different machine, the byte
        order may differ there.  This option will force the bytes
        to be reversed, before sending the data to afni.

        ** As of version 3.0, this option should not be necessary.
           'Dimon' detects the byte order of the image data, and then
           passes that information to afni.  The realtime plugin
           will (now) decide whether to swap bytes in the viewer.

           If for some reason the user wishes to reverse the order
           from what is detected, '-rev_byte_order' can be used.

    -te_list 'TE TE TE ...' : specify a list of echo times

        e.g. -te_list '13.9 31.7 49.5'

        This option is used to pass along a list of echo times to the
        realtime plugin.  The list should be enclosed in quotes to be
        a single program argument.  It is passed to plug_realtime as
        ECHO_TIMES TE TE TE ...

    -zorder ORDER     : slice order over time

        e.g. -zorder alt
        e.g. -zorder seq
        the default is 'alt'

        This options allows the user to alter the slice
        acquisition order in real-time mode, similar to the slice
        pattern of the '-sp' option.  The main differences are:
            o  only two choices are presently available
            o  the syntax is intentionally different (from that
               of 'to3d' or the '-sp' option)

        ORDER values:
            alt   : alternating in the Z direction (over time)
            seq   : sequential in the Z direction (over time)

  ---------------------------------------------------------------
  other options:

    -debug LEVEL       : show debug information during execution

        e.g.  -debug 2
        the default level is 1, the domain is [0,3]
        the '-quiet' option is equivalent to '-debug 0'

    -dicom_org         : organize files before other processing

        e.g.  -dicom_org

        When this flag is set, the program will attempt to read in
        all files subject to -infile_prefix or -infile_pattern,
        determine which are DICOM image files, and organize them
        into an ordered list of files per run.

        This may be necessary since the alphabetized list of files
        will not always match the sequential slice and time order
        (which means, for instance, that '*.dcm' may not list
        files in the correct order.

        In this case, if the DICOM files contain a valid 'image
        number' field (0x0020 0013), then they will be sorted
        before any further processing is done.

        Notes:

        - This does not work in real-time mode, since the files
          must all be organized before processing begins.

          ** As of version 4.0, this _is_ a real-time option.

        - The DICOM images need valid 'image number' fields for
          organization to be possible (DICOM field 0x0020 0013).

        - This works will in conjunction with '-GERT_Reco', to
          create a script to make AFNI datasets.  There will be
          a single file per run that contains the image filenames
          for that run (in order).  This is fed to 'to3d'.

        - This may be used with '-save_file_list', to store the
          list of sorted filenames in an output file.

        - The images can be sorted in reverse order using the
          option, -rev_org_dir.

    -epsilon EPSILON   : specify EPSILON for 'equality' tests

        e.g.  -epsilon 0.05
        the default is 0.01

        When checking z-coordinates or differences between them
        for 'equality', a check of (difference < EPSILON) is used.
        This option lets the user specify that cutoff value.

    -file_type TYPE    : specify type of image files to be read

        e.g.  -file_type AFNI
        the default is DICOM

        Dimon will currently process GEMS 5.x or DICOM files
        (single slice or Siemens mosaic).

        possible values for TYPE:

           GEMS      : GE Medical Systems GEMS 5.x format
           DICOM     : DICOM format, possibly Siemens mosaic
           AFNI      : AFNI or NIfTI formatted datasets

    -help              : show this help information

    -hist              : display a history of program changes

    -milestones        : display a history of program milestones

    -max_images NUM    : limit on images (slices per volume)

        e.g.  -max_images 256
        default = 3000

        This variable is in case something is very messed up with
        the data, and prevents the program from continuing after
        failing to find a volume in this number of images.

    -max_quiet_trs TRS : max number of TRs without data (if -quit)

        e.g.  -max_quiet_trs 4
        default = 2

        This variable is to specify the number of TRs for which
        having no new data is okay.  After this number of TRs, it
        is assumed that the run has ended.

        The TR (duration) comes from either the image files or
        the -tr option.

    -nice INCREMENT    : adjust the nice value for the process

        e.g.  -nice 10
        the default is 0, and the maximum is 20
        a superuser may use down to the minimum of -19

        A positive INCREMENT to the nice value of a process will
        lower its priority, allowing other processes more CPU
        time.

    -no_wait           : never wait for new data

        More forceful than -quit, when using this option, the
        program should never wait for new data.  This option
        implies -quit and is implied by -gert_create_dataset.

        This is appropriate to use when the image files have
        already been collected.

    -nt VOLUMES_PER_RUN : set the number of time points per run

        e.g.  -nt 120

        With this option, if a run stalls before the specified
        VOLUMES_PER_RUN is reached (notably including the first
        run), the user will be notified.

        Without this option, Dimon will compute the expected number
        of time points per run based on the first run (and will
        allow the value to increase based on subsequent runs).
        Therefore Dimon would not detect a stalled first run.

    -num_slices SLICES  : slices per volume must match this

        e.g.  -num_slices 34

        Setting this puts a restriction on the first volume
        search, requiring the number of slices found to match.

        This prevents odd failures at the scanner, which does not
        necessarily write out all files for the first volume
        before writing some file from the second.

    -quiet             : show only errors and final information

    -quit              : quit when there is no new data

        With this option, the program will terminate once a delay
        in new data occurs (an apparent end-of-run pause).

        This option is implied by -no_wait.

    -order_as_zt       : change order from -time:tz to -time_zt

        e.g.  -rev_org_dir

        Assuming the images are initially sorted in to3d's -time:tz
        order (meaning across images, time changes first and slice
        position changes next, i.e. all time points for the first slice
        come first, then all time points for the next slice), re-order
        the images into the -time:zt order (meaning all slices at the
        first time point come first, then all slices at the next, etc).
        
        Note that -time:zt is the usual order expected with Dimon, since
        it was intended for real-time use (when all slices for a given
        time point come together).

        This option implies -read_all.

      * This is a post-sort operation.  Images will be initially sorted
        based on the other options, then they will be shuffled into the
        slice-minor order (volumes of slices grouped over time).

      * This should probably not be used on a real-time system.

        See 'to3d -help' for the -time options.

    -read_all          : read all images at once

        e.g.  -read_all

           ** June 2024: this option is now set by default **

        There was originally a limit on the number of images initially
        read or stored at any one time, using this option is to remove
        that limit.  The program was changed in June 2024 to always
        apply -read_all.

        It uses more memory, but is particularly important if sorting
        should be done over a complete image list (even just out of
        those currently written).

    -rev_org_dir       : reverse the sort in dicom_org

        e.g.  -rev_org_dir

        With the -dicom_org option, the program will attempt to
        organize the DICOM files with respect to run and image
        numbers.  Normally that is an ascending sort.  With this
        option, the sort is reversed.

        see also: -dicom_org

    -rev_sort_dir      : reverse the alphabetical sort on names

        e.g.  -rev_sort_dir

        With this option, the program will sort the input files
        in descending order, as opposed to ascending order.

    -save_file_list FILENAME : store the list of sorted files

        e.g.  -save_file_list dicom_file_list

        With this option the program will store the list of files,
        sorted via -dicom_org, in the output file, FILENAME.  The
        user may wish to have a separate list of the files.

        Note: this option no longer requires '-dicom_org'.

    -save_details FILE_PREFIX : save details about images

        e.g.  -save_defails dicom_details

        With this option the program will store the list of files,
        along with many details for each image file.

        It is akin to -save_file_list, only with extra information.

        Fields:

           index     : current index
           findex    : index in main finfo_t list (as found)
           sindex    : sorting index (-1 if not used)
           state     : current state (<=0:bad, 1=good, >1=todo)
           errs      : reading errors

           zoff      : slice coordinate
           diff      : difference from previous coordinate
           data      : have data
           run       : apparent run index
           IIND      : image index (DICOM 0054 1330)
           RIN       : image instance number (DICOM 0020 0013)
           GEMEIND   : GE multi-echo index (DICOM RawDataRunNumber)
           ATIME     : Acquisition time (DICOM 0008 0032)

    -save_errors          : save 'details' files on search/match errors

        e.g.  -save_errors -save_details dicom_details

        For use with -save_details, the option causes extra details
        files to be written upon any volume_search or volume_match
        errors.

    -sort_by_acq_time  : sort files by acquisition time

        e.g.  -dicom_org -sort_by_acq_time

        When this option is used with -dicom_org, the program will
        sort DICOM images according to:
           run, acq time, image index and image number

        For instance, Philips files may have 0020 0013 (Inst. Num)
        fields that are ordered as slice-major (volume minor).
        But since slice needs to be the minor number, Acquisition
        Time may be used for the major sort, before Instance Num.
        So sort first by Acquisition Num, then by Instance.

        Consider example B2.

    -sort_by_num_suffix : sort files according to numerical suffix

        e.g.  -sort_by_num_suffix

        With this option, the program will sort the input files
        according to the trailing '.NUMBER' in the filename.  This
        NUMBER will be evaluated as a positive integer, not via
        an alphabetic sort (so numbers need not be zero-padded).

        This is intended for use on files which are usefully enumerated
        in the filename suffix.
        Consider a set of names for a single, interleaved volume:

          im001.1  im002.3  im003.5  im004.7  im005.9  im006.11
          im007.2  im008.4  im009.6  im010.8  im011.10

        Here the image prefixes are in the order of acquisition, and
        were interleaved.  So an alphabetical sort is not ordered by the
        slice position (z-order).  However the slice ordering was
        encoded in the suffix of the filenames..

        NOTE: the suffix numbers should be unique.

        NOTE: this is a pre-sort method, akin to reading files
              alphabetically.  One can still apply -sort_method,
              which would sort the resulting list based on other
              information.

    -sort_method METHOD : apply METHOD for real-time sorting

        e.g. -sort_method geme_index

        This option is used to specify the sorting method to apply
        to image structures after they have been read in.

        methods:

           none            : do not apply any real-time sorting
           acq_time        : by acquisition time, if set
           default         : sort by run, [ATIME], IIND, RIN
           geme_index      : by GE multi-echo index
                           - alphabetical, but for each grouping of
                             ge_me_index values, sort by that
           geme_rin        : modulo sort by RIN, subsort by echo/RIN
           geme_suid       : pre-sort by SOP IUID (0008 0018)
                             as a major/minor pair, then by geme_index
           geme_xnat       : pre-sort by RIN, then sort by geme_index
           num_suffix      : based on numeric suffix
           rin             : sort by RIN (0020 0013)
           zposn           : based on z-coordinate and input order

        more detailed method descriptions:

           none

             Do not perform any real-time sorting.  One can still apply
             a pre-read name-based sort, such as -sort_by_num_suffix.

           acq_time

             Try to sort by acquisition time, if set.  This may apply
             to Philps images.

           default

             Sort by run, acq_time (maybe), image index (0054 1330),
             and REL Instance Number, or RIN (0020 0013).

           geme_index

             This is for the GE multi-echo sequence.  Sort the list of
             images in groups of nslices*nechos (which should match
             'Images in Acquisition' in the Dicom header).  Each such
             set of images should have the same GE_ME_INDEX sequence,
             starting from some arbitrary offset.

             Note that the actual file order is somewhat unspecified,
             except that for a given geme_index, the files should be
             chronological.

           geme_rin

             Sort GE multi-echo images by RIN (0020 0013).

             This method essentially does a pre-sort by RIN (possibly
             implied by -sort_by_num_suffix, before images are
             actually read in), followed by a secondard grouped sort.

             Note that for this method to work in real-time mode, the
             input files must be either alphabetized in RIN order, or
             there must be numerical RIN-order file suffix, to pre-sort 
             using -sort_by_num_suffix.  Without that, real-time sorting
             might not work.

             In non-real-time mode (using -dicom_org), all images are
             read up front, so the RIN sorting can simply come from
             that DICOM field.

             Given that the images are first sorted by RIN, then they
             are sub-sorted in groups of NES
                   NES = nechos * nslices_per_volume
             where the major axis is echo number (ACQ Echo Number),
             and the minor axis is RIN (could be slice or GEME_INDEX).

                   0020 0013 - RIN - Instance Number
                   0018 0086 - echo - ACQ Echo Number

             Basically, for each echo, that set of NES slices is sorted
             together.  That effectively makes the overall sort as:

                major 1 : time point (multiple echos and volume slices)
                          (has NES slices per time point = echo volumes)
                major 2 : echo number
                          (each echo in this group is a single volume)
                minor   : slice (within that echo of that volume)

           geme_suid

             Like geme_index and geme_rin, but pre-sort by SOP IUID,
             rather than by alphabetical index.

             The SOP IUID (0008 0018), evaluated as a major and minor
             index pair (taking the 2 most minor '.' fields as indexes)
             is used as an initial sorting of the images, not depending
             on file name ordering.

           geme_xnat

             Like geme_index, but pre-sort by RIN, rather than by
             alphabetical index.

           num_suffix

             Sort by numerical file suffix (e.g. image.01234).

           rin

             Sort by RIN (0020 0013).  

           zposn

             Sort by z-coordinate.  This is limited to a single volume
             window of images, so num_slices should be set if there is
             more than 1 volume.

    -start_file S_FILE : have Dimon process starting at S_FILE

        e.g.  -start_file 043/I.901

        With this option, any earlier I-files will be ignored
        by Dimon.  This is a good way to start processing a later
        run, if it desired not to look at the earlier data.

        In this example, all files in directories 003 and 023
        would be ignored, along with everything in 043 up through
        I.900.  So 043/I.901 might be the first file in run 2.

    -tr TR             : specify the TR, in seconds

        e.g.  -tr 5.0

        In the case where volumes are acquired in clusters, the TR
        is different than the time needed to acquire one volume.
        But some scanners incorrectly store the latter time in the
        TR field.
        
        This option allows the user to override what is found in
        the image files, which is particularly useul in real-time
        mode, though is also important to have stored properly in
        the final EPI datasets.

        Here, TR is in seconds.

    -use_imon          : revert to Imon functionality

        ** This option is deprecated.
           Use -file_type GEMS, instead.

    -assume_dicom_mosaic : as stated, useful for 3D format

        Siemens 3D DICOM image files use a different type of mosaic
        format, missing the indicator string.  This option matches
        that for to3d.

    -use_last_elem     : use the last elements when reading DICOM

        In some poorly created DICOM image files, some elements
        are listed incorrectly, before being listed correctly.

        Use the option to search for the last occurrence of each
        element, not necessarily the first.

    -use_slice_loc     : use REL Slice Loc for z offset

        REL Slice Location, 0020 1041, is sometimes used for the
        z offset, rather than Image Position.
        
        Use this option to set slice offsets according to SLoc.

    -ushort2float      : convert short datasets to float in to3d

        By default, if short integer datasets appear to be unsigned
        shorts, Dimon will add a similar -ushort2float to the to3d
        command when creating AFNI datasets (via -gert_create_dataset).

        But if some runs need conversion and others do not, one can
        have a mix of types across runs.  Then one basically needs to
        decide whether to use floats for all subjects, one subject at a
        time, or to perform some conversion that removes the large
        shorts.

        Applying -ushort2float in Dimon will result in passing it to
        any to3d commands (if -gert_create_dataset is applied), which
        would have all short datasets converted to float32.

    -version           : show the version information

  ---------------------------------------------------------------
  GERT_Reco options:

    -GERT_Reco        : output a GERT_Reco_dicom script

        Create a script called 'GERT_Reco_dicom', similar to the
        one that Ifile creates.  This script may be run to create
        the AFNI datasets corresponding to the I-files.

    -gert_create_dataset     : actually create the output dataset

        Execute any GERT_Reco script, creating the AFNI or NIfTI
        datasets.

        This option implies -GERT_Reco and -quit.

        See also -gert_write_as_nifti.

    -gert_filename FILENAME : save GERT_Reco as FILENAME

        e.g. -gert_filename gert_reco_anat

        This option can be used to specify the name of the script,
        as opposed to using GERT_Reco_dicom.

        By default, if the script is generated for a single run,
        it will be named GERT_Reco_dicom_NNN, where 'NNN' is the
        run number found in the image files.  If it is generated
        for multiple runs, then the default it to name it simply
        GERT_Reco_dicom.

    -gert_nz NZ        : specify the number of slices in a mosaic

        e.g. -gert_nz 42

        Dimon happens to be able to write valid to3d commands
        for mosaic (volume) data, even though it is intended for
        slices.  In the case of mosaics, the user must specify the
        number of slices in an image file, or any GERT_Reco script
        will specify nz as 1.

    -gert_outdir OUTPUT_DIR  : set output directory in GERT_Reco

        e.g. -gert_outdir subject_A7
        e.g. -od subject_A7
        the default is '-gert_outdir .'

        This will add '-od OUTPUT_DIR' to the @RenamePanga command
        in the GERT_Reco script, creating new datasets in the
        OUTPUT_DIR directory, instead of the 'afni' directory.

    -sp SLICE_PATTERN  : set output slice pattern in GERT_Reco

        e.g. -sp alt-z
        the default is 'alt+z'

        This options allows the user to alter the slice
        acquisition pattern in the GERT_Reco script.

        See 'to3d -help' for more information.

    -gert_to3d_prefix PREFIX : set to3d PREFIX in output script

        e.g. -gert_to3d_prefix anatomy
        e.g. -gert_to3d_prefix epi.nii.gz

        When creating a GERT_Reco script that calls 'to3d', this
        option will be applied to '-prefix'.

        The default prefix is 'OutBrick_run_NNN', where NNN is the
        run number found in the images.

        Use a NIFTI suffix to create a NIFTI dataset.

      * Caution: this option should only be used when the output
        is for a single run.

    -gert_chan_digits N_DIG : use N_DIG digits for channel number

        e.g. -gert_chan_digits 1

        When creating a GERT_Reco script that calls 'to3d' in the case
        of multi-channel (or echo) data, use this option to specify the
        number of digits in the channel/echo part of the prefix.

    -gert_chan_prefix PREFIX : use PREFIX instead of _chan_ in dsets

        e.g. -gert_chan_prefix _echo_

        When creating a GERT_Reco script that calls 'to3d' in the case
        of multi-channel (or echo) data, this option overrides the
        _chan_ part of the prefix.

        Instead of naming the result as in:
            OutBrick_run_003_chan_001+orig.HEAD
        the name would use PREFIX, e.g. _echo_, in place of _chan_:
            OutBrick_run_003_echo_001+orig.HEAD

    -gert_write_as_nifti     : output dataset should be in NIFTI format

        By default, datasets created by the GERT_Reco script will be in 
        AFNI format.  Use this option to create them in NIfTI format,
        instead.  These merely appends a .nii to the -prefix option of
        the to3d command.

        This option is not necessary if -gert_to3d_prefix is NIFTI.

        See also -gert_create_dataset, -gert_to3d_prefix.

    -gert_quit_on_err : Add -quit_on_err option to to3d command
                        which has the effect of causing to3d to 
                        fail rather than come up in interactive
                        mode if the input has an error.

    -use_obl_origin    : if oblique, pass -oblique_origin to to3d

        This will usually apply a more accurate origin to the volume.
        Maybe this will become the default operation in the future.

  ---------------------------------------------------------------

  Author: R. Reynolds - version 4.34 (September 5, 2024)
This page auto-generated on Tue Dec 17 06:54:35 PM EST 2024