Introduction

If you are running your DBM with in-house tools following our documentation, there are lots of helpful wikis to guide you through the process, but it may be a bit confusing to know where they are and know which ones are useful. To that end, the goal of this wiki is 1) provide a high-level overview of the pipeline 2) to point you towards all of the useful wikis and 3) to fill in any gaps. Please bear in mind that this is a living document--if something is confusing, or if there is an error, edit it! Be sure to check to make sure you are using the most up-to-date versions of everything.

High-level overview of DBM pipeline

Quality Control

Convert to niftis

After you have acquired your raw data, you can find it all in /data/chamal/Bruker_7T_animal_scans/pv6/{SCANNER_ID}/{DATA_FOLDER}. The first thing you should do is create a directory in /data/scratch2/{YOUR_USERNAME}/{YOUR_PROJECT_NAME} called raw_scans. Importantly, do not make a copy of the data, as this will use up a lot of storage. Instead, we will make a symbolic link (symlink) from the place where the data is stored to your project file.

To link a specific scan run the following in the terminal: ln -s /data/chamal/Bruker_7T_animal_scans/pv6/{SCANNER_ID}/{DATA_FOLDER} /data/scratch2/{YOUR_USERNAME}/{YOUR_PROJECT_NAME}/raw_scans

You can write a for loop to loop through all files in your project code and create the symlinks:

