xcp_d.interfaces.plotting module

Plotting interfaces.

class xcp_d.interfaces.plotting.AnatomicalPlot(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Python class to plot x,y, and z of image data.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Plot image.

Outputs:

out_file (a pathlike object or string representing an existing file) – Out image.

class xcp_d.interfaces.plotting.CensoringPlot(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Generate a censoring figure.

This is a line plot showing both the raw and filtered framewise displacement time series, with vertical lines/bands indicating volumes removed by the post-processing workflow.

Mandatory Inputs:

  • TR (a float) – Repetition Time.

  • dummy_scans (an integer) – Dummy time to drop.

  • fd_thresh (a float) – Framewise displacement threshold.

  • filtered_motion (a pathlike object or string representing an existing file) – Filtered motion file.

  • fmriprep_confounds_file (a pathlike object or string representing an existing file) – FMRIPrep confounds file.

  • head_radius (a float) – Head radius for FD calculation.

  • motion_filter_type (a string or None)

  • temporal_mask (a pathlike object or string representing an existing file) – Temporal mask.

Outputs:

out_file (a pathlike object or string representing an existing file) – Censoring plot.

class xcp_d.interfaces.plotting.PNGAppend(**inputs)[source]

Bases: FSLCommand

Wrapped executable: pngappend.

Run pngappend.

Notes

pngappend - append PNG files horizontally and/or vertically into a new PNG (or GIF) file

Usage: pngappend <input 1> <+|-> [n] <input 2> [<+|-> [n] <input n>] output>

  • appends horizontally,

  • appends vertically (i.e. works like a linebreak)

[n] number ofgap pixels note that files with .gif extension will be input/output in GIF format

Mandatory Inputs:

  • in_files (a list of items which are a pathlike object or string representing an existing file) – List of files to process.

  • out_file (a pathlike object or string representing a file) – Output file.

Optional Inputs:

  • args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

  • environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

  • output_type (‘NIFTI’ or ‘NIFTI_PAIR’ or ‘NIFTI_GZ’ or ‘NIFTI_PAIR_GZ’) – FSL output type.

Outputs:

out_file (a pathlike object or string representing an existing file) – Output file.

class xcp_d.interfaces.plotting.QCPlots(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Generate pre- and post-processing quality control (QC) figures.

Examples

>>> from tempfile import TemporaryDirectory
>>> tmpdir = TemporaryDirectory()
>>> os.chdir(tmpdir.name)
.. doctest::
qcplots = QCPlots()
qcplots.inputs.cleaned_file = datafile
qcplots.inputs.name_source = rawbold
qcplots.inputs.bold_file = rawbold
qcplots.inputs.TR = TR
qcplots.inputs.temporal_mask = temporalmask
qcplots.inputs.mask_file = mask
qcplots.inputs.dummy_scans = dummy_scans
qcplots.run()
.. testcleanup::
>>> tmpdir.cleanup()
Mandatory Inputs:

  • TR (a float) – Repetition Time.

  • bold_file (a pathlike object or string representing an existing file) – Preprocessed BOLD file, after dummy scan removal. Used in carpet plot.

  • cleaned_file (a pathlike object or string representing an existing file) – Processed file, after denoising and censoring.

  • dummy_scans (an integer) – Dummy time to drop.

  • fmriprep_confounds_file (a pathlike object or string representing an existing file) – FMRIPrep confounds file, after dummy scans removal.

  • head_radius (a float) – Head radius for FD calculation.

  • mask_file (a pathlike object or string representing an existing file or None) – Mask file from nifti. May be None, for CIFTI processing.

  • name_source (a pathlike object or string representing a file) – Preprocessed BOLD file. Used to find files. In the case of the concatenation workflow, this may be a nonexistent file (i.e., the preprocessed BOLD file, with the run entity removed).

  • temporal_mask (a pathlike object or string representing an existing file) – Temporal mask.

Optional Inputs:

  • anat_brainmask (a pathlike object or string representing an existing file) – Mask in T1W.

  • bold2T1w_mask (a pathlike object or string representing an existing file) – Bold mask in MNI.

  • bold2temp_mask (a pathlike object or string representing an existing file) – Bold mask in T1W.

  • seg_file (a pathlike object or string representing an existing file) – Seg file for nifti.

  • template_mask (a pathlike object or string representing an existing file) – Template mask.

Outputs:

  • clean_qcplot (a pathlike object or string representing an existing file) – Qc plot after regression.

  • qc_file (a pathlike object or string representing an existing file) – Qc file in tsv.

  • raw_qcplot (a pathlike object or string representing an existing file) – Qc plot before regression.

class xcp_d.interfaces.plotting.QCPlotsES(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Plot fd, dvars, and carpet plots of the bold data before and after regression/filtering.

This is essentially equivalent to the QCPlots (which are paired pre- and post-processing FMRIPlots), but adapted for the executive summary.

It takes in the data that’s regressed, the data that’s filtered and regressed, as well as the segmentation files, TR, FD, bold_mask and unprocessed data.

It outputs the .SVG files before after processing has taken place.

Mandatory Inputs:

  • filtered_motion (a pathlike object or string representing an existing file) – TSV file with filtered motion parameters.

  • interpolated_filtered_bold (a pathlike object or string representing an existing file) – Data after filtering, interpolation, etc. This is not plotted.

  • preprocessed_bold (a pathlike object or string representing an existing file) – Preprocessed BOLD file, after mean-centering and detrending using only the low-motion volumes.

  • standardize (a boolean) – Whether to standardize the data or not. If False, then the preferred DCAN version of the plot will be generated, where the BOLD data are not rescaled, and the carpet plot has color limits of -600 and 600. If True, then the BOLD data will be z-scored and the color limits will be -2 and 2.

  • uncensored_denoised_bold (a pathlike object or string representing an existing file) – Data after regression and interpolation, but not filtering.The preprocessed BOLD data are censored, mean-centered, detrended, and denoised to get the betas, and then the full, uncensored preprocessed BOLD data are denoised using those betas.

Optional Inputs:

  • TR (a float) – Repetition time.

  • mask (a pathlike object or string representing an existing file) – Bold mask.

  • run_index (a list of items which are an integer or a _Undefined or None) – An index indicating splits between runs, for concatenated data. If not Undefined, this should be a list of integers, indicating the volumes.

  • seg_data (a pathlike object or string representing an existing file) – Segmentation file.

Outputs:

  • after_process (a pathlike object or string representing an existing file) – .SVG file after processing.

  • before_process (a pathlike object or string representing an existing file) – .SVG file before processing.

class xcp_d.interfaces.plotting.SlicesDir(**inputs)[source]

Bases: FSLCommand

Wrapped executable: slicesdir.

Run slicesdir.

Notes

Usage: slicesdir [-o] [-p <image>] [-e <thr>] [-S] <filelist> -o : filelist is pairs ( <underlying> <red-outline> ) of images -p <image> : use <image> as red-outline image on top of all images in <filelist> -e <thr> : use the specified threshold for edges (if >0 use this proportion of max-min,

if <0, use the absolute value)

-S

: output every second axial slice rather than just 9 ortho slices

Mandatory Inputs:

in_files (a list of items which are a pathlike object or string representing an existing file) – List of files to process. Maps to a command-line argument: %s (position: -1).

Optional Inputs:

  • args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

  • edge_threshold (a float) – Use the specified threshold for edges (if >0 use this proportion of max-min, if <0, use the absolute value). Maps to a command-line argument: -e %.03f (position: 2).

  • environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

  • is_pairs (a boolean) – Filelist is pairs ( <underlying> <red-outline> ) of images. Maps to a command-line argument: -o (position: 0).

  • out_extension (‘.gif’ or ‘.png’ or ‘.svg’) – Convenience parameter to let xcp_d select the extension. (Nipype default value: .gif)

  • outline_image (a pathlike object or string representing an existing file) – Use <image> as red-outline image on top of all images in <filelist>. Maps to a command-line argument: -p %s (position: 1).

  • output_odd_axials (a boolean) – Output every second axial slice rather than just 9 ortho slices. Maps to a command-line argument: -S (position: 3).

  • output_type (‘NIFTI’ or ‘NIFTI_PAIR’ or ‘NIFTI_GZ’ or ‘NIFTI_PAIR_GZ’) – FSL output type.

Outputs:

  • out_dir (a pathlike object or string representing an existing directory) – Output directory.

  • out_files (a list of items which are a pathlike object or string representing an existing file) – List of generated PNG files.