cat12.qmd

# Voxel-Based Morphometry {#sec-cat12}

This starter kit walks through the voxel-based morphometry (VBM) outputs generated by the [Computational Anatomy Toolbox (CAT12)](https://neuro-jena.github.io/cat/). 

Voxel-Based Morphometry is an automated technique that uses statistics to identify differences in brain anatomy (most commonly gray matter density or volume) between groups of subjects. It achieves this by registering all structural images to a common stereotaxic space and then comparing voxels across subjects. This makes it an incredibly powerful tool for investigating structural brain differences associated with chronic pain or evaluating structural changes resulting from interventions. For more foundational knowledge on VBM, see the classic [Ashburner and Friston (2000)](https://doi.org/10.1006/nimg.2000.0582) paper.

## Starting Project

### Locate data

{{< include _snippets/mri-location.qmd >}}

The morphometry measures are underneath `derivatives/cat12`.

### Extract data

Data for each participant is stored in a sub-directory

```bash
$ ls -d mris/derivatives/cat12/sub* | head
mris/derivatives/cat12/sub-10003
mris/derivatives/cat12/sub-10005
mris/derivatives/cat12/sub-10008
mris/derivatives/cat12/sub-10009
mris/derivatives/cat12/sub-10010
mris/derivatives/cat12/sub-10011
mris/derivatives/cat12/sub-10013
mris/derivatives/cat12/sub-10014
mris/derivatives/cat12/sub-10015
mris/derivatives/cat12/sub-10017
```

For example:

```bash
$ tree mris/derivatives/cat12/sub-10003
mris/derivatives/cat12/sub-10003
└── ses-V1
    ├── label
    │   ├── catROI_sub-10003_ses-V1_T1w.mat
    │   └── catROI_sub-10003_ses-V1_T1w.xml
    ├── mri
    │   ├── misub-10003_ses-V1_T1w.nii
    │   ├── msub-10003_ses-V1_T1w.nii
    │   ├── mwp1sub-10003_ses-V1_T1w.nii
    │   ├── mwp2sub-10003_ses-V1_T1w.nii
    │   ├── mwp3sub-10003_ses-V1_T1w.nii
    │   ├── p0sub-10003_ses-V1_T1w.nii
    │   ├── p1sub-10003_ses-V1_T1w.nii
    │   ├── p2sub-10003_ses-V1_T1w.nii
    │   ├── p3sub-10003_ses-V1_T1w.nii
    │   ├── wmisub-10003_ses-V1_T1w.nii
    │   ├── wmsub-10003_ses-V1_T1w.nii
    │   ├── wp0sub-10003_ses-V1_T1w.nii
    │   ├── wp1sub-10003_ses-V1_T1w.nii
    │   ├── wp2sub-10003_ses-V1_T1w.nii
    │   ├── wp3sub-10003_ses-V1_T1w.nii
    │   └── y_sub-10003_ses-V1_T1w.nii
    ├── report
    │   ├── catlog_sub-10003_ses-V1_T1w.txt
    │   ├── cat_sub-10003_ses-V1_T1w.mat
    │   └── cat_sub-10003_ses-V1_T1w.xml
    └── surf
        ├── lh.central.sub-10003_ses-V1_T1w.gii
        ├── lh.pbt.sub-10003_ses-V1_T1w
        ├── lh.pial.sub-10003_ses-V1_T1w.gii
        ├── lh.sphere.reg.sub-10003_ses-V1_T1w.gii
        ├── lh.sphere.sub-10003_ses-V1_T1w.gii
        ├── lh.thickness.sub-10003_ses-V1_T1w
        ├── lh.white.sub-10003_ses-V1_T1w.gii
        ├── rh.central.sub-10003_ses-V1_T1w.gii
        ├── rh.pbt.sub-10003_ses-V1_T1w
        ├── rh.pial.sub-10003_ses-V1_T1w.gii
        ├── rh.sphere.reg.sub-10003_ses-V1_T1w.gii
        ├── rh.sphere.sub-10003_ses-V1_T1w.gii
        ├── rh.thickness.sub-10003_ses-V1_T1w
        └── rh.white.sub-10003_ses-V1_T1w.gii

5 directories, 35 files
```

Additionally, there is a table of "cluster volumes", which contains information relevant to A2CPS primary and secondary biomarkers.

```bash
$ ls mris/derivatives/cat12/cluster*
mris/derivatives/cat12/cluster_volumes.json  mris/derivatives/cat12/cluster_volumes.tsv

$ head mris/derivatives/cat12/cluster_volumes.tsv 
sub ses mri atlas   cluster volume
10703   V1  wp1sub-10703_ses-V1_T1w tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg    0   1998.106000518892
10703   V1  wp1sub-10703_ses-V1_T1w tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg    1   2294.6824886463583
10703   V1  mwp1sub-10703_ses-V1_T1w    tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg    0   1219.69091796875
10703   V1  mwp1sub-10703_ses-V1_T1w    tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg    1   1443.6837158203125
10753   V1  mwp1sub-10753_ses-V1_T1w    tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg    0   1673.0926513671875
10753   V1  mwp1sub-10753_ses-V1_T1w    tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg    1   1950.593505859375
10753   V1  wp1sub-10753_ses-V1_T1w tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg    0   2353.910433325509
10753   V1  wp1sub-10753_ses-V1_T1w tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg    1   2952.608998143696
10040   V1  mwp1sub-10040_ses-V1_T1w    tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg    0   1499.8414306640625
```

The `json` file contains a data dictionary, with links to confluence pages providing detailed information about each of the atlases.

```json
{
    "sub": {
        "LongName": "Subject",
        "Description": "Study Participant, BIDS Subject ID",
        "TermURL": "https://bids-specification.readthedocs.io/en/v1.9.0/appendices/entities.html#sub"
    },
    "ses": {
        "LongName": "Session",
        "Description": "Visit, Protocol, BIDS Session ID",
        "Levels": {
            "V1": "baseline_visit",
            "V3": "3mo_postop"
        },
        "TermURL": "https://bids-specification.readthedocs.io/en/v1.9.0/appendices/entities.html#ses"
    },
    "mri": {
        "LongName": "MRI Filename",
        "Description": "Product of CAT12 in which volumes were calculated",
        "TermURL": "https://neuro-jena.github.io/cat12-help/#naming"
    },
    "atlas": {
        "LongName": "Atlas of Clusters",
        "Description": "Source file in which clusters are defined",
        "Levels": {
            "tpl-MNI152NLin2009cAsym_atlas-smallwood_dseg": "https://a2cps.atlassian.net/wiki/external/NjFmMGViNjA1OGI4NGIxNWJlMjk0ZmM5ODcyNDhhODc",
            "tpl-MNI152NLin2009cAsym_atlas-henn_desc-controlspatientgmtfce05_dseg": "https://doi.org/10.1097/j.pain.0000000000002681, Table 4"
        }
    },
    "cluster": {
        "LongName": "Cluster Number",
        "Description": "ID of cluster as reported by FSL. May not match ID in source paper."
    },
    "volume": {
        "LongName": "Cluster Volume",
        "Description": "Volume of cluster_id from atlas_id in mri_id calculated as number of voxels times voxel volume."
    }
}
```

## Considerations While Working on the Project

### Variability Across Scanners

{{< include _snippets/mri-scanner-variability.qmd >}}

### Data Quality

{{< include _snippets/mri-qc.qmd >}}

### Data Generation (CAT12 Configuration)

For details on CAT12's methods see [their documentation](https://neuro-jena.github.io/cat12-help/#major_process). CAT12 ([12.9](https://github.com/ChristianGaser/cat12/releases/tag/12.9), r2582) was run with nearly the default configurations, changing only parameters that cause a few additional outputs to be saved. For the full batch script, see [GitHub](https://github.com/a2cps/biomarker-extractor/blob/86809551c856ff468bafeb631858a7939b53bfe9/src/biomarkers/data/batch.m). 

### CAT12 Image Quality Ratings

Part of the Raw MRI data quality ratings are derived from an "Image Quality Rating" that is provided by CAT12. The ratings were pulled from the xml document in the `reports` subfolder. For example

```bash
$ grep -P "<IQR>|\(IQR\)" sub-10003/ses-V1/report/cat_sub-10003_ses-V1_T1w.xml
      <IQR>1.85445149536238</IQR>
      <item>Image Quality Rating (IQR): 86.46% (B)</item>
```

The version of the IQR reported as a percentage is equal to $105 - 10*IQR$.

Note that CAT12 typically generates a PDF with an overview of processing and image quality. There is an ongoing issue with CAT12 that prevented the PDFs from being generated for Release 2.0.0. For details, see [the associated issue on the CAT12 GitHub Repo](https://github.com/ChristianGaser/cat12/issues/27). 

### Citations

The methods driving CAT12 are based on extensive research. If you use these results, please be sure to cite the relevant papers outlined here: https://neuro-jena.github.io/cat/index.html#About.

{{< include _snippets/a2cps_citations.qmd >}}

When using neuroimaging derivatives, please also cite @sadil_acute_2024.