Merge pull request #46 from DCAN-Labs/develop

Update to Coming Soon Release
ABCD-STUDY · May 10, 2023 · 0015f85 · 0015f85
2 parents c3262d1 + de62627
commit 0015f85
Show file tree

Hide file tree

Showing 7 changed files with 186 additions and 114 deletions.
diff --git a/docs/derivatives.md b/docs/derivatives.md
@@ -10,6 +10,7 @@ This document reports and describes the derivative files containing processed da
 
 1. [fMRIPrep](https://fmriprep.org/)
 1. [QSIPrep](https://qsiprep.readthedocs.io/en/stable/)
+1. [abcd-bids-tfmri-pipeline](https://github.com/DCAN-Labs/abcd-bids-tfmri-pipeline)
 
 can be found by clicking on their respective links.
 
@@ -220,27 +221,37 @@ Motion-corrected individual functional task run in MNI space in a volume.
 - `sub-#/ses-#/func/sub-#_ses-#_task-(MID|nback|SST|rest)_run-#_space-MNI_bold.nii.gz`
 
 
-## 5. Executive Summary
+## 5. Task fMRI
+
+The task pipeline will produce its derivatives in the following BIDS-valid directory structure.
+
+- `sub-#/ses-#/func/sub-#_ses-#_task-(MID|nback|SST)_level-2_contrast_*_cope1.dtseries.nii`
+- `sub-#/ses-#/func/sub-#_ses-#_task-(MID|nback|SST)_level-2_contrast_*_tdof_t1.dtseries.nii`
+- `sub-#/ses-#/func/sub-#_ses-#_task-(MID|nback|SST)_level-2_contrast_*_logfile`
+- `sub-#/ses-#/func/sub-#_ses-#_task-(MID|nback|SST)_level-2_contrast_*_mask.dtseries.nii`
+- `sub-#/ses-#/func/sub-#_ses-#_task-(MID|nback|SST)_level-2_contrast_*_res4d.dtseries.nii`
+
+## 6. Executive Summary
 
 The DCAN Labs executive summary is software for getting a basic visual quality control report to review processed output data.
 
 ### Prerequisites: At least one `T1w` and one fMRI
 
 - DCAN Labs Executive Summary: `derivatives.executivesummary.all`
 
-## 6. Derivative Filenames
+## 7. Derivative Filenames
 
 Some BIDS derivative standards are still [BIDS Extension Proposals (BEPs)](https://bids-specification.readthedocs.io/en/stable/06-extensions.html#bids-extension-proposals) at the time of this writing, but we tried to conform to the available derivative standards at the time for common derivatives ([BEP003](https://docs.google.com/document/d/1Wwc4A6Mow4ZPPszDIWfCUCRNstn7d_zzaWPcfcHmgI4/view)), the structural preprocessing derivatives ([BEP011](https://docs.google.com/document/d/1YG2g4UkEio4t_STIBOqYOwneLEs1emHIXbGKynx7V0Y/view)), and the functional preprocessing derivatives ([BEP012](https://docs.google.com/document/d/1qBNQimDx6CuvHjbDvuFyBIrf2WRFUOJ-u50canWjjaw/view)).
 
-## 7. Motion MAT File
+## 8. Motion MAT File
 
 The MATLAB motion .MAT files are a product of the DCANBOLDProcessing stage of the pipeline.  They should be used to select a frame censoring mask (frames to keep in analysis versus frames to censor out based on excessive motion).  They contain a 1x51 MATLAB cell of MATLAB structs where each struct is the censoring info at a given framewise displacement (FD) threshold (0 to 0.5 millimeters in steps of 0.01 millimeters).
 
 These files use the motion censoring algorithm from the [Power, et al, 2014 paper](https://www.sciencedirect.com/science/article/pii/S1053811913009117).  In that paper, the authors describe a motion censoring method wherein you only exclude periods of data below FD thresholds which are less than five contiguous frames between sequential censored frames.
 
 [*Power, J. D., Mitra, A., Laumann, T. O., Snyder, A. Z., Schlaggar, B. L., & Petersen, S. E. (2014). Methods to detect, characterize, and remove motion artifact in resting state fMRI. NeuroImage, 84, 320–41. doi:10.1016/j.neuroimage.2013.08.048*](https://www.sciencedirect.com/science/article/pii/S1053811913009117)
 
-## 8. Caveats
+## 9. Caveats
 
 There were a few parts of the NDA fmriresults01 and imagingcollection01 data structures where we could not conform to the NDA's established standard.  We plan to correct these in future releases.
 

diff --git a/docs/index.md b/docs/index.md
@@ -6,11 +6,22 @@ The ABCC houses a community-shared and continually updated ABCD neuroimaging dat
 
 In addition to the data, the ABCC read-the-docs provides helpful links to how to use, process, and analyze ABCD data. The documentation guide below will take users to different sections for more information.
 
+## 2. Background
+
+As a community share, the ABCC enables researchers to access **available derivatives** and share their **own derivatives.**. The ABCD-BIDS datasets are continually updated as new ABCD releases become available. A list of currently available datasets are provided below.
+
+1. `BIDS inputs` The input DICOM data to this [BIDS version 1.2.0](https://www.nature.com/articles/sdata201644) data collection were retrieved from the [NIMH Data Archive (NDA) share of ABCD fast-track data](https://nda.nih.gov/edit_collection.html?id=2573) and were last accessed on May 1, 2019. BIDS input data were converted from DICOMs using [Dcm2Bids](https://github.com/cbedetti/Dcm2Bids). 
+2. `abcd-hcp-pipeline` BIDS derivatives data were derived from the [DCAN Labs ABCD-BIDS MRI processing pipeline](https://doi.org/10.5281/zenodo.2587210) which outputs [Human Connectome Project (HCP) Minimal Preprocessing Pipelines-style data](https://doi.org/10.1016/j.neuroimage.2013.04.127) in both volume and surface spaces. This collection is independent from ABCD Data Collection 2573. Users may access ABCD DICOM files via the ABCD fast-track imaging data release in Collection 2573.
+3. `abcd-task-hcp-pipeline`
+4. `freesurfer-5.3.0-HCP` segmentation statistics and surface morphometrics from the FreeSurfer stage within the [DCAN Labs ABCD-BIDS MRI processing pipeline](https://doi.org/10.5281/zenodo.2587210) are provided here.
+5. `QSIPrep`
+6. `fMRIPrep`
+
 # How to Contribute
 
-If you would like to contribute to this effort, please visit our [Git NDA Uploads Repository](https://github.com/ABCD-STUDY/nda-abcd-collection-3165). Additionally, you may contact us by emailing [email protected]. 
+If you would like to contribute to this effort, please visit our [Git NDA Uploads Repository](https://github.com/ABCD-STUDY/nda-abcd-collection-3165).
 
-Latest updates are detailed below. 
+Latest updates are detailed below.
 
 # Collection News
 
@@ -20,20 +31,18 @@ Latest updates are detailed below.
 
 - Additional year 1 BIDS input and abcd-hcp-pipeline derivatives
 
-- The timeseries data has been reprocessed with an updated version of the abcd-hcp-pipeline (v1.0.3) with improved bandpass filtering to the BOLD data. The new implementation zero pads the BOLD data prior to filtering to minimize distortions at the beginning and ending timepoints. It's important to note that this is not a bug, but rather an improvement. This release does not invalidate previous results, it reduces variance towards the beginning and end of the time-series data. In the previous release, those frames are labeled as "outliers" and discarded according to the provided mask. Using these updated timeseries users should be able to include more data in their analyses. (TODO: Provide specific derivatives filenames)
+- The timeseries data will be reprocessed with an updated version of the abcd-hcp-pipeline (v1.0.3) with improved bandpass filtering to the BOLD data. The new implementation zero pads the BOLD data prior to filtering to minimize distortions at the beginning and ending timepoints. It's important to note that this is not a bug, but rather an improvement. This release does not invalidate previous results, it reduces variance towards the beginning and end of the time-series data. In the previous release, those frames are labeled as "outliers" and discarded according to the provided mask. Using these updated timeseries users should be able to include more data in their analyses.
 
-- New version of [QSIPrep](https://qsiprep.readthedocs.io/en/stable/)- year 1 derivatives.
-    - There was in issue for some subjects in distortion correction that resulted in very inaccurate distortion correction results. This was due to TOPUP being given a denoised b=0 image from the DWI series and a raw b=0 image in the opposite phase encoding direction (taken from the image in the fmap/ directory). We updated QSIPrep to use the unprocessed b=0 images in both phase encoding directions, which resulted in TOPUP performing as expected.
-    
+- New version of [QSIPrep](https://qsiprep.readthedocs.io/en/stable/) v0.14.2 year 1 derivatives.
+  - There was in issue for some subjects in distortion correction that resulted in very inaccurate distortion correction results. This was due to TOPUP being given a denoised b=0 image from the DWI series and a raw b=0 image in the opposite phase encoding direction (taken from the image in the fmap/ directory). We updated QSIPrep to use the unprocessed b=0 images in both phase encoding directions, which resulted in TOPUP performing as expected.
+
     The bug affected a subset of subjects, but it is worth suggesting that anyone using the initial data re-calculate their analysis using the updated version.
 
-(TODO: Edit this section @Feczko)
-- New version of [fMRIPrep](https://fmriprep.org/) 23.x.x year 1 derivatives. Special thanks to Thomas Madison, etc.
-    - Improved distortion correction
-    - Improved bold projection to surface
-    - New CIFTI outputs
-    - T2w in T1w volume space
-
-- Change to participants.tsv format (TODO: Anders link to recomendations section)
-
+- New version of [fMRIPrep](https://fmriprep.org/) 23.0.0rc0 year 1 derivatives. For specifics on what has changed since fMRIprep v20.2.0 and fMRIprep 23.0.0rc0, see the change log for the software [here](https://fmriprep.org/en/stable/changes.html).
+  - Improved distortion correction
+  - Improved bold projection to surface
+  - New CIFTI outputs
+  - T2w in T1w volume space
 
+- Change to participants.tsv format
+  - The combined race & ethnicity variable from v1.0.1 has been replaced with more descriptive individual race columns.
diff --git a/docs/pipelines.md b/docs/pipelines.md
@@ -1,8 +1,4 @@
-# Pipeline (TODO: Split out all pipelines into seperate md files)
-
-Note: Clicking any link within the readthedocs site will not open a new web browser tab.  If you want to keep your docs open, either middle-click or right-click and choose open in new tab for the links you would like to follow.
-
----
+# Pipeline
 
 ## 1. About this Document
 
@@ -98,7 +94,7 @@ The ExecutiveSummary stage produces an HTML visual quality control page that dis
 
 ## abcd-bids-fmri
 
-abcd-bids-tfmri, a modified version of the TaskfMRIAnalysis stage of the HCP-pipeline (Glasser et al., 2013) developed at University of Vermont by Anthony Juliano, was used to process task-fmri data from the minimally processed ABCD-BIDS (Feczko et al., 2020b) processing pipeline (v.1.0) data, as well as derived ABCC data (Feczko, 2020; ABCD-3165). Given the abcd-bids-tfmri pipeline's focus on reproducibility in neuroimaging, it allows for minimal user input while providing vast flexibility with regard to the task-based fMRI data that can be processed (including the type of task and the number of subject-level runs). Transparency is easily achieved with the abcd-bids-tfmri pipeline as users can efficiently share their command-line that was used in processing their data when presenting their findings. 
+[abcd-bids-tfmri](https://github.com/DCAN-Labs/abcd-bids-tfmri-pipeline), a modified version of the TaskfMRIAnalysis stage of the HCP-pipeline (Glasser et al., 2013) developed at University of Vermont by Anthony Juliano, was used to process task-fmri data from the minimally processed ABCD-BIDS (Feczko et al., 2020b) processing pipeline (v.1.0) data, as well as derived ABCC data (Feczko, 2020; ABCD-3165). Given the abcd-bids-tfmri pipeline's focus on reproducibility in neuroimaging, it allows for minimal user input while providing vast flexibility with regard to the task-based fMRI data that can be processed (including the type of task and the number of subject-level runs). Transparency is easily achieved with the abcd-bids-tfmri pipeline as users can efficiently share their command-line that was used in processing their data when presenting their findings. 
 
 Given its focus on CIFTI (like a dtseries) data, the abcd-bids-tfmri pipeline heavily relies on HCP workbench commands (https://www.humanconnectome.org/software/workbench-command). This includes completing the user-specified spatial smoothing (wb_command -cifti-smoothing), converting the smoothed data to and from a format that FSL (Jenkinson et al. 2012) can interpret (wb_command -cifti-convert), separating the dtseries data into its comprised components (wb_command -cifti-separate-all), and reading in pertinent information from the dtseries data (wb_command -file-information), among others. Based on the user-specified parameters for censoring volumes (i.e. initial and/or high-motion frames), the pipeline will read in the filtered motion file (Fair et al., 2020) produced by the ABCD-BIDS processing pipeline and create a matrix for nuisance regression. Finally, high-pass filtering, with a cutoff of 0.005 Hz (200 seconds), is completed before running FSL's FILM (Woolrich et al. 2001). 
 
@@ -110,25 +106,24 @@ The outputs of the abcd-bids-tfmri pipeline include the fully-processed dtseries
 
 ## fMRIPrep
 
-(TODO: Add more detailed information on pipeline and stages @Thomas Madison)
 
 fMRIPrep is a tool for preprocessing BIDS compatible fMRI datasets. If groups would like to analyze the ABCD fMRI results, these outputs will be helpful for analysis of resting state and task based fMRI data. This is the command that was used:
 
 ```
 singularity run --cleanenv /data/ABCD_MBDU/singularity_images/fmriprep_20.2.0.simg \
 	/data/ABCD_MBDU/abcd_bids/bids \
-$TMPDIR/out \
-participant \
---participant_label $PARTICIPANTID \
+	$TMPDIR/out \
+	participant \
+	--participant_label $PARTICIPANTID \
 	-w $TMPDIR/wrk \
 	--nthreads $SLURM_CPUS_PER_TASK \
 	--mem_mb $SLURM_MEM_PER_NODE \
 	--fs-license-file /data/ABCD_MBDU/singularity_images/license.txt \
 	--output-spaces MNI152NLin2009cAsym:res-2 fsnative fsaverage5 fsLR \
 	--cifti-output \
 	--skip-bids-validation \
---notrack \
---omp-nthreads 1
+	--notrack \
+	--omp-nthreads 1
 ```
 
 Any papers using outputs from this pipeline should acknowledge this contribution of computational resources with the following line:
@@ -137,4 +132,46 @@ Any papers using outputs from this pipeline should acknowledge this contribution
 
 ## QSIPrep
 
-(TODO: Get QSIPrep pipeline description from Matt)
+QSIPrep configures pipelines for processing diffusion-weighted MRI (dMRI or DWI) data. For more information see the [QSIPrep documentation](https://qsiprep.readthedocs.io/en/latest/). This is the command used to run ABCC subjects through QSIPrep preprocessing:
+
+```
+singularity run --cleanenv -B ${PWD} \
+    pennlinc-containers/.datalad/environments/qsiprep-0-16-1/image \
+    inputs/data \
+    prep \
+    participant \
+    -w ${PWD}/.git/wkdir \
+    --n_cpus 8 \
+    --stop-on-first-crash \
+    --fs-license-file code/license.txt \
+    --skip-bids-validation \
+    --participant-label "$subid" \
+    --unringing-method mrdegibbs \
+    --output-resolution 1.7 \
+    --eddy-config code/eddy_params.json \
+    --notrack
+```
+
+Contents of code/eddy_params.json
+```
+{
+ "flm": "linear",
+ "slm": "linear",
+ "fep": false,
+ "interp": "spline",
+ "nvoxhp": 1000,
+ "fudge_factor": 10,
+ "dont_sep_offs_move": false,
+ "dont_peas": false,
+ "niter": 5,
+ "method": "jac",
+ "repol": true,
+ "num_threads": 1,
+ "is_shelled": true,
+ "use_cuda": false,
+ "cnr_maps": true,
+ "residuals": false,
+ "output_type": "NIFTI_GZ",
+ "args": ""
+}
+```