Add --output-spaces argument and use resampler to warp derivatives to requested space(s)

[tsalo]

Summary

NiPreps' resampler will be used in fMRIPost and sMRIPost workflows to warp native-space derivatives to target spaces. I would ultimately like to include this in XCP-D as well.

Additional details

I need to double-check the fMRIPrep --level documentation, but I think we need to require resampling-level outputs from fMRIPrep.

I'm not sure if resampler can handle slice timing correction yet.

Next steps

1. Add an --output-spaces parameter, along with space-parsing.
   • It would probably be easier to do this once Adopt Nipreps-style Config object #1040 is merged.
2. Try to collect the target space's preprocessing derivatives, in the hopes that we can skip the resampling.
   • This will also be a necessary step for preprocessing pipelines that only produce standard-space outputs (e.g., ABCD-BIDS, HCP, and UK Biobank).
3. Otherwise, collect native-space preprocessing derivatives and the necessary transforms.
4. For each transform, warp the native-space derivative to the requested standard space.
   • It would be easiest to do this before anything else, but it probably makes more sense to do this at the end of the workflow.

EDIT: I just want to track nipreps/fmripost-aroma#34 in this issue because fMRIPost-AROMA will probably be the first functioning implementation of this general workflow.

[tsalo]

Ultimately, we may want to support three basic patterns (see below). I've included fMRIPost-AROMA derivatives in the examples as well.

Preprocessing derivatives in standard space

xcp_d \
    /derivatives/<pipeline> \  # path to pipeline with only standard-space derivatives (e.g., HCP)
    /derivatives/xcp_d \
    --output-spaces MNI152NLin6Asym:res-2 \  # will raise an error if it doesn't match the available spaces
    --derivatives aroma=/derivatives/fmripost-aroma \
    ...

Preprocessing derivatives with native-space data and transforms

E.g., fMRIPrep with --level resampling

xcp_d \
    /derivatives/<pipeline> \  # path to pipeline with native-space derivatives and warps
    /derivatives/xcp_d \
    --output-spaces MNI152NLin6Asym:res-2 \  # will raise an error if warps aren't available
    --derivatives aroma=/derivatives/fmripost-aroma \
    ...

Preprocessing derivatives with transforms, plus raw dataset

E.g., fMRIPrep with --level minimal

xcp_d \
    /dset \  # path to raw dataset
    /derivatives/xcp_d \
    --output-spaces MNI152NLin6Asym:res-2 \  # will raise an error if warps aren't available
    --derivatives \
    preprocessed=/derivatives/<pipeline> \  # path to preprocessing derivatives with warps
    aroma=/derivatives/fmripost-aroma \
    ...