Merge pull request #50 from DCAN-Labs/main

Update task descriptions

Author: anders-perrone

docs/index.md

@@ -10,9 +10,9 @@ In addition to the data, the ABCC read-the-docs provides helpful links to how to
 
 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`
+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 (version 0.0.3) 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` 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).
 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`
@@ -34,9 +34,7 @@ Latest updates are detailed below.
 - 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/) 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.
+  - 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.
 
 - 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

docs/inputs.md

@@ -76,10 +76,14 @@ The bval and bvec files associated with the DWI data for each scanner and softwa
 
 Field maps for the DWI data are included in each subject's `fmap` directory and can be distinguished from the functional fieldmaps by the `_acq-dwi` tag in their filenames.
 
-## 10. BIDS Modality-Agnostic Files
+## 10. Event Related Information
+
+The text files containing fMRI task event related information (ERI) have duplicated information. Specifically, per task within each subject's session, each run's ERI text file contains both run 1 and run 2. When extracting task event information for task-fMRI analysis, please make sure to take into account the duplicated structure for each ERI file. Our abcd-bids-tfmri-pipeline already takes this duplication into account for both derived contrasts and the pipeline code itself.
+
+## 11. BIDS Modality-Agnostic Files
 
 To maintain a valid BIDS data structure `dataset_description.json`, `README`, and `CHANGES` files are included.  They respectively: minimally describe the dataset, provide a small blurb about the datsaet, and log the changes from version to version.
 
-## 11. BIDS Validator Compliance
+## 12. BIDS Validator Compliance
 
 This dataset was validated using [the official BIDS validator](https://github.com/bids-standard/bids-validator).

docs/pipelines.md

@@ -94,66 +94,66 @@ The ExecutiveSummary stage produces an HTML visual quality control page that dis
 
 ## abcd-bids-fmri
 
-[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. 
+[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). 
+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).
 
 For FILM to run, users must supply their own subject-, task-, and run-specific event timing files that are in the FSL standard three column format (i.e. onset, duration, weight/magnitude). Additionally, users need to supply a task-specific fsf template file per task that they will be processing using the abcd-bids-tfmri pipeline. As the abcd-bids-tfmri pipeline modifies this template to make it subject- and run-specific, certain values need to be replaced with specific variables that the abcd-bids-tfmri pipeline will be able to recognize. An example fsf file template for ABCD’s MID task is made available for users to review on ABCC (https://osf.io/psv5m/).
 
-Users can specify which task data they would like to process by providing a list of task names within the abcd-bids-tfmri pipeline’s command line interface. If the user specifies multiple runs of the task, the pipeline will complete higher-level analyses (i.e. fixed effects modeling) to combine a given subject's run-level data. Therefore if a study has three different fMRI tasks that consist of two runs, all six level 1 analyses and all three level 2 analyses can be completed for a subject with a single run of the abcd-bids-tfmri pipeline. 
+Users can specify which task data they would like to process by providing a list of task names within the abcd-bids-tfmri pipeline’s command line interface. If the user specifies multiple runs of the task, the pipeline will complete higher-level analyses (i.e. fixed effects modeling) to combine a given subject's run-level data. Therefore if a study has three different fMRI tasks that consist of two runs, all six level 1 analyses and all three level 2 analyses can be completed for a subject with a single run of the abcd-bids-tfmri pipeline.
 
 The outputs of the abcd-bids-tfmri pipeline include the fully-processed dtseries data that are subsequently ready for the user to perform their desired third-level or group-wise analyses.
 
 ## fMRIPrep
 
-
 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:
 
-```
+```bash
 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 \
-	-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
+ /data/ABCD_MBDU/abcd_bids/bids \
+ $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
 ```
 
 Any papers using outputs from this pipeline should acknowledge this contribution of computational resources with the following line:
 
-“This work used the computational resources of the NIH HPC (high-performance computing) Biowulf cluster (http://hpc.nih.gov).”
+“This work used the computational resources of the NIH HPC (high-performance computing) Biowulf cluster (<http://hpc.nih.gov>).”
 
 ## QSIPrep
 
 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:
 
-```
+```bash
 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
+ 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
-```
+
+```json
 {
  "flm": "linear",
  "slm": "linear",