Merge pull request #9 from DCAN-Labs/develop

Develop

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.
 

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`
@@ -21,7 +21,7 @@ As a community share, the ABCC enables researchers to access **available derivat
 
 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
 
@@ -31,20 +31,16 @@ 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.
-
-    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 [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.
 
+- 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.

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).