From 32a438272966f3a765f4cd07adeca9f5316cc952 Mon Sep 17 00:00:00 2001 From: Audrey Houghton Date: Wed, 1 Mar 2023 11:28:19 -0600 Subject: [PATCH 1/9] Updated description of abcd-bids-tmri-pipeline sections --- docs/derivatives.md | 1 + docs/pipelines.md | 2 +- docs/release_notes.md | 9 +-------- 3 files changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/derivatives.md b/docs/derivatives.md index f758855..40e7328 100644 --- 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. diff --git a/docs/pipelines.md b/docs/pipelines.md index d7be342..76f4d0e 100644 --- a/docs/pipelines.md +++ b/docs/pipelines.md @@ -98,7 +98,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). diff --git a/docs/release_notes.md b/docs/release_notes.md index 8f2dadb..e2b6b45 100644 --- a/docs/release_notes.md +++ b/docs/release_notes.md @@ -32,8 +32,6 @@ User feedback will guide our course for future releases. Provide feedback on wh ## 4. Release History -[TODO: Info about zero padding update in DBP, QSIPrep, and future releases (zero byte data)] - ### Release 2.0.0 (6/22/2022) New updates (include dates) to the ABCD BIDS Community Collection cover both revisions to existing datasets and new derivatives. Revisions include: @@ -78,7 +76,6 @@ The DWI acquisition parameters from subjects scanned on Philips and GE with MR S TODO: link to description and brief overview of subject counts -TODO Submission IDs #### Template Matching @@ -88,11 +85,7 @@ TODO: link to description and brief overview of subject counts #### Task outputs -TODO: link to description and brief overview of subject counts - -TODO Submission IDs - -(TODO: Add section about the task derivatives. @Anders give Fez a list of all task derivatives) +(abcd-bids-tfmripipeline)[https://github.com/DCAN-Labs/abcd-bids-tfmri-pipeline] was ran on ABCD-BIDS derivativves of the baseline subjects. TODO: Feczko add a brief description of level 1 and level 2. ### Release 1.1.1 (10/7/2020) From 026a29e65c8aeb3f09c8875659ee7d39e47ebec8 Mon Sep 17 00:00:00 2001 From: Audrey Houghton Date: Wed, 1 Mar 2023 11:59:06 -0600 Subject: [PATCH 2/9] updated todos --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 393f340..b77e6ce 100644 --- a/docs/index.md +++ b/docs/index.md @@ -31,7 +31,7 @@ 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. From 4280282313670ebb49f0d8a950a0a7feaa048f49 Mon Sep 17 00:00:00 2001 From: Anders Perrone Date: Wed, 29 Mar 2023 11:23:21 -0500 Subject: [PATCH 3/9] Add QSIPrep cmd --- docs/pipelines.md | 55 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 48 insertions(+), 7 deletions(-) diff --git a/docs/pipelines.md b/docs/pipelines.md index 72086aa..56c5907 100644 --- a/docs/pipelines.md +++ b/docs/pipelines.md @@ -106,16 +106,15 @@ 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 \ @@ -123,8 +122,8 @@ participant \ --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: @@ -133,4 +132,46 @@ Any papers using outputs from this pipeline should acknowledge this contribution ## QSIPrep -(TODO: Anders will add from MSI run dir) +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": "" +} +``` From 4ecdc9308ce70e42aba180c547bb26cbc231a624 Mon Sep 17 00:00:00 2001 From: Anders Perrone Date: Wed, 29 Mar 2023 13:21:58 -0500 Subject: [PATCH 4/9] Add InfoMap description --- docs/derivatives.md | 37 +++++++++++++++++++++++++++++++++---- docs/index.md | 7 +++++-- docs/postpipeline.md | 8 ++++++-- docs/release_notes.md | 2 +- 4 files changed, 45 insertions(+), 9 deletions(-) diff --git a/docs/derivatives.md b/docs/derivatives.md index 40e7328..e6ebc96 100644 --- a/docs/derivatives.md +++ b/docs/derivatives.md @@ -221,7 +221,36 @@ 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. +(TODO: Perrone confirm derivative structure in ABCC) + +``` +output_dir +├── level-1 +│ ├── events +│ │ └── sub-*_ses-*_task-*_run-*.tsv +│ ├── level1_run-* +│ │ ├── sub-*_ses-*_task-*_run-*_cope*.dtseries.nii +│ │ ├── sub-*_ses-*_task-*_run-*_dof +│ │ ├── sub-*_ses-*_task-*_run-*_logfile +│ │ └── sub-*_ses-*_task-*_run-*_res4d.dtseries.nii +│ └── temp +└── level-2 + ├── cope_files + │ └── sub-*_ses-*_task-*_contrast_*_cope*.dtseries.nii + ├── dof_files + │ └── sub-*_ses-*_task-*_contrast_*_tdof_t1.dtseries.nii + ├── log_files + │ └── sub-*_ses-*_task-*_contrast_*_logfile + ├── mask_files + │ └── sub-*_ses-*_task-*_contrast_*_mask.dtseries.nii + └── res4d_files + └── sub-*_ses-*_task-*_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. @@ -229,11 +258,11 @@ The DCAN Labs executive summary is software for getting a basic visual quality c - 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). @@ -241,7 +270,7 @@ These files use the motion censoring algorithm from the [Power, et al, 2014 pape [*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 index b77e6ce..94539b8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,8 +38,11 @@ Latest updates are detailed below. 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. +(TODO: Anders audit previous fmriprep uploads) + +(TODO: Audrey Check in with Luci/Michael about new features in updated version of fMRIPrep) + +- New version of [fMRIPrep](https://fmriprep.org/) 23.0.0rc0 year 1 derivatives. Special thanks to Thomas Madison, etc. - Improved distortion correction - Improved bold projection to surface - New CIFTI outputs diff --git a/docs/postpipeline.md b/docs/postpipeline.md index 2205d5e..6e410ec 100644 --- a/docs/postpipeline.md +++ b/docs/postpipeline.md @@ -11,6 +11,10 @@ Multiple versions of the time series are provided, to allow investigator flexibi ### Infomap +Because brain synapses grow as a complex system of learning and evolving, neural networks don’t dutifully conform to anatomical coordinates across individuals. Therefore, it often makes sense to consider “function” as the pattern of connections between brain regions rather than assume function occurs at a specific anatomical location. Graph theory is an appropriate avenue for investigation because we can redefine brain regions as anatomically-irrespective nodes, and define the correlation (i.e. connectivity) between them as edges. Nodes that communicate heavily with each other are considered to be a part of the same community or network. Networks for the ABCD collection were detected using infomap (D. Edler, A. Holmgren and M. Rosvall, The MapEquation software package, available online at http://www.mapequation.org). Infomap is an algorithm that describes information flow in the network, by attempting to minimize the number of bits necessary to describe the whole network (Martin Rosvall and Bergstrom 2008; M. Rosvall, Axelsson, and Bergstrom 2009). For example, would it require fewer bits to describe the whole brain with few networks containing many nodes, or many networks with fewer nodes? Similar algorithms maximize modularity metrics, however, Infomap uses a random walk algorithm that uses edge weights (in this case, it uses connectivity) to determine the minimum descriptor code length necessary. Importantly, while the solution provides modules, it is not designed to maximize modularity. Importantly, neural networks have been shown to be scalable. As others have done previously (Gordon et al. 2017), we thresholded the whole brain correlation matrix (91282 x 91292 grayordinates) to the top x% of connections (or edges) because of the computational limitations of using a full set of 8.1 billion connections as descriptors in the map equation. We thresholded the connectivity matrix at a threshold of 0.3%, 0.4%, 0.5%, 1%, 1.5%, 2%, 2.5%, and 3%. These threshold were chosen to scale the number of edges. + +To generate a consensus across multiple edge percentages, we implemented a methodology developed by Gordon and colleagues(Gordon et al. 2017). Briefly, after infomap detected communities for each subject, Putative network assignments were then assigned to each subject’s communities by matching them at each threshold to the independent group networks from the University of Washington (n=120). For each individual, at each percentage threshold, the spatial overlap of each unknown community was compared to each one of the independent group networks separately using the Jaccard similarity index. The unknown community was then assigned that network identity to which it had the highest Jaccard similarity index. If the Jaccard Index was less than 0.1, the community remained unassigned, so as to avoid assigning communities to known networks based on only a few vertices. Assignments were first made with the large, well-known networks (Default, Lateral Visual, Motor, Fronto-Parietal, Cingulo-Opercular, Dorsal Attention), and then to the smaller, less well-known networks (e.g. Ventral Attention, Salience, Parietal Memory, lateral hand-face motor ). In each individual, a “consensus” network assignment was created by giving each grayordinate the canonical assignment it had at the sparsest threshold. + Infomap community detection is an unsupervised method of assigning nodes to communities in a graph based on information theory. Here, grayordinates are treated as nodes, and the edges are the correlation between the nodes. There are two versions of individual-specific maps available depending on whether not investigators are interested in the contribution of tasks to global network topography. The following maps are generated for subjects with at least 10 minutes of low-motion (See Hermosillo et al 2021) resting state data. The following are data subset names: @@ -25,7 +29,7 @@ The following maps are generated with all available minutes below the FD thresho fmriresults01_derivatives.func.networkmaps_task-restandtask_allmin_Surfonly_infomap_singlenet_dscalar.nii ``` -Because the tie density scales exponentially with the number of grayordinates, infomap community detection was only performed on the cortical surface and did not include subcortical structures (i.e. neither brainstem, cerebellum, nor diencephalon). Note, because infomap is an unsupervised community detection method, the subject may have more or fewer networks than a canonical network set. Where possible, we have attempted to assign networks based on the networks observed in an average dataset using the jaccard similarity (see Gordon et al. 2017), however in some instances the jaccard similarity sufficiently low (<0.1) such that the network did not resemble any of the canonical networks, in which case the network was provided a novel network assignment. +Because the tie density scales exponentially with the number of grayordinates, infomap community detection was only performed on the cortical surface and did not include subcortical structures (i.e. neither brainstem, cerebellum, nor diencephalon). Note, because infomap is an unsupervised community detection method, the subject may have more or fewer networks than a canonical network set. Where possible, we have attempted to assign networks based on the networks observed in an average dataset using the jaccard similarity (see Gordon et al. 2017), however in some instances the jaccard similarity sufficiently low (<0.1) such that the network did not resemble any of the canonical networks, in which case the network was provided a novel network assignment. ### Template matching @@ -75,7 +79,7 @@ Dscalars are provided in a fsLR32k format. In the dscalars, each grayordinate (n To generate overlapping networks for each participant, we used the identical template networks as described above, however, rather than assigning the grayordinate to the network with the maximum eta^2 value, a data-driven approach was used to assign multiple networks to each grayordinate. For each network we plotted the distribution of eta^2 values. The distribution of similarity (eta^2) for each network is both bimodal and skewed, such that most grayordinates do not resemble the network of interest (left peak), and some grayordiante have a spatial connectivity that are very similar to the template network (right peak). The distribution for eta^2 values was distributed into 10,000 bins and fitted with a cubic spline then smoothed (2,000 point Savitzky-Golay window), and the local minimum was taken. We then used this local minimum as the threshold for whether or not a grayordinate would be labelled with this network, where grayordinates above this threshold would receive the network assignment. -#### Movement Criteria +### Movement Criteria The following versions of individual-specific maps are available for subjects that had at least 10 minutes of low-motion resting state data. Networks were generated using exactly 10 minutes of data to ensure that an identical amount of time was used to generate correlation matrices for all participants. -fmriresults01_derivatives.func.networkmaps_task-restonly_10min_Surfandsub_templatematching_overlappingnet_dtseries.nii diff --git a/docs/release_notes.md b/docs/release_notes.md index af30b37..27c20d6 100644 --- a/docs/release_notes.md +++ b/docs/release_notes.md @@ -64,7 +64,7 @@ TODO: link to description and brief overview of subject counts #### Task outputs -(abcd-bids-tfmripipeline)[https://github.com/DCAN-Labs/abcd-bids-tfmri-pipeline] was ran on ABCD-BIDS derivativves of the baseline subjects. TODO: Feczko add a brief description of level 1 and level 2. +(abcd-bids-tfmripipeline)[https://github.com/DCAN-Labs/abcd-bids-tfmri-pipeline] was ran on ABCD-BIDS derivatives of the baseline subjects. ### Release 1.1.1 (10/7/2020) From eb7c4767894c3f7bca57be9a46fd21b1dc1d8a71 Mon Sep 17 00:00:00 2001 From: Audrey Houghton Date: Tue, 2 May 2023 13:42:22 -0500 Subject: [PATCH 5/9] Added information on fMRIprep improvements and change log for versions --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 94539b8..4bc71b0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -42,7 +42,7 @@ Latest updates are detailed below. (TODO: Audrey Check in with Luci/Michael about new features in updated version of fMRIPrep) -- New version of [fMRIPrep](https://fmriprep.org/) 23.0.0rc0 year 1 derivatives. Special thanks to Thomas Madison, etc. +- 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 From de6262763a857246f8cafc59429c7508dd028659 Mon Sep 17 00:00:00 2001 From: Anders Perrone Date: Wed, 10 May 2023 10:58:56 -0500 Subject: [PATCH 6/9] Update participants documentation --- docs/derivatives.md | 31 ++++++------------------------- docs/index.md | 25 ++++++++++--------------- docs/recommendations.md | 36 ++++++++++++++++++++++++++++-------- docs/release_notes.md | 6 +++--- 4 files changed, 47 insertions(+), 51 deletions(-) diff --git a/docs/derivatives.md b/docs/derivatives.md index e6ebc96..b1da83b 100644 --- a/docs/derivatives.md +++ b/docs/derivatives.md @@ -224,31 +224,12 @@ Motion-corrected individual functional task run in MNI space in a volume. ## 5. Task fMRI The task pipeline will produce its derivatives in the following BIDS-valid directory structure. -(TODO: Perrone confirm derivative structure in ABCC) - -``` -output_dir -├── level-1 -│ ├── events -│ │ └── sub-*_ses-*_task-*_run-*.tsv -│ ├── level1_run-* -│ │ ├── sub-*_ses-*_task-*_run-*_cope*.dtseries.nii -│ │ ├── sub-*_ses-*_task-*_run-*_dof -│ │ ├── sub-*_ses-*_task-*_run-*_logfile -│ │ └── sub-*_ses-*_task-*_run-*_res4d.dtseries.nii -│ └── temp -└── level-2 - ├── cope_files - │ └── sub-*_ses-*_task-*_contrast_*_cope*.dtseries.nii - ├── dof_files - │ └── sub-*_ses-*_task-*_contrast_*_tdof_t1.dtseries.nii - ├── log_files - │ └── sub-*_ses-*_task-*_contrast_*_logfile - ├── mask_files - │ └── sub-*_ses-*_task-*_contrast_*_mask.dtseries.nii - └── res4d_files - └── sub-*_ses-*_task-*_contrast_*_res4d.dtseries.nii -``` + +- `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 diff --git a/docs/index.md b/docs/index.md index 4bc71b0..7694152 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 @@ -33,21 +33,16 @@ 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/)- 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: Anders audit previous fmriprep uploads) - -(TODO: Audrey Check in with Luci/Michael about new features in updated version of fMRIPrep) - - 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 (TODO: Anders link to recomendations section) - + - 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/recommendations.md b/docs/recommendations.md index 3c60eac..7b3045d 100644 --- a/docs/recommendations.md +++ b/docs/recommendations.md @@ -10,11 +10,7 @@ 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. +Demographic and socioeconomic variables relating to the ABCD participants included in Collection 3165 can be found in the `participants.tsv` spreadsheet. A data dictionary further explaining each variable is also included. They are available for download on [the main NDA Collection 3165 page](https://nda.nih.gov/edit_collection.html?id=3165). A high level overview of these variables is detailed below. 1. `participant_id`: NDA unique pGUID, starting with `sub-` 1. `session_id`: Participant's session ID (all data within this first release are `ses-baselineYear1Arm1`) @@ -25,7 +21,25 @@ In a BIDS standard folder layout there should always be a `participants.tsv` (sp 1. `scanner_software`: Scanner software description 1. `matched_group`: Carefully matched similar groups 1. `sex`: Sex -1. `race_ethnicity`: Combined race & ethnicity variable +1. `demo_race_a_p___10`: White +1. `demo_race_a_p___11`: Black/African American +1. `demo_race_a_p___12`: Native American +1. `demo_race_a_p___13`: Alaska Native +1. `demo_race_a_p___14`: Native Hawaiian +1. `demo_race_a_p___15`: Guamanian +1. `demo_race_a_p___16`: Samoan +1. `demo_race_a_p___17`: Other Pacific Islander +1. `demo_race_a_p___18`: Asian Indian +1. `demo_race_a_p___19`: Chinese +1. `demo_race_a_p___20`: Filipino +1. `demo_race_a_p___21`: Japanese +1. `demo_race_a_p___22`: Korean +1. `demo_race_a_p___23`: Vietnamese +1. `demo_race_a_p___24`: Other Asian +1. `demo_ethn_p`: Latinx +1. `demo_race_a_p___25`: Other Race +1. `demo_race_a_p___77`: Refuse To Answer +1. `demo_race_a_p___99`: Don't Know 1. `age`: Age in months 1. `handedness`: Handedness 1. `siblings_twins`: Family member status @@ -33,13 +47,19 @@ In a BIDS standard folder layout there should always be a `participants.tsv` (sp 1. `participant_education`: Participant grade in school 1. `parental_education`: Highest level of parental education 1. `anesthesia_exposure`: History of participant anesthesia exposure +1. `neurocog_pc1.bl`: +1. `neruocog_pc2.bl`: +1. `neurocog_pc3.bl`: 1. `released`: Participants with updated fast track data based on revised QC (see: [known issues](https://collection3165.readthedocs.io/en/stable/release_notes/#released)) 1. `updated_dwi_input_json`: Participants scanned on GE with MR Software release DV25.0_R02_1549.b (see: [known issues](https://collection3165.readthedocs.io/en/stable/release_notes/#updated_dwi_input_json)) -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 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 table above. +![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). + + ## 3. The BIDS Quality Control File This Quality Control (QC) file contains QC metrics for data from this collection and is available for download on [the main NDA Collection 3165 page](https://nda.nih.gov/edit_collection.html?id=3165). Version 1.0.1 contains brain coverage scores for all runs of the `derivatives.func.runs_task-(MID|nback|rest|SST)_volume` data subsets. Currently, available fields in the QC file are: diff --git a/docs/release_notes.md b/docs/release_notes.md index 27c20d6..f6ca34f 100644 --- a/docs/release_notes.md +++ b/docs/release_notes.md @@ -28,7 +28,7 @@ Details about each update are given below. #### fMRIPrep outputs -fMRIPrep v20.2.0 was run on all 10,038 participants whose visit one data was successfully converted to BIDS. The limited fMRIPrep processing errors were due to subjects that did not have any valid fMRI runs, but we did not do any manual quality control of outputs. 9,484 participants have at least one output.The data is available in 18 submissions (a summary, including number of files and submission size can be found [here](https://docs.google.com/spreadsheets/d/1NbZ28vBvGVJb9miivgsJ695VVoFBSBuBQmWigN5pg_c/edit#gid=678992105)). Detailed information about the files included in each submission are on the second tab of that spreadsheet. Files with no submission name listed have not yet been uploaded. If additional outputs are desired, please reach out to [TODO: contact (Dylan Nielson?)]. fMRIPrep was run in a singularity container on resources from the NIH High Performance Computing Biowulf cluster. +fMRIPrep v20.2.0 was run on all 10,038 participants whose visit one data was successfully converted to BIDS. The limited fMRIPrep processing errors were due to subjects that did not have any valid fMRI runs, but we did not do any manual quality control of outputs. 9,484 participants have at least one output.The data is available in 18 submissions (a summary, including number of files and submission size can be found [here](https://docs.google.com/spreadsheets/d/1NbZ28vBvGVJb9miivgsJ695VVoFBSBuBQmWigN5pg_c/edit#gid=678992105)). Detailed information about the files included in each submission are on the second tab of that spreadsheet. Files with no submission name listed have not yet been uploaded. If additional outputs are desired, please reach out to Dylan Nielson at dylan.nielson@nih.gov. fMRIPrep was run in a singularity container on resources from the NIH High Performance Computing Biowulf cluster. #### Replaced subjects The initial release was processed prior to new updates to the fast track QC spreadsheet that affected the original inputs for 144 participants. This led to discrepancies in the number of timepoints reported for connectivity matrices (see below) relative to the inputs. The 144 participants were re-processed through the ABCD-BIDS pipeline at the Minnesota Supercomputing Institute (MSI), and being replaced, subsequent the required NDA review. The participants.tsv file indicates which subjects were reprocessed. @@ -54,11 +54,11 @@ The DWI acquisition parameters from subjects scanned on Philips and GE with MR S #### Individual-specific network maps (Infomap) -TODO: link to description and brief overview of subject counts +(InfoMap) #### Template Matching -(TODO Anders edit Robert's template matching section and summarize here): link to description and brief overview of subject counts +(Template Matching)[https://github.com/DCAN-Labs/compare_matrices_to_assign_networks] *Submission IDs: 36458 - 36630* From 89b172c7bdaa54d6ccc15087ee39481370f64956 Mon Sep 17 00:00:00 2001 From: Anders Perrone Date: Wed, 10 May 2023 11:29:12 -0500 Subject: [PATCH 7/9] Add Infomap description in release notes --- docs/release_notes.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/release_notes.md b/docs/release_notes.md index f6ca34f..a799061 100644 --- a/docs/release_notes.md +++ b/docs/release_notes.md @@ -47,14 +47,11 @@ The DWI acquisition parameters from subjects scanned on Philips and GE with MR S *Submission ID: 36448* -#### Individual-specific network maps +#### Individual-specific network maps using the Infomap algorithm - Multiple versions of the time series are provided, to allow investigator flexibility in their desired analysis: either exactly 10 minutes of randomly sampled frames, all available frames below the 0.2mm FD threshold, or concatenated rest and task time series data in the following order: rest, MID, n-back, and SST (provided that the participant had an available scan for the task). For full details of inter- and intra- participant reliability, and motion correction, see Hermosillo et al. 2021 (in prep). +Infomap community detection is an unsupervised method of assigning nodes to communities in a graph based on information theory. Here, grayordinates are treated as nodes, and the edges are the correlation between the nodes. There are two versions of individual-specific maps available depending on whether not investigators are interested in the contribution of tasks to global network topography. 1) Maps are generated for subjects with at least 10 minutes of low-motion (See Hermosillo et al 2021) resting state data. 2) - -#### Individual-specific network maps (Infomap) - -(InfoMap) +Maps are generated with all available minutes below an FD threshold of 0.2mm (and corresponding BOLD outlier detection) using concatenated rest and task data. Because the tie density scales exponentially with the number of grayordinates, infomap community detection was only performed on the cortical surface and did not include subcortical structures (i.e. neither brainstem, cerebellum, nor diencephalon). Note, because infomap is an unsupervised community detection method, the subject may have more or fewer networks than a canonical network set. Where possible, we have attempted to assign networks based on the networks observed in an average dataset using the jaccard similarity (see Gordon et al. 2017), however in some instances the jaccard similarity sufficiently low (<0.1) such that the network did not resemble any of the canonical networks, in which case the network was provided a novel network assignment. #### Template Matching From 078f5e2af998f9d4e6a65aeda8a533cee3d3ce0f Mon Sep 17 00:00:00 2001 From: Anders Perrone Date: Wed, 10 May 2023 11:30:47 -0500 Subject: [PATCH 8/9] Add description of ERI data --- docs/inputs.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/inputs.md b/docs/inputs.md index be432f7..d25d1a5 100644 --- a/docs/inputs.md +++ b/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). From 6eed6ba070cfd015fc1c0a0be68b170de469a37a Mon Sep 17 00:00:00 2001 From: Anders Perrone Date: Wed, 10 May 2023 11:57:05 -0500 Subject: [PATCH 9/9] Fix formatting and add task pipeline descriptions --- docs/index.md | 10 +++---- docs/pipelines.md | 70 +++++++++++++++++++++---------------------- docs/release_notes.md | 6 ++-- 3 files changed, 43 insertions(+), 43 deletions(-) diff --git a/docs/index.md b/docs/index.md index 7694152..e830dca 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/pipelines.md b/docs/pipelines.md index 56c5907..3a36934 100644 --- a/docs/pipelines.md +++ b/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 ().” ## 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", diff --git a/docs/release_notes.md b/docs/release_notes.md index a799061..5bdf98d 100644 --- a/docs/release_notes.md +++ b/docs/release_notes.md @@ -14,12 +14,14 @@ User feedback will guide our course for future releases. Provide feedback on wh ### Release 2.0.0 (6/22/2022) New updates to the ABCD BIDS Community Collection cover both revisions to existing datasets and new derivatives. Revisions include: + 1. Uploading 144 participants with new data due to revised fast track QC 2. Providing Connectivity matrices for those participants with discrepancies in the number of timepoints used 3. Uploading JSONs for the diffusion inputs in some participants. 4. Updated version of the participants.tsv to v1.0.2 includes correction to site and sex designation for a small subset of subjects based on new information from the DAIC. New additions include: + 1. Individual-specific network labels based on a template matching approach and infomap approaches 2. Derivatives for the fmriprep pipeline, and 3. Level-2 task files from the ABCD-task-fMRI pipeline. @@ -28,7 +30,7 @@ Details about each update are given below. #### fMRIPrep outputs -fMRIPrep v20.2.0 was run on all 10,038 participants whose visit one data was successfully converted to BIDS. The limited fMRIPrep processing errors were due to subjects that did not have any valid fMRI runs, but we did not do any manual quality control of outputs. 9,484 participants have at least one output.The data is available in 18 submissions (a summary, including number of files and submission size can be found [here](https://docs.google.com/spreadsheets/d/1NbZ28vBvGVJb9miivgsJ695VVoFBSBuBQmWigN5pg_c/edit#gid=678992105)). Detailed information about the files included in each submission are on the second tab of that spreadsheet. Files with no submission name listed have not yet been uploaded. If additional outputs are desired, please reach out to Dylan Nielson at dylan.nielson@nih.gov. fMRIPrep was run in a singularity container on resources from the NIH High Performance Computing Biowulf cluster. +fMRIPrep v20.2.0 was run on all 10,038 participants whose visit one data was successfully converted to BIDS. The limited fMRIPrep processing errors were due to subjects that did not have any valid fMRI runs, but we did not do any manual quality control of outputs. 9,484 participants have at least one output. The data is available in 18 submissions (a summary, including number of files and submission size can be found [here](https://docs.google.com/spreadsheets/d/1NbZ28vBvGVJb9miivgsJ695VVoFBSBuBQmWigN5pg_c/edit#gid=678992105)). Detailed information about the files included in each submission are on the second tab of that spreadsheet. Files with no submission name listed have not yet been uploaded. If additional outputs are desired, please reach out to Dylan Nielson at . fMRIPrep was run in a singularity container on resources from the NIH High Performance Computing Biowulf cluster. #### Replaced subjects The initial release was processed prior to new updates to the fast track QC spreadsheet that affected the original inputs for 144 participants. This led to discrepancies in the number of timepoints reported for connectivity matrices (see below) relative to the inputs. The 144 participants were re-processed through the ABCD-BIDS pipeline at the Minnesota Supercomputing Institute (MSI), and being replaced, subsequent the required NDA review. The participants.tsv file indicates which subjects were reprocessed. @@ -61,7 +63,7 @@ Maps are generated with all available minutes below an FD threshold of 0.2mm (an #### Task outputs -(abcd-bids-tfmripipeline)[https://github.com/DCAN-Labs/abcd-bids-tfmri-pipeline] was ran on ABCD-BIDS derivatives of the baseline subjects. +(abcd-bids-tfmripipeline)[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). An example fsf file template for ABCD's MID task is made available for users to review on ABCC (https://osf.io/psv5m/). MID, Nback, and SST level-2 task outputs are available for the baseline sessions for all data that passed task QC. These outputs include the fully-processed dtseries data that are subsequently ready for the user to perform their desired third-level or group-wise analyses. ### Release 1.1.1 (10/7/2020)