# 3dSliceNDice¶

## OVERVIEW¶

This program is for calculating the Dice coefficient between two
volumes on a slice-by-slice basis.  The user enters two volumes on the
same grid, and Dice coefficients along each axis are calculated; three
separate text (*.1D) files are output.

The Dice coefficient (Dice, 1945) is known by many names and in many
applications.  In the present context it is defined as follows.
Consider two sets voxels (i.e., masks), A and B.  The Dice coefficient
D is the ratio of their intersection to their union. Let N(x) be a
function that calculates the number of voxels in a set x. Then:

D = 2*N(intersection of A and B)/(N(A) + N(B)).

The range of D is 0 (no overlap of A and B at all) to 1 (perfect
overlap of A and B), inclusively.

This program calculates D in a slicewise manner across all 3 major
axes of a dset; other programs of interest for a volumewise Dice
coefficient or more general overlap calculations include 3dABoverlap,
for example.

Nonzero values in a dset are considered part of the mask.  3dcalc
might be useful in creating a mask from a dset if things like
thresholding are required.

written by PA Taylor (NIMH, NIH).


## USAGE¶

    Input:
+ two single-volume datasets

Output:

+ three text files, each a *.1D file of columns of numbers (and
note that the executed 3dSliceNDice command is echoed into a
comment in the top line of each 1D file by output). File name
indicates along which axis the particular results were
calculated, such as ending in '0_RL.1D', '1_AP.1D', '2_IS.1D',
etc.

For each file, there are currently 5 columns of data output,
in the following order:
[index] the i, j, or k index of the slice (starting from 0).
[coord] the x, y, or z coordinate of the slice.
[size of A ROI] the number of voxels in set A's ROI in the slice.
[size of B ROI] the number of voxels in set B's ROI in the slice.
[Dice coef] the Dice coefficient of that slice.

1dplot can be useful for viewing output results quickly.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


## COMMAND¶

    3dSliceNDice                                  \
-insetA    AA                             \
-insetB    BB                             \
-prefix    PP                             \
{-out_range all|AorB|AandB}

where

-insetA    AA   :name of an input set to make a mask from; mask will
be made from nonzero values in AA;
-insetB    BB   :name of an input set to make a mask from; mask will
be made from nonzero values in BB;

-prefix    PP   :prefix of output files.
Three output text files will be named
according to the orientation of the input AA
and BB files.  So, outputs might look like:
PP_0_RL.1D or PP_0_RL.1D,
PP_1_AP.1D or PP_0_PA.1D,
PP_2_IS.1D or PP_0_SI.1D.

-out_domain all|AorB|AandB
:optional specification of the slices over which to
output Dice coefficient results along each axis,
via keyword.  Argument options at present:
'all':   report Dice values for all slices (default);
'AorB':  report values only in slices where sets A or
B (or both) have at least one nonzero voxel;
'AandB': report values only in slices where both sets
A and B have at least one nonzero voxel;
'Amask': report values only in slices where set A
has at least one nonzero voxel;
'Bmask': report values only in slices where set B
has at least one nonzero voxel;

-no_cmd_echo    :turn OFF recording the command line call to
3dSliceNDice in the output *.1D files (default is
to do the recording).

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


## EXAMPLES¶

1. Report slicewise overlap of two masks through full FOV along each
axis.
3dSliceNDice                  \

2. Report slicewise overlap of two masks only for slices where both
dsets have >0 voxels in their masks
3dSliceNDice                  \
-out_domain AandB         \