xcp_d.ingression.utils module

Functions to support ingression of non-BIDS preprocessing derivatives.

xcp_d.ingression.utils.collect_anatomical_files(anat_dir_orig, anat_dir_bids, base_anatomical_ents)[source]

Collect anatomical files from ABCD or HCP-YA derivatives.

Parameters:

  • anat_dir_orig (str) – Path to original anatomical derivatives directory containing source files (e.g., T1w.nii.gz, ribbon.nii.gz, brainmask_fs.nii.gz).

  • anat_dir_bids (str) – Path to output BIDS-compliant anatomical directory.

  • base_anatomical_ents (str) – BIDS entity string to use as filename prefix (e.g., “sub-01_space-MNI152NLin6Asym_res-2”).

Returns:

Dictionary mapping source file paths to lists of destination file paths. Files that do not exist in the source directory are omitted with a warning.

Return type:

dict

xcp_d.ingression.utils.collect_hcp_confounds(task_dir_orig, out_dir, prefix, work_dir, bold_file, brainmask_file, csf_mask_file, wm_mask_file)[source]

Create confound regressors from ABCD-BIDS or HCP-YA derivatives.

Parameters:

  • task_dir_orig (str) – Path to folder containing original preprocessing derivatives.

  • out_dir (str) – Path to BIDS derivatives ‘func’ folder, to which the confounds file will be written.

  • prefix (str) – The filename prefix to use for the confounds file. E.g., “sub-X_ses-Y_task-rest”.

  • work_dir (str) – Path to working directory, where temporary files created by nilearn during the masking procedure will be stored.

  • bold_file (str) – Path to preprocessed BOLD file.

  • brainmask_file (str) – Path to brain mask file in same space/resolution as BOLD file.

  • csf_mask_file (str) – Path to CSF mask file in same space/resolution as BOLD file.

  • wm_mask_file (str) – Path to WM mask file in same space/resolution as BOLD file.

xcp_d.ingression.utils.collect_meshes(anat_dir_orig, anat_dir_bids, sub_id, subses_ents)[source]

Collect mesh files from ABCD or HCP-YA derivatives.

Collects pial and white matter surface meshes for both hemispheres from the fsaverage_LR32k subdirectory.

Parameters:

  • anat_dir_orig (str) – Path to original anatomical derivatives directory. Must contain an fsaverage_LR32k subdirectory with surface GIFTI files.

  • anat_dir_bids (str) – Path to output BIDS-compliant anatomical directory.

  • sub_id (str) – Subject identifier without “sub-” prefix.

  • subses_ents (str) – BIDS subject/session entity string (e.g., “sub-01” or “sub-01_ses-1”).

Returns:

Dictionary mapping source mesh file paths to lists of destination file paths. Files that do not exist in the source directory are omitted with a warning.

Return type:

dict

xcp_d.ingression.utils.collect_morphs(anat_dir_orig, anat_dir_bids, sub_id, subses_ents)[source]

Collect and convert morphometry files to CIFTIs.

Converts hemisphere-specific GIFTI morphometry files (thickness, curvature, sulcal depth, myelin maps) to combined CIFTI dscalar files.

Parameters:

  • anat_dir_orig (str) – Path to original anatomical derivatives directory. Must contain an fsaverage_LR32k subdirectory with morphometry GIFTI files.

  • anat_dir_bids (str) – Path to output BIDS-compliant anatomical directory where CIFTI files will be written.

  • sub_id (str) – Subject identifier without “sub-” prefix.

  • subses_ents (str) – BIDS subject/session entity string (e.g., “sub-01” or “sub-01_ses-1”).

Returns:

Dictionary mapping source GIFTI file paths to output CIFTI file paths. Unlike other collect functions, this returns the actual output paths (not wrapped in lists) because the files are converted rather than copied.

Return type:

dict

xcp_d.ingression.utils.collect_ukbiobank_confounds(task_dir_orig, out_dir, prefix, work_dir, bold_file, brainmask_file)[source]

Create confound regressors from UK Biobank derivatives.

