:orphan: .. _ahelp_Dimon: ***** Dimon ***** .. contents:: :local: | .. code-block:: none 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 . --------------------------------------------------------------- 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 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 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 approriately 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 complete real-time system): ** consider AFNI_data6/realtime.demos/demo.2.fback.* 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 Note that Dimon can be run many times at this point. -------------------- 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 . --------------------------------------------------------------- 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 optins 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 -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 There is typically a limit on the number of images initially read or stored at any one time. This option is to remove that limit. It uses more memory, but is particularly important if sorting should be done over a complete image list. -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 acqusition time, if set default : sort by run, [ATIME], IIND, RIN geme_index : by GE multi-echo index num_suffix : based on numeric suffix zposn : based on z-coordinate and input order rin : sort by RIN (0020 0013) geme_rin : sort by RIN, subsort by echo/RIN 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. num_suffix Sort by numerical file suffix (e.g. image.01234). 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. rin Sort by RIN (0020 0013). 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 Nnumber 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) -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 numbr 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 channe/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.30 (April 22, 2022)