AFNI program: 3dSurfMaskDump
Output of -help
3dSurfMaskDump - dump ascii dataset values corresponding to a surface
This program is used to display AFNI dataset values that
correspond to a surface. The surface points are mapped to xyz
coordinates, according to the SURF_VOL (surface volume) AFNI
dataset. These coordinates are then matched to voxels in other
AFNI datasets. So given any other AFNI dataset, this program
can output all of the sub-brick values that correspond to each
of the suface locations. The user also has options to mask
regions for output.
Different mappings are allowed from the surface(s) to the grid
parent dataset. The mapping function is a required parameter to
the program.
The current mapping functions are:
ave : for each node pair (from 2 surfaces), output the
average of all voxel values along that line
segment
mask : each node in the surface is mapped to one voxel
midpoint : for each node pair (from 2 surfaces), output the
dataset value at their midpoint (in xyz space)
usage: 3dSurfMaskDump [options] -spec SPEC_FILE -sv SURF_VOL \
-grid_parent AFNI_DSET -map_func MAP_FUNC
examples:
3dSurfMaskDump \
-spec fred.spec \
-sv fred_anat+orig \
-grid_parent fred_anat+orig \
-map_func mask \
3dSurfMaskDump \
-spec fred.spec \
-sv fred_anat+orig \
-grid_parent 'fred_epi+orig[0]' \
-map_func mask \
-cmask '-a fred_func+orig[2] -expr step(a-0.6)' \
-debug 2 \
-output fred_surf_vals.txt
3dSurfMaskDump \
-spec fred.spec \
-sv fred_anat+orig \
-grid_parent fred_anat+orig \
-map_func ave \
-m2_steps 10 \
-m2_index nodes \
-cmask '-a fred_func+orig[2] -expr step(a-0.6)' \
-output fred_surf_ave.txt
REQUIRED COMMAND ARGUMENTS:
-spec SPEC_FILE : SUMA spec file
e.g. -spec fred.spec
The surface specification file contains the list of
mappable surfaces that are used.
See @SUMA_Make_Spec_FS and @SUMA_Make_Spec_SF.
-sv SURFACE_VOLUME : AFNI dataset
e.g. -sv fred_anat+orig
This is the AFNI dataset that the surface is mapped to.
This dataset is used for the intial surface node to xyz
coordinate mapping, in the Dicomm orientation.
-grid_parent AFNI_DSET : AFNI dataset
e.g. -grid_parent fred_function+orig
This dataset is used as a grid and orientation master
for the output. Output coordinates are based upon
this dataset.
-map_func MAP_FUNC : surface to dataset function
e.g. -map_func ave
e.g. -map_func ave -m2_steps 10
e.g. -map_func ave -m2_steps 10 -m2_index nodes
e.g. -map_func mask
e.g. -map_func midpoint
Given one or more surfaces, there are many ways to
select voxel locations, and to select corresponding
values for the output dataset. Some of the functions
will have separate options.
The current mapping functions are:
ave : Given 2 related surfaces, for each node
pair, output the average of the dataset
values located along the segment joining
those nodes.
-m2_steps NUM_STEPS :
The -m2_steps option may be added here, to
specify the number of points to use in the
average. The default and minimum is 2.
e.g. -map_func ave -m2_steps 10
default: -m2_steps 2
-m2_index TYPE :
The -m2_index options is used to specify
whether the average is taken by indexing
over distict nodes or over distict voxels.
For instance, when taking the average along
one node pair segment using 10 node steps,
perhaps 3 of those nodes may occupy one
particular voxel. In this case, does the
user want the voxel counted only once, or 3
times? Each case makes sense.
Note that this will only make sense when
used along with the '-m2_steps' option.
Possible values are "nodes", "voxels".
The default value is voxels. So each voxel
along a segment will be counted only once.
e.g. -m2_index nodes
e.g. -m2_index voxels
default: -m2_index voxels
mask : For each surface xyz location, output the
dataset values of each sub-brick.
midpoint : Given 2 related surfaces, for each node
pair, output the dataset value with xyz
coordinates at the midpoint of the nodes.
options:
-cmask MASK_COMMAND : (optional) command for dataset mask
e.g. -cmask '-a fred_func+orig[2] -expr step(a-0.8)'
This option will produce a mask to be applied to the
output dataset. Note that this mask should form a
single sub-brick.
This option follows the style of 3dmaskdump (since the
code for it was, uh, borrowed from there (thanks Bob!)).
See '3dmaskdump -help' for more information.
-debug LEVEL : (optional) verbose output
e.g. -debug 2
This option is used to print out status information
during the execution of the program. Current levels are
from 0 to 4.
-help : show this help
If you can't get help here, please get help somewhere.
-outfile OUTPUT_FILE : specify a file for the output
e.g. -outfile some_output_file
e.g. -outfile mask_values_over_dataset.txt
e.g. -outfile stderr
default: write to stdout
This is where the user will specify which file they want
the output to be written to. Note that the output file
should not yet exist.
Two special (valid) cases are stdout and stderr, either
of which may be specified.
-noscale : no scale factor in output dataset
If the output dataset is an integer type (byte, shorts
or ints), then the output dataset may end up with a
scale factor attached (see 3dcalc -help). With this
option, the output dataset will not be scaled.
-version : show version information
Show version and compile date.
Author: R. Reynolds - version 2.3 (July 21, 2003)
(many thanks to Z. Saad and R.W. Cox)
This page auto-generated on
Fri Jan 30 20:02:25 EST 2009