petprep_hmc

petprep_hmc.bids module

Helpers for handling BIDS-like neuroimaging structures.

exception petprep_hmc.bids.BIDSError(message, bids_root)

Bases: ValueError

exception petprep_hmc.bids.BIDSWarning

Bases: RuntimeWarning

petprep_hmc.bids.check_pipeline_version(cvers, data_desc)

Search for existing BIDS pipeline output and compares against current pipeline version.

Parameters:

• cvers (str) – Current pipeline version

• data_desc (str or os.PathLike) – Path to pipeline output’s dataset_description.json

Examples

>>> check_pipeline_version('1.1.1rc5', 'sample_dataset_description.json') is None
True
>>> check_pipeline_version('1.1.1rc5+129.gbe0e5158', 'sample_dataset_description.json')
>>> check_pipeline_version('1.2', 'sample_dataset_description.json')  
'Previous output generated ...'

Returns:

message – A warning string if there is a difference between versions, otherwise None.

Return type:

str or None

petprep_hmc.bids.collect_data(bids_dir, participant_label, session_id=Query.OPTIONAL, task=None, echo=None, bids_validate=True, bids_filters=None)

Uses pybids to retrieve the input data for a given participant

Parameters:

• bids_dir (str or bids.layout.BIDSLayout) – The BIDS directory

• participant_label (str) – The participant identifier

• session_id (str, None, or bids.layout.Query) – The session identifier. By default, all sessions will be used.

• task (str or None) – The task identifier (for BOLD queries)

• echo (int or None) – The echo identifier (for BOLD queries)

• bids_validate (bool) – Whether the bids_dir is validated upon initialization

• bids_filters (dict or None) – Custom filters to alter default queries

Examples

>>> bids_root, _ = collect_data(str(datadir / 'ds054'), '100185',
...                             bids_validate=False)
>>> bids_root['fmap']  
['.../ds054/sub-100185/fmap/sub-100185_magnitude1.nii.gz', '.../ds054/sub-100185/fmap/sub-100185_magnitude2.nii.gz', '.../ds054/sub-100185/fmap/sub-100185_phasediff.nii.gz']
>>> bids_root['bold']  
['.../ds054/sub-100185/func/sub-100185_task-machinegame_run-01_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-02_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-03_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-04_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-05_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-06_bold.nii.gz']
>>> bids_root['sbref']  
['.../ds054/sub-100185/func/sub-100185_task-machinegame_run-01_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-02_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-03_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-04_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-05_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-06_sbref.nii.gz']
>>> bids_root['t1w']  
['.../ds054/sub-100185/anat/sub-100185_T1w.nii.gz']
>>> bids_root['t2w']  
[]
>>> bids_root, _ = collect_data(str(datadir / 'ds051'), '01',
...                             bids_validate=False,
...                             bids_filters={'t1w':{'run': 1, 'session': None}})
>>> bids_root['t1w']  
['.../ds051/sub-01/anat/sub-01_run-01_T1w.nii.gz']

petprep_hmc.bids.collect_participants(bids_dir, participant_label=None, strict=False, bids_validate=True)

List the participants under the BIDS root and checks that participants designated with the participant_label argument exist in that folder. Returns the list of participants to be finally processed. Requesting all subjects in a BIDS directory root:

Examples

>>> collect_participants(str(datadir / 'ds114'), bids_validate=False)
['01', '02', '03', '04', '05', '06', '07', '08', '09', '10']

Requesting two subjects, given their IDs:

>>> collect_participants(str(datadir / 'ds114'), participant_label=['02', '04'],
...                      bids_validate=False)
['02', '04']

Requesting two subjects, given their IDs (works with ‘sub-’ prefixes):

>>> collect_participants(str(datadir / 'ds114'), participant_label=['sub-02', 'sub-04'],
...                      bids_validate=False)
['02', '04']

Requesting two subjects, but one does not exist:

>>> collect_participants(str(datadir / 'ds114'), participant_label=['02', '14'],
...                      bids_validate=False)
['02']
>>> collect_participants(
...     str(datadir / 'ds114'), participant_label=['02', '14'],
...     strict=True, bids_validate=False)  
Traceback (most recent call last):
BIDSError:
...

petprep_hmc.bids.get_metadata_for_nifti(in_file, bids_dir=None, validate=True)

Fetch metadata for a given NIfTI file.

Examples

>>> metadata = get_metadata_for_nifti(
...     datadir / 'ds054' / 'sub-100185' / 'fmap' / 'sub-100185_phasediff.nii.gz',
...     validate=False)
>>> metadata['Manufacturer']
'SIEMENS'