Parameters:

  • task_dir_orig (str) – Path to folder containing original preprocessing derivatives.

  • out_dir (str) – Path to BIDS derivatives ‘func’ folder, to which the confounds file will be written.

  • prefix (str) – The filename prefix to use for the confounds file. E.g., “sub-X_ses-Y_task-rest”.

  • work_dir (str) – Path to working directory, where temporary files created by nilearn during the masking procedure will be stored.

  • bold_file (str) – Path to preprocessed BOLD file.

  • brainmask_file (str) – Path to brain mask file in same space/resolution as BOLD file.

xcp_d.ingression.utils.copy_file(src, dst)[source]

Copy a file from source path to destination path.

Only performs the copy if the destination file does not exist or differs from the source file (based on shallow file comparison).

Parameters:

  • src (str) – Path to the source file.

  • dst (str) – Path to the destination file.

xcp_d.ingression.utils.copy_files_in_dict(copy_dictionary)[source]

Copy files according to a source-to-destination mapping dictionary.

Parameters:

copy_dictionary (dict) – Dictionary mapping source file paths (str) to lists of destination file paths (list of str). Each source file will be copied to all specified destinations. A warning is logged if a source file is mapped to multiple destinations.

Raises:

ValueError – If any dictionary value is not a list.

xcp_d.ingression.utils.extract_mean_signal(mask, nifti, work_dir)[source]

Extract mean signal within mask from a NIFTI image.

Uses nilearn’s NiftiMasker to extract voxel time series within the mask, then computes the mean across voxels at each time point.

Parameters:

  • mask (str) – Path to binary mask NIFTI file defining the region of interest.

  • nifti (str) – Path to 4D NIFTI file from which to extract the signal.

  • work_dir (str) – Path to working directory used for nilearn’s caching mechanism.

Returns:

1D array of mean signal values, one per time point (volume).

Return type:

numpy.ndarray

xcp_d.ingression.utils.get_identity_transform_destinations(anat_dir_bids, subses_ents, volspace='MNI152NLin6Asym')[source]

Return destination paths for T1w<->template identity transform files.

Parameters:

  • anat_dir_bids (str) – Path to BIDS anatomical derivatives directory.

  • subses_ents (str) – BIDS subject/session entity string (e.g., “sub-01_ses-1”).

  • volspace (str, optional) – Template space name. Default is TEMPLATE_SPACE (MNI152NLin6Asym).

Returns:

Two paths: from-T1w_to-template and from-template_to-T1w transform files.

Return type:

list of str

xcp_d.ingression.utils.plot_bbreg(fixed_image, moving_image, contour, out_file='report.svg')[source]

Generate a boundary-based registration quality assurance figure.

Creates an SVG visualization comparing a fixed anatomical image with a moving functional image (typically a bold reference), with optional contour overlay to assess registration quality.

Parameters:

  • fixed_image (str) – Path to the fixed/reference anatomical image (typically T1w).

  • moving_image (str) – Path to the moving image (typically BOLD reference or SBRef).

  • contour (str or None) – Path to an image to use for contour overlay (typically ribbon.nii.gz), or None to skip contour visualization.

  • out_file (str, optional) – Path for the output SVG file. Default is ‘report.svg’.

Returns:

Path to the generated SVG file.

Return type:

str

xcp_d.ingression.utils.write_json(data, outfile)[source]

Write a dictionary to a JSON file.

Parameters:

  • data (dict) – Dictionary to serialize as JSON.

  • outfile (str) – Path to the output JSON file.

Returns:

Path to the written JSON file.

Return type:

str

xcp_d.ingression.utils.write_scans_tsv(copy_dictionary, subject_dir_bids, subses_ents, out_dir=None)[source]

Write a scans TSV mapping BIDS derivative filenames to their source paths.

Parameters:

  • copy_dictionary (dict) – Mapping from source file path to list of destination file paths. Values may be lists (for copy mapping) or single paths (e.g. morph outputs).

  • subject_dir_bids (str) – Path to subject (or subject/session) BIDS directory.

  • subses_ents (str) – BIDS entity string used in the output filename (e.g., “sub-01_ses-1”).

  • out_dir (str, optional) – Path to the output directory. If provided, the scans.tsv file will also be copied to {out_dir}/sourcedata/bids_conversion/.