mri_overlap

This page proposes a new program, called mri_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 -l or -f 
        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

The proposed JSON output would look something like this:

{
    "names": {
        "1": "structure 1",
        "2": "structure 2"
        ...
    },
    "inputs": [
        "/path/to/manual_label.mgz",
        "/other/path/to/aseg.mgz"
    ],
    "measures": {
        "dice": {
            "mean": 0.9142,
            "std": 0.0232,
            "labels": {
                "2": 0.9143,
                "3": 0.8739,
                "4": 0.9002,
                ...
            }
        },
        "jaccard": {
            "mean": 0.8902,
            "std": 0.0144,
            "labels": {
                "2": 0.8921,
                ...
            }
        },
        "voldiff": {
            "mean": 0.0221,
            "std": 0.0032,
            "labels": {
                "2": 0.0123,
                ...
            }
        }
    }
}