for file in /data/chamal/Bruker_7T_animal_scans/pv6/{SCANNER_ID}/*{PROJ_CODE}*; do ln -s $file /data/scratch2/{YOUR_USERNAME}/{YOUR_PROJECT_NAME}/raw_scans; done

When you have done this, the raw_scans file should appear to be filled with the raw data folders, but they will not take up extra storage space. Then, you must convert the Bruker data to niftis. To do so, follow the wiki here. (BIDS-compliant structure coming soon)

Manual QC

Once all of your data are converted to niftis, you can QC them manually. Typically for mouse data, you should either do this process 2-3 times yourself or have multiple raters QC them to make sure that you have accurate assessments. Steps for proper QC can be found here. In short, you should be using the make_slice_images.sh script and scoring via PyQC, as detailed in that wiki page, Additionally, you should check out this guide for more information about what you could expect to see during your QC process, specifically for your initial QC wiki of the 'raw' (ie un-preprocessed) nifti images. Please note that this is a bit of a skill that needs to be developed and it is best practice to have a more experienced lab member to also QC your images (as a second scorerer) to assess the reliability and reproducibility of your scoring to meet standardized lab practices.

Preprocessing

The preprocessing depends on your study a bit. A guide to the standard preprocessing can be found here for adult mice (latest version coming soon). If, however, you are working with embryos, use this preprocessing guide. If you are working with neonates, information can be found in the subsection here.

After preprocessing, be sure to look at your outputs to make sure nothing looks weird. For example, sometimes an image is moved partially out of the FOV. You must perform another quick QC to flag mice that 'failed' preprocessing.

Running DBM

Our current DBM pipeline is available here, and should be referenced and cited using this paper: https://doi.org/10.52294/001c.133510

A bit of history: In "recent" years (2022-2023) we moved away from the Pydpiper tools published in our older papers to Gabe's newer registration tools. As a result, the thorough documentation found here is marked "old". While some aspects are no longer applicable, there is still value in other sections. For example, the "Looking at Results" section which I will address more later. More applicable is the github here, however, if this is your first time running DBM, it may be a bit confusing what you need. Again, if you are using neonates, be sure to check out this wiki.

Running DBM on Trillium

In general, you will likely run the DBM on Trillium. If this is your first time using Trillium, follow these instructions.

Before running any command related to this, you should be writting them out into an executable script:

for example: setting-up-dbm.sh

Load appropriate modules:

module load cobralab

Get a copy of the twolevel GitHub directory

git clone --recursive https://github.com/CoBrALab/optimized_antsMultivariateTemplateConstruction.git

Copying files to Trillium

Now, you need to copy several things to Trillium to run the DBM.

1. Your preprocessed images in nifti form:

rsync -avzh *nii.gz [email protected]:/home/USERNAME/links/scratch/PROJECTNAME/

2. Input file that tells the pipeline which files to run and what their relationship

3. A template and mask that you want to base your registrations on (most commonly the DSURQE atlas, which can be found here: /opt/quarantine/resources/Dorr_2008_Steadman_2013_Ullmann_2013_Richards_2011_Qiu_2016_Egan_2015_40micron_CoBrALab/nifti/DSURQE_100micron_denoise_N3_recrop.nii.gz). More details below

For instance:

If you have longitudinal data, the format of this file (txt or csv) must be one row per subject, one column per time point. So, if you have 40 subjects, three timepoints, you will have 40 rows with three columns. Wiki coming soon for how to get R to create this for you!

If you have cross-sectional data, it'll only have one column with the same number of rows as your subject number. This file is very easy to make since all you need to do is print out the filename one after the other and can be done using this command in the terminal: ls inputs/*.nii.gz >> input_files.txt

Setting up your run script

You must create an executable script for each of the two-steps of running DBM, so that you can re-run it later and keep a record of what your commands were.

The first step is running the modelbuild which ultimately produces the group average and the second is running dbm to generate the jacobians

For the modelbuild step, depending on if you are running a cross-section or longitudinal study, the script you should point to are optimized_antsMultivariateTemplateConstruction/modelbuild.sh or optimized_antsMultivariateTemplateConstruction/twolevel_modelbuild.sh

The minimal run command for the modelbuild in this case would be as follows if you are running a 1-level (cross-sectional): optimized_antsMultivariateTemplateConstruction/modelbuild.sh input_files.txt

Or, if you are running a two-level (longitudinal): optimized_antsMultivariateTemplateConstruction/twolevel_modelbuild.sh input_files.txt

You generally would select different options, such as including a starting target, a final target, or increasing the time attributed to various stages, but these are decisions you will make along the way, and not generic enough to be included here.

Some common added features are:

A) a final target (and its mask)

for cross-sectional: --final-target and --final-target-mask for longitudinal: --secondlevel-final-target and --secondlevel-final-target-mask

It is a good idea to include a final target and mask, which will be registered to your average and give you the transforms. This can be used to easily compute a stats mask. Can be done for both cross-sectional and longitudinal

B) a starting target (and its mask): this dictates the resolution and the orientation of the brains as per the target you specify (again most commonly the DSURQE). This will make sure when you visualize results, the background image is properly oriented and squared off.

for cross-sectional: --starting-target and --starting-target-mask for longitudinal: --firstlevel-starting-target, --firstlevel-starting-target-mask, --secondlevel-starting-target and --secondlevel-starting-target-mask

denoting that the registration should start off in the space you designated as a firstlevel, and again with the subject averages as the secondlevel. You don't necessarily need to designate a firstlevel if your subjects are properly oriented

This can be done in conjunction with the --final-target options

Example for a cross-sectional (onelevel) study

This is my script: run-modelbuild.sh

module load cobralab
optimized_antsMultivariateTemplateConstruction/modelbuild.sh --final-target DSURQE_100micron_N4_recrop.nii.gz \
--final-target-mask DSURQE_100micron_N4_recrop_mask.nii.gz input_files.txt

Example for a longitudinal study

This is my script: run-modelbuild.sh

module load cobralab
optimized_antsMultivariateTemplateConstruction/twolevel_modelbuild.sh \
        --firstlevel-starting-target DSURQE_100micron_N4_recrop.nii.gz \
        --firstlevel-starting-target-mask DSURQE_100micron_N4_recrop_mask.nii.gz \
        --secondlevel-starting-target DSURQE_100micron_N4_recrop.nii.gz \
        --secondlevel-starting-target-mask DSURQE_100micron_N4_recrop_mask.nii.gz \
         input_files.txt

QC'ing ModelBuild Outputs

Once your modelbuild is done running, it is a good idea to QC the outputs. You must download them onto the cic server from trillium using the rsync command.

Here are the following outputs you want to QC:

1. the average, named template_sharpen_shapeupdate.nii.gz can be found here for cross-sectional: output/final/average/template_sharpen_shapeupdate.nii.gz can be found here for longitudinal: output/secondlevel/final/average/template_sharpen_shapeupdate.nii.gz

2. subject averages: for cross-sectional: output/final/resample/*.nii.gz for longitudinal: output/secondlevel/final/resample/*nii.gz

QC using the same methods described for initial QC above, using the make_slice_images.sh and PyQC

Running the post-processing DBM

Once the modelbuild has successfully run, before running the second step (the dbm script), you should QC the outputs, specifically for a longitudinal study, to check that the subject averages have been generated properly and that there are no registration errors as these will propagate into your jacobian outputs.

Again, you must create an executable script to run this next part, for example named "run-dbm.sh", which the following inside, again depending on your study design (cross-sectional vs longitudinal)

For a onelevel (cross-sectional), simply run

optimized_antsMultivariateTemplateConstruction/dbm.sh input_files.txt

Or

For a two-level (longitudinal):

optimized_antsMultivariateTemplateConstruction/twolevel_dbm.sh input_files.txt

Again, there are options to add to these commands as we did for the modelbuild run, however they are less commonly used. You can explore those options here

QC'ing DBM Outputs

Here are the outputs you'll be wanting - it is best to do a quick QC mainly to make sure that these files open properly and aren't corrupt

Jacobians:

• For cross-sectional data:
• • output/dbm/jacobian/relative/smooth/*
• • output/dbm/jacobian/full/smooth/*
• For longitudinal data
• • output/secondlevel/resampled-dbm/jacobian/relative/smooth/
• • output/secondlevel/resampled-dbm/jacobian/full/smooth/
• • output/secondlevel/overall-dbm/jacobian/relative/smooth/
• • output/secondlevel/overall-dbm/jacobian/full/smooth/

Note: Two-level DBM processing produces two types of outputs, overall-dbm files, which encode the entire voxel-wise difference between the original input scan and the final second-level average, and resampled-dbm which encode the within-subject change, with voxel-wise correspondence at the population level. The resampled-dbm outputs are typically what is used for longitudinal analysis as they contain within-subject changes aligned at the population level. Full are the absolute Jacobians that include the affine transformations and relative are the relative Jacobians that include only nonlinear transformations. The ones you want to analyze are likely determined by your research question, but you can save both to be safe.

Also, note that you should analyze the ones in the smooth/ directory as these are (by default) 4 voxel smoothed for general linear modelling for statistical analysis

You should also QC and likely manually correct the mask that is associated with the modelbuild average (template_sharpen_shapeupdate_mask.nii.gz). If you need to make a mask, follow this wiki.

Preparing for analyses in R

Once you have assured your run is high quality, you double check that you've downloaded all the outputs you want for your analyses. It's also a good idea to save your run file (run_modelbuild.sh or run_dbm.sh). This would allow you to have good documentation and easily update it if you include other options.

To analyze the data voxelwise in R, you will need 1) your average as MINC 2) a mask of the average as MINC, 3) the appropriate Jacobians as MINC. Transform to MINC using nii2mnc.

The "Looking at Results" section of this wiki is still useful for setting up your R script to run an LM/LMER.

Saving heatmap outputs of mincLMs/mincLMERs

To visualize the heatmaps of results automatically, follow this wiki.

Identifying and plotting peak-voxels

See wiki here