dHCP_fetal_fMRI_release_paper

The resourse contains materials and scripts associated with dHCP fetal fMRI release paper

This page is in the process of being updated, for specific queries please write to: slava.karolis@kcl.ac.uk

Citation:

"The developing Human Connectome Project fetal functional MRI release: Methods and data structures"

Vyacheslav R Karolis, Lucilio Cordero-Grande, Anthony Price, Emer Hughes, Sean Patrick Fitzgibbon, Vanessa Kyriakopoulou, Alena Uus, Nicholas Harper, Denis Prokopenko, Devi Bridglal, Jucha Willers Moore, Sian Wilson, Maximilian Pietsch, Daan Christiaens, Maria Deprez, Logan Zane John Williams, Emma Claire Robinson, Antonios Makropoulos, Seyedeh-Rezvan Farahibozorg, Jonathan O'Muircheartaigh, Mary Rutherford, Daniel Rueckert, David Edwards, Tomoki Arichi, Stephen M Smith, Eugene Duff, Joseph V Hajnal bioRxiv 2024.06.13.598863; doi: https://doi.org/10.1101/2024.06.13.598863

txt

This folder contains text files with sample information. The convention is subID, sesID, age, sex (1-male, 0 -female), nearest template.

QC

The folder contains QC reports and scripts that were used to generate them

temporal filtering

The folder containing the code is denoise The core script performing temporal filtering is dnx.py Running this script is faciliated by dnx_wrapper.py, which allows customising temporal filtering model and saves the processed data.

dnx_wrapper.py accepts 4 non-optional inputs:
--sub - subject ID, e.g., CC00856XX15

--ses - session ID, e.g., 3530

--root_dir - root directory for the dHCP data (the one that contains rawdata and derivatives data structures

--odir - directory for writing the output. Needs to be unique for each case/model; otherwise, the outputs will be overwritten. Two outputs are generated: data.nii.gz (data after temporal filtering) and yhat.nii.gz (timeseries that has been removed from the data as a result of temporal filtering). In other words, data.nii.gz + yhat.nii.gz will reconstruct the data prior to filtering

The optional parameters can be defined to customise the temporal filtering model and/or overwrite the default settings:

--config - this allows using your own configuration file. Note that you will have to modify the code if you want to use regressors, which are not available in the release

--regr_set - customised regressor set, space-separated. The keys to the regressor types are:

vc - volume censoring
dm - density map
fm - folding maps
ica - temporal courses of independent components, obtained by FSL melodic, derived from white matter + csf mask
bp - frequency bandpath filtering
mp_pca - motion-parameter (MP) based regressors>
The default option (used for the release) includes all of the above

--ica-options - number of independent components to include (max 6, which is default). These components are derived from combined eroded white matter + CSF mask. If you want to use a larger number of components, you will need to re-run FSL melodic with dimensionality of your choice and alter config file correspondingly. The eroded WF+CSF mask is included in the release

--mp_pca-options - customises the set of motion-parameter(MP)-based voxelwise regressors using convention XX_YY_pZZ or XX_YY_nZZ, where XX is the number of regressors of the 1st type, YY - the number of regressors of the 2nd type, and pZZ or nZZ is the rule for the regressor set truncation. Below is the a more detailed explanation.
There are two types of MP-based regressors, one is based on MP proper and the other is representing slice-to-to-slice MP changes (see the section "Motion parameter (MP)-based voxelwise maps" in the paper for the exact definition). The code takes these as an input and performs - indpendently for each type - their expansion, adding to them, in exact order, their squared value, volumetric differential, squared value of volumetric differentials, second order volumetric differentials, the squared value of their second order differentials. Internally, the script prevents using options that are divisible by 6 with a remainder, which is the number of motion parametes (3 rotation and 3 translation parameters). The expansions of the two types of regressors are then concatentated and converted into principal component representation. There are two ways that allow one to truncate the obtained set, using the flag p for the percent of variance explained by obtained components in the entire regressor set and n for the number of regressors to keep. For instance, the default option is 36_24_p99, which signifies 36 regressors of the 1st type, 24 of the second type, and using components that account for 99 percent of variance in the concatentated regressor set. Alternatively, 36_24_n6 signifies the identical expansions of the MP-based regressors and subsequent PCA representation, but only the first 6 principal components will be included into the model

--bp-options - define bandpath for the frequencies to regress out using convention lXX_hYY, hYY_lXX, lXX or hYY, where XX is a decimal fraction for a cut-off lowpass frequency and YY is the same for a cut-off highpass frequency. For instance l1 represents the cut-off lowpass frequency of 0.1. The default is h0067 (the cut-off highpass frequency .0067)

Examples:

The filtering model used for the release, using parameters defined in config.yml and therefore dropping optional parameters, is:

python ./dnx_wrapper.py --sub $subID --ses $sesID --root_dir $path_to_dHCP_data_directory --odir $output_directory

The same model can be written explicitly (and can be used as a template for modification of the model) as:

python ./dnx_wrapper.py --sub $subID --ses $sesID --root_dir $path_to_dHCP_data_directory --odir $output_directory --config ./config.yml --regr_set vc bp dm fm ica mp_pca --mp_pca-options 36_24_p99 --ica-options 6 --bp-options h0067