draft fslanat

.Rprofile

@@ -1 +1,2 @@
+options(renv.ppm.enabled = TRUE)
 source("renv/activate.R")

_freeze/fslanat/execute-results/html.json

@@ -0,0 +1,15 @@
+{
+  "hash": "ab9f94100e1920c7f28e9ffc4927c805",
+  "result": {
+    "engine": "knitr",
+    "markdown": "\n\n\n# FSL Anat {#sec-fslanat}\n\n![Subcortical Structures (source: https://fsl.fmrib.ox.ac.uk/fsl/docs/structural/first.html)](https://fsl.fmrib.ox.ac.uk/fsl/docs/structural/first.png)\n\nThe structural T1w scan in the A2CPS neuroimaging protocol is the source of several pre-specified biomarkers. Two of these biomarkers--the volumes of the hippocampi and amygdalae--are derived from a tool in the Functional Magnetic Resonance Imaging of the Brain (FMRIB) Software Library (FSL): [FMRIB's Integrated Registration and Segmentation Tool (FIRST)](https://fsl.fmrib.ox.ac.uk/fsl/docs/structural/first.html). The A2CPS pipeline calls FIRST as a part of FSL standard pipeline for processing anatomical images ([fsl_anat](https://fsl.fmrib.ox.ac.uk/fsl/docs/structural/fsl_anat.html)), which generates several outputs in addition to the biomarkers. This kit provides and overview of the outputs available from that pipeline.\n\n## Starting Project\n\n### Locate data\n\nIn the release, data are stored underneath the `mris/derivatives` folder:\n\n\n::: {.cell}\n\n```{.bash .cell-code}\n/corral-secure/projects/A2CPS/products/consortium-data/pre-surgery/mris/derivatives/fslanat\n```\n:::\n\n\nThis folder contains all of the outputs for every participant, with subject folders of the form `sub-[recordid]_ses-[protocolid]_T1w.anat`. Detailed descriptions of the outputs are available in the [`fsl_anat` documentation](https://fsl.fmrib.ox.ac.uk/fsl/docs/structural/fsl_anat.html#outputs).\n\nMany users will not need the raw `fsl_anat` outputs and can instead rely a table in which the subcortical measures have been aggregated: `fslanat.tsv`. A data dictionary for this table is available in the `fslanat.json` file, and also [ online](https://github.com/a2cps/snapshot/blob/v2.1.0/src/snapshot/data/fslanat.json).\n\n### Extract data\n\nIn this kit, we will compare volumetric measurements that are produced by both FIRST and FreeSurfer (@sec-freesurfer). In some circumstances, the volumes are largely interchangeable, but for some structures these tools are known to produce fairly different estimates of volume [@sadil_comparing_2024]. Let's replicate part of that analysis.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nlibrary(readr)\nlibrary(dplyr)\nlibrary(tidyr)\nlibrary(ggplot2)\nlibrary(stringr)\nlibrary(purrr)\nlibrary(irr)\nlibrary(agree)\n```\n:::\n\n\nFirst, load in the cortical volumes provided by FSL.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nfslanat <- read_tsv(\"data/fslanat/fslanat.tsv\", show_col_types = FALSE)\nhead(fslanat)\n```\n\n::: {.cell-output-display}\n<div class=\"kable-table\">\n\n| Brain-Stem /4th Ventricle| Left-Accumbens-area| Left-Amygdala| Left-Caudate| Left-Hippocampus| Left-Pallidum| Left-Putamen| Left-Thalamus-Proper| Right-Accumbens-area| Right-Amygdala| Right-Caudate| Right-Hippocampus| Right-Pallidum| Right-Putamen| Right-Thalamus-Proper| t1_to_mni_scaling| t1_space_orig_volume| t1_space_mni_volume|   sub|ses |\n|-------------------------:|-------------------:|-------------:|------------:|----------------:|-------------:|------------:|--------------------:|--------------------:|--------------:|-------------:|-----------------:|--------------:|-------------:|---------------------:|-----------------:|--------------------:|-------------------:|-----:|:---|\n|                     24714|                 582|          1696|         3631|             3213|          2040|         4107|                 8117|                  426|           1132|          3634|              3206|           2016|          4174|                  7751|          0.514789|              1051418|            541258.4| 20034|V1  |\n|                     20177|                 497|          1472|         3309|             3951|          1681|         4385|                 7400|                  365|           1134|          3305|              3873|           1746|          4067|                  7390|          0.515193|              1030126|            530713.7| 10767|V1  |\n|                     22711|                 609|          1645|         2822|             4529|          1705|         4857|                 7520|                  308|           1300|          2876|              4219|           1598|          4128|                  7253|          0.710936|              1015779|            722153.9| 20275|V1  |\n|                     21246|                 394|          1164|         2863|             2414|          1620|         4274|                 7011|                  409|           1320|          2833|              3356|           1561|          3795|                  6830|          0.968790|               944113|            914647.2| 10292|V1  |\n|                     24811|                 625|          1366|         3152|             3429|          1967|         4824|                 8532|                  517|           1545|          3083|              3569|           1833|          4551|                  7725|          0.544569|              1142600|            622224.5| 10826|V1  |\n|                     24092|                 676|          1616|         2897|             4227|          1878|         4573|                 9116|                  553|           1416|          3080|              4447|           1903|          4665|                  9040|          1.228005|              1224947|           1504241.0| 20104|V1  |\n\n</div>\n:::\n:::\n\n\nIn addition to subcortical volumetric information, that table contains a few fields related to the overall size of the brain (`t1_to_mni_scaling`, `t1_space_orig_volume`, `t1_space_mni_volume`). Drop those fields. To make it easier to join with FreeSurfer values, we'll also unpivot the table into a wider format, and extract information about the hemisphere.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nsubcort_fsl <- fslanat |>\n  select(-starts_with(\"t1_\")) |>\n  pivot_longer(-c(sub, ses), values_to = \"volume\", names_to = \"structure\") |>\n  separate(structure, c(\"hemisphere\", \"structure\"), sep = \"-\")\n\nhead(subcort_fsl)\n```\n\n::: {.cell-output-display}\n<div class=\"kable-table\">\n\n|   sub|ses |hemisphere |structure           | volume|\n|-----:|:---|:----------|:-------------------|------:|\n| 20034|V1  |Brain      |Stem /4th Ventricle |  24714|\n| 20034|V1  |Left       |Accumbens           |    582|\n| 20034|V1  |Left       |Amygdala            |   1696|\n| 20034|V1  |Left       |Caudate             |   3631|\n| 20034|V1  |Left       |Hippocampus         |   3213|\n| 20034|V1  |Left       |Pallidum            |   2040|\n\n</div>\n:::\n:::\n\n\nNow, grab the equivalent information from FreeSurfer.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nsubcort_freesurfer <- read_tsv(\n  \"data/freesurfer/aseg.tsv\",\n  show_col_types = FALSE\n) |>\n  filter(str_detect(\n    StructName,\n    \"Thalamus|Putamen|Pallidum|Hippocampus|Amygdala|Accumbens\"\n  )) |>\n  separate(StructName, into = c(\"hemisphere\", \"structure\"), sep = \"-\") |>\n  select(volume = Volume_mm3, hemisphere, structure, sub, ses)\n```\n:::\n\n\nThe tables may now be combined. Note that, while combining them, we add an additional column to keep track of which method produced the volume.\n\n\n::: {.cell}\n\n```{.r .cell-code}\nsubcort <- bind_rows(\n  list(fsl = subcort_fsl, freesurfer = subcort_freesurfer),\n  .id = \"method\"\n) |>\n  pivot_wider(names_from = method, values_from = volume) |>\n  na.omit() # not every structure is available in both methods, and not every participant has been processed by both pipelines\n\n\n# check which structures we have available\nsubcort |> distinct(structure)\n```\n\n::: {.cell-output-display}\n<div class=\"kable-table\">\n\n|structure   |\n|:-----------|\n|Accumbens   |\n|Amygdala    |\n|Hippocampus |\n|Pallidum    |\n|Putamen     |\n|Thalamus    |\n\n</div>\n:::\n:::\n\n\nTo compare the structures, make a simple [Bland-Altman plot](https://en.wikipedia.org/wiki/Bland%E2%80%93Altman_plot). \n\n::: {#fig-ba}\n\n\n::: {.cell}\n\n```{.r .cell-code}\nsubcort |>\n  mutate(Average = (fsl + freesurfer) / 2, Difference = fsl - freesurfer) |>\n  ggplot(aes(x = Average, y = Difference)) +\n  facet_wrap(~ structure + hemisphere, scales = \"free\") +\n  geom_point(alpha = 0.1, shape = 20) +\n  geom_hline(yintercept = 0) +\n  geom_ba() +\n  ylab(\"Difference (FSL - FreeSurfer)\") +\n  xlab(\"Average ([FSL + FreeSurfer]/2)\")\n```\n\n::: {.cell-output-display}\n![](fslanat_files/figure-html/plotting-1.png){width=672}\n:::\n:::\n\n\nComparison of Subcortical Volumes as Estimated by FSL and FreeSurfer. Each dot corresponds to a single structure of a single participant. The blue lines span the 95% confidence interval around the difference of the two estimates of volume, and the red lines are confidence intervals around the limits of agreement. \n\n:::\n\nAs expected, there are overal differences in how the estimates provided by the two structures [@fig-ba]. We can quantify these differences using the intraclass correlation coefficient.\n\n::: {#tbl-icc}\n\n\n::: {.cell}\n\n```{.r .cell-code}\nsubcort |>\n  group_nest(hemisphere, structure) |>\n  mutate(\n    fit = map(\n      data,\n      ~ icc(\n        cbind(.x$fsl, .x$freesurfer),\n        model = \"twoway\",\n        type = \"consistency\",\n        unit = \"single\"\n      )\n    ),\n    estimate = map_dbl(fit, pluck, \"value\"),\n    lower = map_dbl(fit, pluck, \"lbound\"),\n    upper = map_dbl(fit, pluck, \"ubound\")\n  ) |>\n  select(-data, -fit) |>\n  arrange(structure, hemisphere)\n```\n\n::: {.cell-output-display}\n<div class=\"kable-table\">\n\n|hemisphere |structure   |  estimate|     lower|     upper|\n|:----------|:-----------|---------:|---------:|---------:|\n|Left       |Accumbens   | 0.5545339| 0.5099570| 0.5961404|\n|Right      |Accumbens   | 0.4525440| 0.4016893| 0.5006163|\n|Left       |Amygdala    | 0.1712640| 0.1102848| 0.2309586|\n|Right      |Amygdala    | 0.2097839| 0.1495811| 0.2684369|\n|Left       |Hippocampus | 0.5341598| 0.4882153| 0.5771516|\n|Right      |Hippocampus | 0.5844969| 0.5420350| 0.6239818|\n|Left       |Pallidum    | 0.4685240| 0.4185594| 0.5156609|\n|Right      |Pallidum    | 0.4980915| 0.4498653| 0.5434214|\n|Left       |Putamen     | 0.5330968| 0.4870825| 0.5761597|\n|Right      |Putamen     | 0.5511217| 0.5063117| 0.5929634|\n|Left       |Thalamus    | 0.3977454| 0.3440988| 0.4488036|\n|Right      |Thalamus    | 0.4593056| 0.4088233| 0.5069856|\n\n</div>\n:::\n:::\n\n\nConsistency of Subcortical Volumes. The lower and upper bounds are 95% Confidence intervals, and the estimate is for the intraclass correlation. By the conventions of @mcgraw_forming_1996, this is also known as the $ICC(C,1)$.\n\n:::\n\n## Considerations While Working on Projects\n\n### Variability Across Scanners\n\nMany MRI biomarkers exhibit variability across the scanners, which may confound some analyses. For an up-to-date assessment of the issue and overview of current thinking, please see [Confluence](https://a2cps.atlassian.net/wiki/spaces/DOC/pages/176619539/Imaging+Harmonization). \n\n\n### Data Quality\n\nAs with any MRI derivative, all pipeline derivatives have been included. This means that products were included regardless of their quality, and so some products may have been generated from images that are known to have poor quality---rated \"red\", or incomparable. For details on the ratings and how to exclude them, see @sec-rawdata-mri-qc-joining. Additionally, extensive QC has not yet been performed on the derivatives themselves, and so there may be cases where pipelines produced atypical outputs. For an overview of planned checks, see [Confluence](https://a2cps.atlassian.net/wiki/spaces/DOC/pages/262471688/Image+Processing+Checks). \n\n\n### Methods\n\nFor a subset of participants, the standard `fsl_anat` pipeline needed to be modified.\n\n#### Field-of-View Estimation in UC\n\nAn early step in this pipeline involves estimating the field-of-view and cropping the image to a standard size. The cropping is done with the FSL tool `robustfov`, which uses a heuristic to first identify the most superior slice that could include the skull, uses a pre-specified distance in mm to select an inferior slice that is expected to be below the cerebellum, and crops everything outside of those slices. The heuristic is based on the quantiles of intensity values, but this heuristic was observed to often fail for data collected with SENSE.\n\nTo accommodate scans that failed for this reason, a small amount of noise was added to the entire image, and then the field-of-view was estimated on this degraded image. The field-of-view was then applied to the original image, and that cropped image was provided to `fsl_anat` (with automated cropping disabled). This workaround was recommended by [Mark Jenkinson on the FSL Archives](https://www.jiscmail.ac.uk/cgi-bin/wa-jisc.exe?A2=ind2307&L=FSL&D=0&P=182032), and it was applied to [these subjects](https://github.com/a2cps/mri_imaging_pipeline/blob/96f36b3a5cd9f9fa3c74d9239f1b864cdd603dfc/fslanat_actor/reactor.py#L26-L92).\n\n#### High-Intensity Voxels\n\nA subset of cases exhibited poor alignment to the standard space, with the misalignment driven by high-intensity voxels from outside of the brain. The extreme intensity values may have been driven by relatively high proportions of fatty tissue. For cases where these failures were identified, a mask was generated from the top 1% of voxels, which was then visually inspected to confirm that it did not include any voxels in the brain. That mask was then provided to `fsl_anat` as a \"lesion\" mask (via a hidden option), resulting in those voxels being ignored during alignment. In instances where the mask included brain voxels, the `fsl_anat` results were not included. The list of participants this fix was applied to is [here](https://github.com/a2cps/mri_imaging_pipeline/blob/96f36b3a5cd9f9fa3c74d9239f1b864cdd603dfc/fslanat_actor/reactor.py#L94-L102).\n\n### Citations\n\nThe fsl_anat pipeline relies on several tools that are the products of research by the FMRIB team. If you use these derivatives in your analyses, please follow the instructions for citations here: https://fsl.fmrib.ox.ac.uk/fsl/docs/index.html.\n\nIn publications or presentations including data from A2CPS, please include the following statement as attribution:\n\n> Data were provided [in part] by the A2CPS Consortium funded by the National Institutes of Health (NIH) Common Fund, which is managed by the Office of the Director (OD)/ Office of Strategic Coordination (OSC). Consortium components and their associated funding sources include Clinical Coordinating Center (U24NS112873), Data Integration and Resource Center (U54DA049110), Omics Data Generation Centers (U54DA049116, U54DA049115, U54DA049113), Multi-site Clinical Center 1 (MCC1) (UM1NS112874), and Multi-site Clinical Center 2 (MCC2) (UM1NS118922).\n\n::: {.callout-note}\nThe following published papers should be cited when referring to A2CPS Protocol and Biomarkers: @sluka_predicting_2023 @berardi_multi_2022\n:::\n\n\n\nWhen using neuroimaging derivatives, please also cite @sadil_acute_2024.\n",
+    "supporting": [],
+    "filters": [
+      "rmarkdown/pagebreak.lua"
+    ],
+    "includes": {},
+    "engineDependencies": {},
+    "preserve": {},
+    "postProcess": true
+  }
+}

_quarto.yml

@@ -18,6 +18,7 @@ book:
     - genomic_imputation.qmd
     - raw-mri.qmd
     - freesurfer.qmd
+    - fslanat.qmd
     - brainager.qmd
     - cat12.qmd
     - fcn.qmd

freesurfer.qmd

@@ -188,6 +188,8 @@ The data are plotted as in @fig-pairs, but with a restricted axis. Note the appa
 
 The relationship between surface area and volume appears to vary by region. For example, the Superior Temporal Sulcus has a similar surface area to the Superior Frontal Gyrus, but that gyrus has a larger volume. 
 
+## Considerations While Working on Projects
+
 ### Pivoting the Data
 
 The data have been shared in a ["longer" format](https://r4ds.hadley.nz/data-tidy.html#sec-tidy-data), with rows corresponding to region-level observations. Some analyses benefit from having the data in a ["wider" format](https://r4ds.hadley.nz/data-tidy.html#widening-data), with rows corresponding to participant-level observations. For example, if we're predicting age from cortical thickness, we may want to drop the other morphological measures, and pivot the table such that columns correspond to regional thickness.