afni [options] [session_directory ...]
-bysub This new [01 Feb 2018] option allows you to have 'sessions'
made up from files scattered across multiple directories.
The purpose of this option is to gather all the datasets
corresponding to a single subject identifier, as is done
in the BIDS file hierarchy -- [bids.neuroimaging.io]
** After '-bysub' you put one or more subject identifiers,
which are of the form 'sub-XXX' where 'XXX' is some
subject code (it does not have to be exactly 3 characters).
** If an identifier does NOT start with 'sub-', then that
4 letter string will be added to the front. This allows
you to specify your subjects by their numbers 'XXX' alone.
** The list of subject identifiers ends when an argument
on the command line starts with the '-' character.
That would be another option, or the '-' character
by itself if the next things on the command line
are the list of directories to scan for datasets.
** Each directory on the command line (after all options)
will be scanned recursively (down the file tree) for
subdirectories whose name matches the 'sub-XXX' identifier
exactly. All such subdirectories will have all their
datasets read in (recursively down the file tree) and
put into a single session for viewing in AFNI.
** Remember: if no directories are given on the command
line after the various options, then the current working
directory ('.' or 'echo $cwd') is used.
** If a directory on the command line does NOT have any
subdirectories that match any of the '-bysub' identifiers,
then that directory will be read in the normal way, with
all the datasets in that particular directory (but not
subdirectories) read into the session.
** Please note that '-bysub' sessions will NOT be rescanned
for new datasets that might get placed there after the
AFNI GUI starts, unlike normal (single directory) sessions.
** Example:
afni -bysub 10506 50073 - ~/data/OpenFMRI/ds000030
This will open the data for subjects 10506 and 50073 from
the data at the specified directory -- presumably the
data downloaded from [openfmri.org]
** If directory sub-10506 is found and has (say) sub-directories
anat beh dwi func
all AFNI-readable datasets from these sub-directories will
be input and collected into one session, to be easily
viewed together. In addition, if a sub-directory named
derivatives/sub-10506
is found underneath ~/data/OpenFMRI/ds000030, all the
datasets found underneath that will also be put into the
same session, so they can be viewed with the 'raw' data.
** In this context, 'dataset' also means .png and .jpg files
found in the sub-XXX directories. These images can be
opened in the AFNI GUI using the Axial image viewer.
(You might want to turn the AFNI crosshairs off!)
** If you do NOT want .png and .jpg files read into AFNI,
set UNIX environment variable AFNI_IMAGE_DATASETS to 'NO'.
** You can put multiple subject IDs after '-bysub', as
in the example above. You can also use the '-bysub' option
more than once, if you like. Each distinct subect ID will
get a distinct AFNI session.
