Final edits for next release

docs/pipeline.md

@@ -49,10 +49,37 @@ One pair of spin echo EPI scans with opposite phase encoding directions are used
 
 The purpose of the FMRISurface stage is primarily to take a volume time series and map it to the standard CIFTI grayordinates space.  This stage has not been altered from the original pipeline so refer to [Glasser, et al. 2013](https://doi.org/10.1016/j.neuroimage.2013.04.127) for more information.
 
-### Stage 6: DCANBOLDProcessing
+### Stage 6: DCANBOLDProcessing (DBP)
 
 [DCAN BOLD Processing](https://github.com/DCAN-Labs/dcan_bold_processing) is a signal processing software developed primarily by Dr. Oscar Miranda-Dominguez in the DCAN Labs with the primary function of nuisance regression from the dense time series and providing motion censoring information in accordance with [Power, et al. 2014](https://www.ncbi.nlm.nih.gov/pubmed/23994314).  The motion numbers produced in the FMRIVolume stage are also filtered to remove artifactual motion caused by respiration.  For more information on the respiration filtering see [Correction of respiratory artifacts in MRI head motion estimates. Fair, et al. NeuroImage. 2019.](https://doi.org/10.1016/j.neuroimage.2019.116400).
 
+This stage involves four broad steps:
+
+1. Standard pre-processing
+1. Application of a respiratory motion filter
+1. Motion censoring followed by standard re-processing
+1. Construction of parcellated timeseries
+
+#### 1. DBP Standard pre-processing
+
+Standard pre-processing comprises three steps.  First all fMRI data are de-meaned and de-trended with respect to time.  Next a general linear model is used to denoise the processed fMRI data.  Denoising regressors comprise signal and movement variables.  Signal variables comprise mean time series and first derivative for white matter, CSF, and the global signal, which are derived from Individualized segmentations generated during PostFreesurfer.  Movement variables comprise translational (X,Y,Z) and rotational (roll, pitch, and yaw) measures estimated by re-alignment during FMRIVolume and their Volterra expansion.  The inclusion of GSR is critical for most resting-state functional MRI comparisons, as demonstrated empirically by multiple independent labs (Ciric et al., 2017; Power et al., 2017, 2019b; Satterthwaite et al., 2013).  After denoising the fMRI data, the time series are band-pass filtered between 0.008 and 0.09 Hz using a 2nd order Butterworth filter.  Such a band-pass filter is softer than other filters, and avoids potential aliasing of the time series signal.
+
+##### On Global Signal Regression
+
+Global signal regression (GSR) has been consistently shown to reduce the effects of motion on BOLD signals and eliminate known batch effects that directly impact group  comparisons (Ciric et al., 2017; Power et al., 2015, 2019b). Motion censoring (see below) combined with GSR has been shown to be the best existing method for eliminating artifacts produced by motion.
+
+#### DBP 2. Respiratory Motion Filter
+
+In working with ABCD data, we have found that a respiratory artifact is produced within multi-band data (Fair et al., 2020).  While this artifact occurs outside the brain, it can affect estimates of frame alignment, leading to inappropriate motion censoring.  By filtering the frequencies of the respiratory signal from the motion realignment data, our respiratory motion filter produces better estimates of FD.
+
+#### DBP 3. Motion censoring
+
+Our motion censoring procedure is used for performing the standard pre-processing and for the final construction of parcellated timeseries.  For standard pre-processing, data are labeled as "bad" frames if they exceed an FD threshold of 0.3 mm.  Such "bad" frames are removed when demeaning and detrending, and betas for the denoising are calculated using only the "good" frames. For band-pass filtering, interpolation is used initially to replace the "bad" frames and the residuals are extracted from the denoising GLM.  In such a way, standard pre-processing of the timeseries only uses the "good" data but avoids potential aliasing due to missing timepoints.  When extracting time series for data analysis only data above an FD threshold of 0.2 mm are extracted.  After motion censoring, timepoints are further censored using an outlier detection approach.
+
+#### DBP 4. Generation of parcellated timeseries for specific atlases
+
+Using the processed resting-state fMRI data, this stage constructs parcellated time series for pre-defined atlases making it easy to construct correlation matrices or perform time series analysis on putative brain areas defined by independent datasets.  The atlases comprise recent parcellations of brain regions that comprise different networks.  In particular, parcellated timeseries are extracted for Evan Gordon’s 333 ROI atlas template (Gordon et al., 2014), Jonathan Power’s 264 ROI atlas template (Power et al., 2011), Thomas Yeo’s 118 ROI atlas template (Yeo et al., 2011), and the HCP’s 360 ROI atlas template (Glasser et al., 2016).  Since we anticipate newer parcellated atlases as data acquisition, analytic techniques, and knowledge all improve, it is trivial to add new templates for this final stage.
+
 ### Stage 7: ExecutiveSummary
 
 The ExecutiveSummary stage produces an HTML visual quality control page that displays a [BrainSprite](https://github.com/simexp/brainsprite.js) viewer of the T1w and T2w segmentation, an overlay of the atlas registration on each single band reference created by FSL's slicer, and a visualization of the movement and grayordinate time series for each fMRI run pre- and post-regression.

docs/recommendations.md

@@ -10,6 +10,10 @@ This document highlights common recommendations for usage of the collection 3165
 
 ## 2. The BIDS Participants Files and Matched Groups
 
+![Matched groups](img/matched_groups.png)
+
+A full-resolution version of this table can be found [here](https://github.com/ABCD-STUDY/nda-abcd-collection-3165/tree/master/docs/img/matched_groups.png).
+
 In a BIDS standard folder layout there should always be a `participants.tsv` (spreasheet) and `participants.json` (data dictionary) file.  This was not available in our first release, but is available now.  The participants files have the following fields inside.
 
 1. `participant_id`: NDA unique pGUID. starting with `sub-`
@@ -32,14 +36,22 @@ In a BIDS standard folder layout there should always be a `participants.tsv` (sp
 
 They are available for download on [the main NDA Collection 3165 page](https://nda.nih.gov/edit_collection.html?id=3165).
 
-The `matched_group` field is the product of a lot of group matching work to create two large separate groups and one small template group which are comparable across the variables.  Participants were matched across 10 variables: site, age, sex, race_ethnicity, participant_education, parental_education, handedness, income, and anesthesia_exposure.  Family members (e.g. sibling pairs, twins, and triplets) were kept together in the same set and the two larger sets were matched to include equal numbers of single participants and family members.
+The `matched_group` field is the product of comparisons across site, age, sex, ethnicity, grade, highest level of parental education, handedness, combined family income, exposure to anesthesia, and family-relatedness which show no significant differences between the ABCD-1 and ABCD-2 groups.  Comparison of the counts and means for each of these factors shows that ABCD-1 and ABCD-2 are negligibly different samples.  Gender shows the largest absolute difference of 2.5 percent.  No other demographic variables differ by more than 1 percent.  See below table:
 
 ## 3. Downloading and Unpacking Data
 
 There are two ways to download ABCD Study data and get BIDS inputs or derivatives:
 
-1. (*PREFERRED*) Downloading from NDA Collection 3165 will provide you an "associated files" spreadsheet with AWS S3 links and other key information.  DCAN Labs has designed [a GitHub repository for selectively downloading only parts of the BIDS input and derivative data, the "nda-abcd-s3-downloader"](https://github.com/ABCD-STUDY/nda-abcd-s3-downloader).
-1. [ABCD Fast Track Data on the NDA](https://nda.nih.gov/abcd/query/abcd-fast-track-data.html) can alternatively be downloaded and unpacked into BIDS with the [ABCD-STUDY abcd-dicom2bids GitHub repository](https://github.com/ABCD-STUDY/abcd-dicom2bids).
+1. (***PREFERRED***) Downloading from NDA Collection 3165 will provide you an "associated files" spreadsheet with AWS S3 links and other key information.  DCAN Labs has designed [a GitHub repository for selectively downloading only parts of the BIDS input and derivative data, the "nda-abcd-s3-downloader"](https://github.com/ABCD-STUDY/nda-abcd-s3-downloader).
+1. [ABCD Fast Track Data on the NDA](https://nda.nih.gov/abcd/query/abcd-fast-track-data.html) can alternatively be downloaded and unpacked into BIDS with the [ABCD-STUDY abcd-dicom2bids GitHub repository](https://github.com/ABCD-STUDY/abcd-dicom2bids).  This is if you need DICOM files specifically.
+
+### [`nda-abcd-s3-downloader`](https://github.com/ABCD-STUDY/nda-abcd-s3-downloader)
+
+This downloader can parallelize downloads and you can specify only your data subsets of interest.
+
+### [`abcd-dicom2bids`](https://github.com/ABCD-STUDY/abcd-dicom2bids)
+
+This tool pulls DICOMs and E-Prime files from the NDA's "fast-track" data.  It also unpacks, converts, and BIDS-standardizes the fast-track data so it becomes BIDS-compliant and matches that which is uploaded to collection 3165.
 
 ## 4. MATLAB Motion Mask Files
 
@@ -98,6 +110,6 @@ Much like custom clean, you define a JSON file which says how to map a file from
 
 Your final BIDS folder structure will look like this tree if you download everything.  Full descriptions of these BIDS input and BIDS derivative data are located in these release notes' documents 2 and 4, [**Inputs**](https://collection3165.readthedocs.io/en/stable/inputs/) and [**Derivatives**](https://collection3165.readthedocs.io/en/stable/derivatives/) respectively.
 
-![ABCD-BIDS Layout](img/ABCD-BIDS.png)
+![ABCD-BIDS Layout](img/ABCD-BIDS_cropped.png)
 
-A full-resolution version of this picture can be found [here](https://github.com/ABCD-STUDY/nda-abcd-collection-3165/tree/master/docs/img/ABCD-BIDS.png).
+A full-resolution version of this picture, complete with descriptions, can be found [here](https://github.com/ABCD-STUDY/nda-abcd-collection-3165/tree/master/docs/img/ABCD-BIDS.png).