petprep_hmc.bids.group_multiecho(bold_sess)

Multiplex multi-echo EPIs into arrays.

Dual-echo is a special case of multi-echo, which is treated as single-echo data.

Examples

>>> bold_sess = ["sub-01_task-rest_echo-1_run-01_bold.nii.gz",
...              "sub-01_task-rest_echo-2_run-01_bold.nii.gz",
...              "sub-01_task-rest_echo-1_run-02_bold.nii.gz",
...              "sub-01_task-rest_echo-2_run-02_bold.nii.gz",
...              "sub-01_task-rest_echo-3_run-02_bold.nii.gz",
...              "sub-01_task-rest_run-03_bold.nii.gz"]
>>> group_multiecho(bold_sess)  
['sub-01_task-rest_echo-1_run-01_bold.nii.gz',
 'sub-01_task-rest_echo-2_run-01_bold.nii.gz',
['sub-01_task-rest_echo-1_run-02_bold.nii.gz',
 'sub-01_task-rest_echo-2_run-02_bold.nii.gz',
 'sub-01_task-rest_echo-3_run-02_bold.nii.gz'],
 'sub-01_task-rest_run-03_bold.nii.gz']

>>> bold_sess.insert(2, "sub-01_task-rest_echo-3_run-01_bold.nii.gz")
>>> group_multiecho(bold_sess)  
[['sub-01_task-rest_echo-1_run-01_bold.nii.gz',
  'sub-01_task-rest_echo-2_run-01_bold.nii.gz',
  'sub-01_task-rest_echo-3_run-01_bold.nii.gz'],
 ['sub-01_task-rest_echo-1_run-02_bold.nii.gz',
  'sub-01_task-rest_echo-2_run-02_bold.nii.gz',
  'sub-01_task-rest_echo-3_run-02_bold.nii.gz'],
  'sub-01_task-rest_run-03_bold.nii.gz']

>>> bold_sess += ["sub-01_task-beh_echo-1_run-01_bold.nii.gz",
...               "sub-01_task-beh_echo-2_run-01_bold.nii.gz",
...               "sub-01_task-beh_echo-1_run-02_bold.nii.gz",
...               "sub-01_task-beh_echo-2_run-02_bold.nii.gz",
...               "sub-01_task-beh_echo-3_run-02_bold.nii.gz",
...               "sub-01_task-beh_run-03_bold.nii.gz"]
>>> group_multiecho(bold_sess)  
[['sub-01_task-rest_echo-1_run-01_bold.nii.gz',
  'sub-01_task-rest_echo-2_run-01_bold.nii.gz',
  'sub-01_task-rest_echo-3_run-01_bold.nii.gz'],
 ['sub-01_task-rest_echo-1_run-02_bold.nii.gz',
  'sub-01_task-rest_echo-2_run-02_bold.nii.gz',
  'sub-01_task-rest_echo-3_run-02_bold.nii.gz'],
  'sub-01_task-rest_run-03_bold.nii.gz',
  'sub-01_task-beh_echo-1_run-01_bold.nii.gz',
  'sub-01_task-beh_echo-2_run-01_bold.nii.gz',
 ['sub-01_task-beh_echo-1_run-02_bold.nii.gz',
  'sub-01_task-beh_echo-2_run-02_bold.nii.gz',
  'sub-01_task-beh_echo-3_run-02_bold.nii.gz'],
  'sub-01_task-beh_run-03_bold.nii.gz']

Some tests from https://neurostars.org/t/fmriprep-from-singularity-unboundlocalerror/3299/7

>>> bold_sess = ['sub-01_task-AudLoc_echo-1_bold.nii',
...              'sub-01_task-AudLoc_echo-2_bold.nii',
...              'sub-01_task-FJT_echo-1_bold.nii',
...              'sub-01_task-FJT_echo-2_bold.nii',
...              'sub-01_task-LDT_echo-1_bold.nii',
...              'sub-01_task-LDT_echo-2_bold.nii',
...              'sub-01_task-MotLoc_echo-1_bold.nii',
...              'sub-01_task-MotLoc_echo-2_bold.nii']
>>> group_multiecho(bold_sess) == bold_sess
True

>>> bold_sess += ['sub-01_task-MotLoc_echo-3_bold.nii']
>>> groups = group_multiecho(bold_sess)
>>> len(groups[:-1])
6
>>> [isinstance(g, list) for g in groups]
[False, False, False, False, False, False, True]
>>> len(groups[-1])
3

petprep_hmc.bids.relative_to_root(path)

Calculate the BIDS root folder given one file path’s.

