qsiprep.workflows.dwi.merge module

Merge and denoise dwi images.

Merge and denoise dwi images

qsiprep.workflows.dwi.merge.closest_odd(x)

qsiprep.workflows.dwi.merge.gen_denoising_boilerplate(do_biascorr)

Generate a methods boilerplate for the denoising workflow.

do_biascorr is the resolved decision for this output, not the --dwi-biascorrect mode: under auto the mode alone cannot say whether N4 actually ran, so reading the config here would state the wrong thing.

qsiprep.workflows.dwi.merge.get_acq_parameters_df(dwi_file_list, metadata_lookup)

Tabulate each file’s acquisition parameters.

metadata_lookup maps a path to its sidecar metadata (usually PreprocUnit.metadata_for, so nothing is re-read from disk); the NIfTI header still supplies image-derived fields like the volume count.

qsiprep.workflows.dwi.merge.get_merged_parameter(parameter_df, parameter_name, selection_mode='all')

Return a single parameter from a parameter dataframe.

qsiprep.workflows.dwi.merge.init_dwi_denoising_wf(source_file, partial_fourier, phase_encoding_direction, n_volumes, use_phase, name='denoise_wf')

Build a workflow to denoise a DWI series.

Parameters:

• source_file (str) – path to the original dwi file

• partial_fourier (float) – fraction of k-space acquired

• phase_encoding_direction (str) – direction of phase encoding

• n_volumes (int) – number of volumes in the DWI series. Used to determine the window size for denoising if dwidenoise is used and the ‘auto’ option is selected.

• use_phase (bool) – True if phase data are available for the DWI scan. If True, and denoise_method is dwidenoise or dwidenoise2, then the denoiser will be run on the complex-valued data. If denoise_method is svht, then svht_denoise will rotate the magnitude and phase data onto the real axis before denoising.

• name (str, optional) – name of the workflow

Inputs:

• dwi_file – path to the dwi file

• bval_file – path to the bval file

• bvec_file – path to the bvec file

• dwi_phase_file – path to the dwi phase file (optional)

Outputs:

• dwi_file – path to the denoised dwi file

• bval_file – path to the denoised bval file

• bvec_file – path to the denoised bvec file

• noise_image – path to the noise image

• confounds – path to the confounds file

qsiprep.workflows.dwi.merge.init_dwi_series_denoise_wf(dwi_file, metadata, phase_file=None, orientation='LPS', name=None)

Build a workflow that conforms and denoises one raw DWI series.

A series may belong to several preprocessing units (virtual acquisitions list it under more than one MultipartID), and denoising depends only on the series itself, so this workflow is built once per raw file at the subject level and its outputs are shared by every unit that uses the file.

(Source code)

Parameters:

• dwi_file (str) – the raw DWI series, in its original BIDS directory

• metadata (dict) – the sidecar metadata of dwi_file (PreprocUnit.metadata_for)

• phase_file (str, optional) – the part-phase companion of dwi_file, when the acquisition is complex-valued and the phase has not been ignored

• orientation (str, optional) – Orientation the series is conformed to (‘LPS’ or ‘LAS’).

• name (str, optional) – Name of workflow. Derived from the file name when omitted.

Outputs:

• dwi_file – the series, conformed and denoised

• bval_file – bvals of the series

• bvec_file – bvecs of the series, conformed

• raw_dwi_file – the series, conformed but not denoised

• noise_image – noise image estimated by the denoiser (when one ran)

• confounds – per-volume denoising/unringing confounds (when any step ran)

• validation_report – HTML segment reporting header problems found while conforming

qsiprep.workflows.dwi.merge.init_merge_dwis_wf(unit, raw_dwi_files, orientation, source_file, calculate_qc=False, phase_id='same', name='merge_dwis_wf')

Build a workflow that merges already-denoised DWI series.

The series arrive conformed and denoised from init_dwi_series_denoise_wf(), one list entry per file in raw_dwi_files and in the same order.

(Source code, png, svg, pdf)

Parameters:

• unit (PreprocUnit) – the unit these series belong to; sidecar metadata comes from its records, so the layout is never re-read

• raw_dwi_files (list) – list of raw (in their original BIDS directory) dwi nifti files

• orientation (str) – Orientation the series were conformed to (‘LPS’ or ‘LAS’). Selects the bvec convention used for QC (‘DIPY’ for ‘LPS’, ‘FSL’ otherwise).

• source_file (str) – Source file whose name (without extension) is used as the prefix of the merged outputs.

• calculate_qc (bool, optional) – Whether to calculate DSI Studio QC metrics on the merged raw data. Default is False.

• phase_id (str, optional) – Label for the distortion group, used in the methods boilerplate. Default is 'same'.

• name (str, optional) – Name of workflow (default: merge_dwis_wf)

Inputs:

• dwi_files – conformed, denoised series, one per entry of raw_dwi_files

• bval_files – bvals of each series

• bvec_files – conformed bvecs of each series

• raw_dwi_files – conformed, not denoised series

• noise_images – noise image of each series

• denoising_confounds – denoising confounds of each series

• validation_reports – conformation report of each series

Outputs:

• merged_image – dwi series, conformed, denoised if requested

• merged_raw_image – dwi series, conformed, raw

• merged_bval – bvals from merged images

• merged_bvec – bvecs from merged images

• merged_json – JSON file containing slice timings for slice2vol

• noise_images – image(s) created by dwidenoise

• denoising_confounds – confounds from denoising, aligned to the merged series

• original_files – names of the original files for each volume

• qc_summary – DSI Studio QC text file

• validation_reports – the conformation reports, passed through