Workflows module

Workflow for the management of super-resolution reconstruction pipeline inputs.

pymialsrtk.workflows.input_stage.create_input_stage(p_bids_dir, p_sub_ses, p_sub_path, p_use_manual_masks, p_masks_desc, p_masks_derivatives_dir, p_labels_derivatives_dir, p_skip_stacks_ordering, p_do_reconstruct_labels, p_stacks, p_do_srr_assessment, p_verbose, name='input_stage')[source]

Create a input management workflow for srr pipeline.

Parameters

name (string) – name of workflow (default: input_stage)
p_bids_dir (string) – Path to the bids directory
p_sub_ses (string) – String containing subject-session information.
p_use_manual_masks (boolean) – Whether manual masks are used
p_masks_desc (string) – BIDS description tag of masks to use (optional)
p_masks_derivatives_dir (string) – Path to the directory of the manual masks.
p_skip_stacks_ordering (boolean) – Whether stacks ordering should be skipped. If true, uses the order provided in p_stacks.
p_stacks (list of integer) – List of stack to be used in the reconstruction. The specified order is kept if skip_stacks_ordering is True.
p_do_srr_assessment (bool) – If super-resolution assessment should be done.

Outputs

outputnode.t2ws_filtered (list of filenames) – Low-resolution T2w images
outputnode.masks_filtered (list of filenames) – Low-resolution T2w masks
outputnode.stacks_order (list of ids) – Order in which the stacks should be processed
outputnode.report_image (filename) – Output PNG image for report
outputnode.motion_tsv (filename) – Output TSV file with results used to create report_image
outputnode.ground_truth (filename) – Ground truth image used for srr_assessment (optional, if `p_do_srr_assessment=True)

Example

>>> from pymialsrtk.pipelines.workflows import input_stage
>>> input_mgmt_stage = input_stage.create_input_stage(
        p_bids_dir="bids_data",
        p_sub_ses="sub-01_ses-1",
        p_sub_path="sub-01/ses-1/anat",
        p_use_manual_masks=False,
        p_skip_stacks_ordering=False,
        p_do_srr_assessment=False,
        name="input_mgmt_stage",
    )
>>> input_mgmt_stage.run()  

Module for the preprocessing stage of the super-resolution reconstruction pipeline.

pymialsrtk.workflows.preproc_stage.create_preproc_stage(p_skip_preprocessing=False, p_do_nlm_denoising=False, p_do_reconstruct_labels=False, p_verbose=False, name='preproc_stage')[source]

Create a SR preprocessing workflow.

Parameters

p_do_nlm_denoising (boolean) – Whether to proceed to non-local mean denoising (default: False)
p_do_reconstruct_labels (boolean) – Whether we are also reconstruction label maps. (default: False)
p_verbose (boolean) – Whether verbosity should be enabled (default False)
name (string) – name of workflow (default: “preproc_stage”)

Inputs

input_images (list of items which are a pathlike object or string representing a file) – Input T2w images
input_masks (list of items which are a pathlike object or string representing a file) – Input mask images

Outputs

output_images (list of items which are a pathlike object or string representing a file) – Processed images
output_masks (list of items which are a pathlike object or string representing a file) – Processed images
output_images_nlm (list of items which are a pathlike object or string representing a file) – Processed images with NLM denoising, required if p_do_nlm_denoising = True

Example

>>> from pymialsrtk.pipelines.workflows import preproc_stage as preproc
>>> preproc_stage = preproc.create_preproc_stage(p_do_nlm_denoising=False)
>>> preproc_stage.inputs.inputnode.input_images =
        ['sub-01_run-1_T2w.nii.gz',
         'sub-01_run-2_T2w.nii.gz']
>>> preproc_stage.inputs.inputnode.input_masks =
        ['sub-01_run-1_T2w_mask.nii.gz',
         'sub-01_run-2_T2w_mask.nii.gz']
>>> preproc_stage.inputs.inputnode.p_do_nlm_denoising = 'mask.nii'
>>> preproc_stage.run()  

Module for the registration stage of the super-resolution reconstruction pipeline.

pymialsrtk.workflows.registration_stage.create_registration_stage(p_do_nlm_denoising=False, p_skip_svr=False, p_sub_ses='', p_verbose=False, name='registration_stage')[source]

Create a a registration workflow, used as an optional stage in the preprocessing only pipeline.

Parameters

p_do_nlm_denoising (boolean) – Enable non-local means denoising (default: False)
p_skip_svr (boolean) – Skip slice-to-volume registration (default: False)
p_sub_ses (string) – String containing subject-session information.
name (string) – name of workflow (default: “registration_stage”)

Inputs

input_images (list of items which are a pathlike object or string representing a file) – Input low-resolution T2w images
input_images_nlm (list of items which are a pathlike object or string representing a file) – Input low-resolution denoised T2w images, Optional - only if p_do_nlm_denoising = True
input_masks (list of items which are a pathlike object or string representing a file) – Input mask images from the low-resolution T2w images
stacks_order (list of integer) – Order of stacks in the registration

Outputs

output_sdi (pathlike object or string representing a file) – SDI image
output_tranforms (list of items which are a pathlike object or string representing a file) – Estimated transformation parameters

Example

>>> from pymialsrtk.pipelines.workflows import registration_stage as reg
>>> registration_stage = reg.create_registration_stage(
        p_sub_ses=p_sub_ses,
    )
>>> registration_stage.inputs.input_images = [
        'sub-01_run-1_T2w.nii.gz',
        'sub-01_run-2_T2w.nii.gz'
    ]
>>> registration_stage.inputs.input_masks = [
        'sub-01_run-1_T2w.nii_mask.gz',
        'sub-01_run-2_T2w.nii_mask.gz'
    ]
>>> registration_stage.inputs.stacks_order = [2,1]
>>> registration_stage.run()  

Module for the reconstruction stage of the super-resolution reconstruction pipeline.

pymialsrtk.workflows.recon_stage.create_recon_stage(p_paramTV, p_use_manual_masks, p_do_multi_parameters=False, p_do_nlm_denoising=False, p_do_reconstruct_labels=False, p_do_refine_hr_mask=False, p_skip_svr=False, p_sub_ses='', p_verbose=False, name='recon_stage')[source]

Create a super-resolution reconstruction workflow.

Parameters

p_paramTV (dictionary) – Dictionary of TV parameters
p_use_manual_masks (boolean) – Whether masks were done manually.
p_do_nlm_denoising (boolean) – Whether to proceed to non-local mean denoising. (default: False)
p_do_multi_parameters (boolean) – Perform super-resolution reconstruction with a set of multiple parameters. (default: False)
p_do_reconstruct_labels (boolean) – Whether we are also reconstruction label maps. (default: False)
p_do_refine_hr_mask (boolean) – Whether to do high-resolution mask refinement. (default: False)
p_skip_svr (boolean) – Whether slice-to-volume registration (SVR) should be skipped. (default: False)
p_sub_ses (string) – String describing subject-session information (default: ‘’)
p_verbose (boolean) – Whether verbosity should be enabled (default: False)
name (string) – Name of workflow (default: “recon_stage”)

Inputs

input_images (list of items which are a pathlike object or string representing a file) – Input T2w images
input_images_nlm (list of items which are a pathlike object or string representing a file) – Input T2w images, required if p_do_nlm_denoising=True
input_masks (list of items which are a pathlike object or string representing a file) – Input mask images
stacks_order (list of integer) – Order of stacks in the reconstruction

Outputs

output_sr (pathlike object or string representing a file) – SR reconstructed image
output_sdi (pathlike object or string representing a file) – SDI image
output_hr_mask (pathlike object or string representing a file) – SRR mask
output_tranforms (list of items which are a pathlike object or string representing a file) – Estimated transformation parameters
outputnode.output_json_path (pathlike object or string representing a file) – Path to the json sidecar of the SR reconstruction
outputnode.output_sr_png (pathlike object or string representing a file) – Path to the PNG of the SR reconstruction
outputnode.output_TV_parameters (dictionary) – Parameters used for TV reconstruction

Example

>>> from pymialsrtk.pipelines.workflows import recon_stage as rec
>>> recon_stage = rec.create_preproc_stage(
        p_paramTV,
        p_use_manual_masks,
        p_do_nlm_denoising=False)
>>> recon_stage.inputs.inputnode.input_images =
        ['sub-01_run-1_T2w.nii.gz', 'sub-01_run-2_T2w.nii.gz']
>>> recon_stage.inputs.inputnode.input_masks =
        ['sub-01_run-1_T2w_mask.nii.gz', 'sub-01_run-2_T2w_mask.nii.gz']
>>> recon_stage.inputs.stacks_order = [2,1]
>>> recon_stage.run()  

Module for the high-resolution reconstruction stage of low-resolution labelmaps in the super-resolution reconstruction pipeline.

pymialsrtk.workflows.recon_labelmap_stage.create_recon_labelmap_stage(p_sub_ses, p_verbose=False, name='recon_labels_stage')[source]

Create a SR reconstruction workflow for tissue label maps.

Parameters

p_sub_ses (string) – String containing subject-session information for output formatting
p_verbose (boolean) – Whether verbosity should be enabled (default: False)
name (string) – Name of workflow (default: “recon_labels_stage”)

Inputs

input_labels (list of items which are a pathlike object or string representing a file) – Input LR label maps
input_masks (list of items which are a pathlike object or string representing a file) – Input mask images
input_transforms (list of items which are a pathlike object or string representing a file) – Input tranforms
input_reference (pathlike object or string representing a file) – Input HR reference image
label_ids (list of integer) – Label IDs to reconstruct
stacks_order (list of integer) – Order of stacks in the reconstruction

Outputs

output_labelmap (pathlike object or string representing a file) – HR labelmap

Example

>>> from pymialsrtk.pipelines.workflows import recon_labelmap_stage as rec_label
>>> recon_labels_stage = rec_label.create_recon_labelmap_stage(
        p_sub_ses=p_sub_ses,
        p_verbose=p_verbose
    )
>>> recon_labels_stage.inputs.input_labels = [
        'sub-01_run-1_labels.nii.gz',
        'sub-01_run-2_labels.nii.gz'
    ]
>>> recon_labels_stage.inputs.input_masks = [
        'sub-01_run-1_T2w.nii_mask.gz',
        'sub-01_run-2_T2w.nii_mask.gz'
    ]
>>> recon_labels_stage.inputs.input_transforms = [
        'sub-01_run-1_transforms.txt',
        'sub-01_run-2_transforms.txt'
    ]
>>> recon_labels_stage.inputs.input_reference = 'sub-01_desc-GT_T2w.nii.gz'
>>> recon_labels_stage.inputs.label_ids = 'sub-01_desc-GT_T2w.nii.gz'
>>> recon_labels_stage.inputs.stacks_order = [2,1]
>>> recon_labels_stage.run()  

Module for the assessment of the super-resolution reconstruction quality with a reference.

pymialsrtk.workflows.srr_assessment_stage.create_srr_assessment_stage(p_do_multi_parameters=False, p_do_reconstruct_labels=False, p_input_srtv_node=None, p_verbose=False, p_openmp_number_of_cores=1, name='srr_assessment_stage')[source]

Create an assessment workflow to compare a SR-reconstructed image and a reference target.

Parameters

name (string) – Name of workflow (default: “sr_assessment_stage”)
p_do_multi_parameters (boolean) – whether multiple SR are to be assessed with different TV parameters (default: False)
p_input_srtv_node (string) – when p_do_multi_parameters is set, name of the sourcenode from which metrics must be merged
p_openmp_number_of_cores (integer) – number of threads possible for ants registration (default : 1)

Inputs

input_reference_image (pathlike object or string representing a file) – Path to the ground truth image against which the SR will be evaluated.
input_reference_mask (pathlike object or string representing a file) – Path to the mask of the ground truth image.
input_reference_labelmap (pathlike object or string representing a file) – Path to the labelmap (tissue segmentation) of the ground truth image.
input_sr_image (pathlike object or string representing a file) – Path to the SR reconstructed image.
input_sdi_image (pathlike object or string representing a file) – Path to the SDI (interpolated image) used as input to the SR.
input_TV_parameters (dictionary) – Dictionary of parameters that were used for the TV reconstruction.

Outputs

outputnode.output_metrics (list of float) – List of output metrics

Example

>>> from pymialsrtk.pipelines.workflows import srr_assessment_stage as srr_assessment
>>> srr_eval = srr_assessment.create_srr_assessment_stage()
>>> srr_eval.inputs.input_reference_image = 'sub-01_desc-GT_T2w.nii.gz'
>>> srr_eval.inputs.input_reference_mask = 'sub-01_desc-GT_mask.nii.gz'
>>> srr_eval.inputs.input_reference_mask = 'sub-01_desc-GT_labels.nii.gz'
>>> srr_eval.inputs.input_sr_image = 'sub-01_id-1_rec-SR_T2w.nii.gz'
>>> srr_eval.inputs.input_sdi_image = 'sub-01_id-1_desc-SDI_T2w.nii.gz'
>>> srr_eval.inputs.input_TV_parameters = {
        'in_loop': '10',
        'in_deltat': '0.01',
        'in_lambda': '0.75',
        'in_bregman_loop': '3',
        'in_iter': '50',
        'in_step_scale': '1',
        'in_gamma': '1',
        'in_inner_thresh':
        '1e-05',
        'in_outer_thresh': '1e-06'
    }
>>> srr_eval.run()  

Workflow for the management of super-resolution reconstruction pipeline outputs.

pymialsrtk.workflows.output_stage.create_preproc_output_stage(p_sub_ses, p_sr_id, p_run_type, p_use_manual_masks, p_do_nlm_denoising=False, p_skip_stacks_ordering=False, p_do_registration=False, name='preproc_output_stage')[source]

Create an output management workflow for the preprocessing only pipeline.

Parameters

p_sub_ses (string) – String containing subject-session information for output formatting
p_sr_id (integer) – ID of the current run
p_run_type (“preprocessing” or “super resolution”) – Type of run
p_use_manual_masks (boolean) – Whether manual masks were used in the pipeline
p_do_nlm_denoising (boolean) – Enable non-local means denoising (default: False)
p_skip_stacks_ordering (boolean) – Skip stacks ordering (default: False) If disabled, report_image and motion_tsv are not generated
p_do_registration (boolean) – Whether registration is performed in the preprocessing pipeline
name (string) – name of workflow (default: “preproc_output_stage”)

Inputs

sub_ses (string) – String containing subject-session information for output formatting
sr_id (integer) – ID of the current run
stacks_order (list of integer) – Order of stacks in the registration (list of integer)
final_res_dir (pathlike object or string representing a file) – Output directory
run_type (“preprocessing” or “super resolution”) – Type of run
input_masks (list of items which are a pathlike object or string representing a file) – Input mask images from the low-resolution T2w images
input_images (list of items which are a pathlike object or string representing a file) – Input low-resolution T2w images
input_sdi (pathlike object or string representing a file) – Interpolated high resolution volume, obtained after slice-to-volume registration (SVR) Optional - only if p_do_registration = True
input_transforms (list of items which are a pathlike object or string representing a file) – Transforms obtained after SVR Optional - only if p_do_registration = True
report_image (pathlike object or string representing a file) – Report image obtained from the StacksOrdering module Optional - only if p_skip_stacks_ordering = False
motion_tsv (pathlike object or string representing a file) – Motion index obtained from the StacksOrdering module Optional - only if p_skip_stacks_ordering = False
input_images_nlm (list of items which are a pathlike object or string representing a file) – Input low-resolution denoised T2w images, Optional - only if p_do_nlm_denoising = True

pymialsrtk.workflows.output_stage.create_srr_output_stage(p_sub_ses, p_sr_id, p_run_type, p_keep_all_outputs=False, p_use_manual_masks=False, p_do_nlm_denoising=False, p_do_reconstruct_labels=False, p_do_srr_assessment=False, p_skip_stacks_ordering=False, p_do_multi_parameters=False, p_subject=None, p_session=None, p_stacks=None, p_output_dir=None, p_run_start_time=None, p_run_elapsed_time=None, p_skip_svr=None, p_do_anat_orientation=None, p_do_refine_hr_mask=None, p_masks_derivatives_dir=None, p_openmp_number_of_cores=None, p_nipype_number_of_cores=None, name='srr_output_stage')[source]

Create a output management workflow for the super-resolution reconstruction pipeline.

Parameters

p_sub_ses – String containing subject-session information for output formatting
p_sr_id – ID of the current run
p_run_type – Type of run (preprocessing/super resolution/ …)
p_keep_all_outputs – Whether intermediate outputs must be issues
p_use_manual_masks – Whether manual masks were used in the pipeline
p_do_nlm_denoising (bool) – Enable non-local means denoising (default: False)
p_do_reconstruct_labels (bool) – Enable the reconstruction of labelmaps
p_do_srr_assessment (bool) – Enables output of srr assessment stage
p_skip_stacks_ordering (bool) – Skip stacks ordering (default: False) If disabled, report_image and motion_tsv are not generated
p_do_multi_parameters (bool) – Whether recon_stage was performed in a multi-TV mode
name (str) – name of workflow (default: “srr_output_stage”)

Inputs

stacks_order (list of integer) – Order of stacks in the registration (list of integer)
use_manual_masks (bool) – Whether manual masks were used in the pipeline
final_res_dir (pathlike object or string representing a file) – Output directory
input_masks (list of items which are a pathlike object or string representing a file) – Input mask images from the low-resolution T2w images
input_images (list of items which are a pathlike object or string representing a file) – Input low-resolution T2w images
input_transforms (list of items which are a pathlike object or string representing a file) – Transforms obtained after SVR
input_sdi (pathlike object or string representing a file) – Interpolated high resolution volume, obtained after slice-to-volume registration (SVR)
input_sr (pathlike object or string representing a file) – High resolution volume, obtained after the super- resolution (SR) reconstruction from the SDI volume.
input_hr_mask (pathlike object or string representing a file) – Brain mask from the high-resolution reconstructed volume.
input_json_path (pathlike object or string representing a file) – Path to the JSON file describing the parameters used in the SR reconstruction.
input_sr_png (pathlike object or string representing a file) – PNG image summarizing the SR reconstruction.
report_image (pathlike object or string representing a file) – Report image obtained from the StacksOrdering module Optional - only if p_skip_stacks_ordering = False
motion_tsv (pathlike object or string representing a file) – Motion index obtained from the StacksOrdering module Optional - only if p_skip_stacks_ordering = False
input_images_nlm (pathlike object or string representing a file) – Input low-resolution denoised T2w images Optional - only if p_do_nlm_denoising = True