A few questions about the workflow of XCP-D

1

Dear experts,

I am relatively new to XCP-D and have run it on my data using the following command:

docker run -ti --rm \
        -v ${sour_dir}:/input:ro \
        -v ${targ_dir}:/output \
        -v ${work_dir}:/work \
        -v ${FSLICENSE}:/opt/freesurfer/license.txt \
        -v ${TFDIR}:/opt/templateflow \
        -e TEMPLATEFLOW_HOME=/opt/templateflow \
        -u $(id -u):$(id -g) \
        pennlinc/xcp_d:26.0.2 \
        /input /output participant \
        -w /work --nthreads 10 --fs-license-file /opt/freesurfer/license.txt \
        --mode none --input-type fmriprep --file-format nifti \
        --dummy-scans 5 --despike y -p 27P --smoothing 0 -m n \
        --skip connectivity \
        --motion-filter-type none --fd-thresh 0.2 --output-type interpolated \
        --lower-bpf 0.01 --upper-bpf 0.1 \
        --atlases 4S256Parcels --min-coverage 0.5 \
        --output-run-wise-correlations n --warp-surfaces-native2std n \
        --linc-qc y --abcc-qc n \
        --output-layout bids

After reading the documentation and inspecting the outputs, I have a few questions regarding the underlying workflows:

  1. Surface-based vs. volume-based workflows (--file-format)

The --file-format option determines whether to run surface-based or volume-based workflows. If I want to perform both surface- and volume-based analyses, should I run XCP-D twice with different settings for --file-format? Or is there a way to run both in a single call?

  1. Template and atlas management

Are the templates and atlases used by XCP-D built-in, or are they obtained via TemplateFlow? More specifically, is it necessary to specify a TemplateFlow directory (e.g., via -v ${TFDIR}:/opt/templateflow) when running XCP-D? This part does not seem to be clearly covered in the documentation.

  1. Accuracy of the automatically generated Methods section

I noticed that the automatically generated Methods section in the subject-wise HTML report is not always accurate. For example, I set --output-type interpolated, but the Methods section states: “The interpolated time series were then censored using the temporal mask.” This seems inconsistent with the actual processing steps. Could you clarify whether this is a known issue or if I might have misunderstood the workflow?

  1. Motion outliers: censoring/interpolation vs. confound regression

In the subject-wise HTML report, the design matrix includes a column for motion outliers. However, I believe motion outliers are used for interpolation and censoring rather than as regressors in confound regression. Could you clarify how XCP-D actually handles motion outliers?

Thank you very much for your time and guidance.

Best regards,

Yang Hu

2

At the moment you need to run XCP-D twice.

The main ones XCP-D uses are downloaded from TemplateFlow and stored in the Docker/Apptainer image. XCP-D will automatically download new ones that it needs from TemplateFlow and store them in the image. If your compute node doesn’t have internet access, you can pre-download the necessary templates and mount it into the image, but that generally isn’t necessary.

The interpolated time series is censored using the temporal mask for certain outputs (e.g., correlation matrices, ReHo, ALFF), but the dense and parcellated time series will be interpolated.

The design matrix includes the motion outliers just to give users a sense of how many degrees of freedom are removed. They are not regressed out of the data. For more information about the exact steps, I suggest looking at Processing Pipeline Details — xcp_d 26.0.2.dev2+g48b878745 documentation.

1 Like