:orphan:
.. _ahelp_3dmaskave:
*********
3dmaskave
*********
.. contents:: :local:

.. codeblock:: none
Usage: 3dmaskave [options] inputdataset
Computes average of all voxels in the input dataset
which satisfy the criterion in the options list.
If no options are given, then all voxels are included.

Examples:
1. compute the average timeseries in epi_r1+orig, over voxels
that are set (any nonzero value) in the dataset, ROI+orig:
3dmaskave mask ROI+orig epi_r1+orig
2. restrict the ROI to values of 3 or 4, and save (redirect)
the output to the text file run1_roi_34.txt:
3dmaskave mask ROI+orig quiet mrange 3 4 \
epi_r1+orig > run1_roi_34.txt
3. Extract the time series from a single voxel with given
spatial indexes (e.g., for use with 3dTcorr1D):
3dmaskave quiet ibox 40 30 20 epi_r1+orig > r1_40_30_20.1D

Options:
mask mset Means to use the dataset 'mset' as a mask:
Only voxels with nonzero values in 'mset'
will be averaged from 'dataset'. Note
that the mask dataset and the input dataset
must have the same number of voxels.
SPECIAL CASE: If 'mset' is the string 'SELF',
then the input dataset will be
used to mask itself. That is,
only nonzero voxels from the
#miv subbrick will be used.
mindex miv Means to use subbrick #'miv' from the mask
dataset. If not given, miv=0.
mrange a b Means to further restrict the voxels from
'mset' so that only those mask values
between 'a' and 'b' (inclusive) will
be used. If this option is not given,
all nonzero values from 'mset' are used.
Note that if a voxel is zero in 'mset', then
it won't be included, even if a < 0 < b.
[mindex and mrange are old options that predate]
[the introduction of the subbrick selector '[]' ]
[and the subrange value selector '<>' to AFNI. ]
xbox x y z } These options are the same as in
dbox x y z } program 3dmaskdump:
nbox x y z } They create a mask by putting down boxes
ibox x y z } or balls (filled spheres) at the specified
xball x y z r } locations. See the output of
dball x y z r } 3dmaskdump help
nball x y z r } for the gruesome and tedious details.
https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dmaskdump.html
dindex div Means to use subbrick #'div' from the inputdataset.
If not given, all subbricks will be processed.
drange a b Means to only include voxels from the inputdataset whose
values fall in the range 'a' to 'b' (inclusive).
Otherwise, all voxel values are included.
[dindex and drange are old options that predate]
[the introduction of the subbrick selector '[]' ]
[and the subrange value selector '<>' to AFNI. ]
slices p q Means to only included voxels from the inputdataset
whose slice numbers are in the range 'p' to 'q'
(inclusive). Slice numbers range from 0 to
NZ1, where NZ can be determined from the output
of program 3dinfo. The default is to include
data from all slices.
[There is no provision for geometrical voxel]
[selection except in the slice (z) direction]
sigma Means to compute the standard deviation in addition
to the mean.
sum Means to compute the sum instead of the mean.
sumsq Means to compute the sum of squares instead of the mean.
enorm Means to compute the Euclidean norm instead of the mean.
This is the sqrt() of the sumsq result.
median Means to compute the median instead of the mean.
max Means to compute the max instead of the mean.
min Means to compute the min instead of the mean.
[sigma is ignored with sum, median, max, or min.]
[the last given of sum, median, max, or min wins.]
perc XX Means to compute the XXth percentile value (min=0 max=100).
XX should be an integer from 0 to 100.
dump Means to print out all the voxel values that
go into the result.
udump Means to print out all the voxel values that
go into the average, UNSCALED by any internal
factors.
N.B.: the scale factors for a subbrick
can be found using program 3dinfo.
indump Means to print out the voxel indexes (i,j,k) for
each dumped voxel. Has no effect if dump
or udump is not also used.
N.B.: if nx,ny,nz are the number of voxels in
each direction, then the array offset
in the brick corresponding to (i,j,k)
is i+j*nx+k*nx*ny.
q or
quiet Means to print only the minimal numerical result(s).
This is useful if you want to create a *.1D file,
without any extra text; for example:
533.814 [18908 voxels] == 'normal' output
533.814 == 'quiet' output
The output is printed to stdout (the terminal), and can be
saved to a file using the usual redirection operation '>'.
Or you can do fun stuff like
3dmaskave q mask Mfile+orig timefile+orig  1dplot stdin nopush
to pipe the output of 3dmaskave into 1dplot for graphing.
 Author: RWCox
INPUT DATASET NAMES

This program accepts datasets that are modified on input according to the
following schemes:
'r1+orig[3..5]' {subbrick selector}
'r1+orig<100..200>' {subrange selector}
'r1+orig[3..5]<100..200>' {both selectors}
'3dcalc( a r1+orig b r2+orig expr 0.5*(a+b) )' {calculation}
For the gruesome details, see the output of 'afni help'.
++ Compile date = May 11 2021 {AFNI_21.1.07:linux_ubuntu_16_64}