= mri_seg_overlap =

This page proposes a new program, called `mri_seg_overlap`, that will replace the redundant (and buggy/slow) `mri_compute_seg_overlap` and `mri_compute_overlap`. A primary new feature is the ability to save a detailed overlap report to a JSON file.

{{{
USAGE
	mri_seg_overlap [options] <vol1> <vol2>

DESCRIPTION
	
	This program computes the structural overlap between two segmentation 
	volumes. The following statistics can be calculated for each label:
	
	     dice coefficient     -  F1-measure of the similarity between
	                             the two labels.
	     jaccard coefficient  -  Intersecting volume over the combined
	                             volume of the two labels.
	     volume difference    -  Fractional difference in volumes of
	                             the labels.
	
	By default, only dice scores are computed, but this can be 
	reconfigured with the --measures flag.
	
	Each structure in the input volumes will be considered by default, but
	an alternative list of labels can be specified with the --label or --labelfile
	flags. Additionally, the --seg flag will compute the overlap between 
	the following 12 major anatomical structures:
	
	     Cerebral White Matter (2,41)
	     Cerebral Cortex (3,42)
	     Hippocampus (17,53)
	     Caudate (11,50)
	     Putamen (12,51)
	     Pallidum (13,52)
	     Amygdala (18,54)
	     Thalamus Proper (10,49)
	     Lateral Ventricle (4,43)
	     Third and Fourth Ventricles (14,15)
	     Inf Lateral Vent (5,44)
	     Accumbens Area (26,58)
	 

OPTIONAL ARGUMENTS
	-o, --out [FILE]
		Save detailed overlap report to a JSON file.

	-m, --measures  [MEASURE...]
		List of measures to compute. By default, only dice scores are 
		computed. Options include: dice, jaccard, voldiff

	-l, --labels  [LABEL...]
		Space-separated list of label values to include. By default, 
		the overlap will be computed between all labels available in 
		both input volumes.

	-n, --names  [LABELNAME...]
		Custom label names corresponding to the values specified with 
		the --labels flag.

	-f, --labelfile  [FILE]
		Text file specifying the label values to include. This file 
		must be in the format of a freesurfer lookup-table, in which 
		each line contains a label value and, optionally, a 
		corresponding label name.

	-x, --no-names
		Do not report label names.

	-s, --seg
		Compute overlap between the the major segmentation structures 
		listed above.

	-q, --quiet
		Quiet mode - do not print results to stdout.

}}}

== JSON ==

NOTE: if the `--seg` flag is used, an additional statistic called `weighted-subcortical-mean`, which ignores wm and cortex, will be reported for each measure.

{{{
{
    "inputs": [
        "/path/to/aseg.mgz",
        "/path/to/mseg.mgz"
    ],
    "measures": {
        "dice": {
            "labels": {
                "10": 0.9075892566820576,
                "11": 0.8953675962203272,
                "12": 0.9146751935375295,
                ...
            },
            "mean": 0.6805390452588164,
            "std": 0.3237900375396044,
            "weighted-mean": 0.9340674985029207
        },
        "jaccard": {
            "labels": {
                "10": 0.8308131920466723,
                "11": 0.8105570623826414,
                "12": 0.8427663203597457,
                ...
            },
            "mean": 0.5892475078628221,
            "std": 0.3029904264784899,
            "weighted-mean": 0.8801749135061013
        }
    },
    "names": {
        "10": "Left-Thalamus",
        "11": "Left-Caudate",
        "12": "Left-Putamen",
        ...
    }
}
}}}