Examples

>>> str(relative_to_root(
...     "/sub-03/sourcedata/sub-01/anat/sub-01_T1.nii.gz"
... ))
'sub-01/anat/sub-01_T1.nii.gz'

>>> str(relative_to_root(
...     "/sub-03/anat/sourcedata/sub-01/ses-preop/anat/sub-01_ses-preop_T1.nii.gz"
... ))
'sub-01/ses-preop/anat/sub-01_ses-preop_T1.nii.gz'

>>> str(relative_to_root(
...     "sub-01/anat/sub-01_T1.nii.gz"
... ))
'sub-01/anat/sub-01_T1.nii.gz'

>>> str(relative_to_root("anat/sub-01_T1.nii.gz"))
'anat/sub-01_T1.nii.gz'

petprep_hmc.utils module

petprep_hmc.utils.plot_mc_dynamic_pet(pet_orig, pet_mc, sub_out_dir, file_prefix)

Creates a dynamic GIF of the PET images before and after motion correction, saves to sub_out_dir.

Parameters:

• pet_orig (str) – original PET NifTi image

• pet_mc (str) – motion corrected PET NifTi image

• sub_out_dir (str) – path to output directory, typically located in derivatives/petprep_hmc/sub-*

• file_prefix (str) – result of regex match on r”_pet_file_(.*?)_pet”

run

run.add_mc_ext(in_file)

Function to add the mc extension to the list of file names.

:param in_file : file name to be updated :type in_file : list of file names

: return mc_list : list of updated file names with mc extension : rtype mc_list : list

run.check_fsl_installed()

run.combine_hmc_outputs(translations, rot_angles, rotation_translation_matrix, in_file)

Function to combine the outputs of the hmc workflow.

:parameter translations : list of estimated translations across frames :parameter rot_angles : list of estimated rotational angles across frames :parameter rotation_translation_matrix : list of estimated rotation translation matrices across frames :parameter in_file : list of frames to be used in the hmc workflow

Returns:

Output path to confounds file for head motion correction

Return type:

str

run.display_motion_correction_html(file_prefix, sub_out_dir)

Load and display motion correction figures based on config settings. Then creates an HTML report at sub_out_dir as {file_prefix}_report.html

run.get_min_frame(json_file, mc_start_time)

Function to extract the frame number after mc_start_time (default=120) seconds of mid frames of dynamic PET data to be used with motion correction

:param json_file : json file containing the frame length and duration of the dynamic PET data :type json_file : str

:return min_frame : minimum frame to use for the motion correction (first frame after 2 min)

run.init_petprep_hmc_wf(subjects, sessions_to_exclude=[])

run.init_single_subject_wf(subject_id, sessions_to_exclude=[])

run.load_config(filepath)

Load a YAML configuration file. :param filepath: str, path to the YAML file :return: dict, parsed YAML data

run.lta2mat(in_file)

Function to convert the lta file to the fsl format (.mat).

:param in_file : list of lta files to be converted :type in_file : list :return mat_list : list of mat files :rtype mat_list : list

run.main(args)

Main function to run the PETPrep HMC workflow.

• Checks whether BIDS directory exists and instantiates BIDSLayout.

• Checks whether FreeSurfer license is valid.

• Checks whether FSL is installed.

• Gets all PET files.

• Checks to see if any subjects are excluded from the HMC workflow.

• Collects list of all sessions.

• Checks to see if any sessions are excluded from the HMC workflow.

• Creates derivatives directories.

• Runs workflow.

• Loops through directories and stores according to PET-BIDS specification.

• Plots with and without motion correction.

• Creates HTML report.

• Removes temp outputs.

run.plot_motion_outputs(in_file)

Function to plot estimated motion data

:in_file : list of estimated motion data :type in_file : list

:return : Plots of estimated motion data :rtype : png

run.run_group_level(args)

Aggregate confounds files and generate a group report.

run.update_list_frames(in_file, min_frame)

Update the list of frames to be used in the HMC workflow.

Parameters:

• in_file (list) – list of frames

• min_frame (int) – minimum frame to use for the analysis (first frame after 2 min)

Returns:

list of updated frames to be used in the HMC workflow

Return type:

list

run.update_list_transforms(in_file, min_frame)

Update the list of transforms to be used in the HMC workflow.

Parameters:

• in_file (list) – List of transforms.

• min_frame (int) – Minimum frame to use for the analysis (first frame after 2 min).

Returns:

List of updated transforms to be used in the HMC workflow.

Return type:

list

run.write_itk_transforms(mat_list, out_file)

Write ITK transform file from a list of FSL matrices.