3dGenPriors produces classification priors based on voxel signatures.
At this stage, its main purpose is to speed up the performance of
3dSignatures when using the probabilistic method as opposed to SVM.
Example:
3dGenPriors -sig sigs+orig \
-tdist train.niml.td \
-pprefix anat.p \
-cprefix anat.c \
-labeltable DSC.niml.lt \
-do pc
Options:
-sig SIGS: Signatures dataset. A dataset with F features per voxel.
-tdist TDIST: Training results. This file is generated by 3dSignatures.
ONLY training files generated by 3dSignatures' method 'prob'
can be used by this program. The number of features in this
file should match the number of features (F) in SIGS
This file also contains the names of the K classes that
will be references in the output datasets
-prefix PREF: Specify root prefix and let program suffix it for output
Volumes. This way you need not use the -*prefix options
below.
-pprefix PPREF: Prefix for probability dset
-cprefix CPREF: Prefix for class dset
If you use -regroup_classes then you can also specify:
-pgprefix PGPREF, and -cgprefix CGPREF
-labeltable LTFILE: Labeltable to attach to output dset
This labeltable should contain all the classes
in TDIST
-cmask CMASK: Provide cmask expression. Voxels where expression is 0
are excluded from computations
-mask MASK: Provide mask dset
To run the program on one voxel only, you can set MASK to
the key word VOX_DEBUG. In this mode a mask is created
with only the one voxel specified in -vox_debug set to 1.
-mrange M0 M1: Consider MASK only for values between M0 and M1, inclusive
-do WHAT: Specify the output that this program should create.
Each character in WHAT specifies an output.
a 'c' produces the most likely class
a 'p' produces probability of belonging to a class
a 'pc' produces both of the above and that is the default.
You'd be deranged to use anything else at the moment.
-debug DBG: Set debug level
-vox_debug 1D_DBG_INDEX: 1D index of voxel to debug.
OR
-vox_debug I J K: where I, J, K are the 3D voxel indices
(not RAI coordinates in mm)
-vox_debug_file DBG_OUTPUT_FILE: File in which debug information is output
use '-' for stdout, '+' for stderr.
-uid UID : User identifier string. It is used to generate names for
temporary files to speed up the process.
You must use different UID for different subjects otherwise
you will run the risk of using bad temporary files.
By default, uid is set to a random string.
-use_tmp: Use temporary storage to speed up the program (see -uid )
This is the default
-no_tmp: Opposite of use_tmp
-pset PSET: Reuse probability output from an earlier run.
-cset CSET: Reuse classification output from an earlier run.
-regroup_classes 'C1 C2 C3': Regroup classes into parent classes C1 C2 C3
For this to work, the original classes must
be named something like C1.*, C2.*, etc.
This option can be used to replace @RegroupLabels script.
For example:
3dGenPriors -sig sigs+orig \
-tdist train.niml.td \
-pprefix anat.p \
-cprefix anat.c \
-labeltable DSC.niml.lt \
-do pc \
-regroup_classes 'CSF GM WM Out'
or if you have the output already, you can do:
3dGenPriors -sig sigs+orig \
-tdist train.niml.td \
-pset anat.p \
-cset anat.c \
-labeltable DSC.niml.lt \
-do pc \
-regroup_classes 'CSF GM WM Out'
-classes 'C1 C2 C3': Classify into these classes only. Alternative is
to classify from all the classes in the training data
-features 'F1 F2 F3 ...': Use these features only. Otherwise use all
features in the signature file will be used.
Note that partial matching is used to resolve
which features to keep from training set. If you
want exact feature name matching, use
option -strict_feature_match
-strict_feature_match: Use strict feature name matching when resolving
which feature to keep from the training set.
-featgroups 'G1 G2 G3 ...': TO BE WRITTEN
Example: -featgroups 'MEDI MAD. P2S'
-ShowThisDist DIST: Show information obtained from the training data about
the distribution of DIST. For example: -
-ShowThisDist 'd(mean.20_mm|PER02)'
Set DIST to ALL to see them all.
-fast: Use OpenMPized routines (default).
Considerably faster than alternative.
-slow: Not -fast.
=========================================================================
* This binary version of 3dGenPriors is compiled using OpenMP, a semi-
automatic parallelizer software toolkit, which splits the work across
multiple CPUs/cores on the same shared memory computer.
* OpenMP is NOT like MPI -- it does not work with CPUs connected only
by a network (e.g., OpenMP doesn't work across cluster nodes).
* For some implementation and compilation details, please see
https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
* The number of CPU threads used will default to the maximum number on
your system. You can control this value by setting environment variable
OMP_NUM_THREADS to some smaller value (including 1).
* Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of
using all CPUs available.
++ However, on some systems, it seems to be necessary to set variable
OMP_NUM_THREADS explicitly, or you only get one CPU.
++ On other systems with many CPUS, you probably want to limit the CPU
count, since using more than (say) 16 threads is probably useless.
* You must set OMP_NUM_THREADS in the shell BEFORE running the program,
since OpenMP queries this variable BEFORE the program actually starts.
++ You can't usefully set this variable in your ~/.afnirc file or on the
command line with the '-D' option.
* How many threads are useful? That varies with the program, and how well
it was coded. You'll have to experiment on your own systems!
* The number of CPUs on this particular computer system is ...... 1.
* The maximum number of CPUs that will be used is now set to .... 1.
