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.

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

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

  • motion_filter_type (a string or None)

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

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. Maps to a command-line argument: %s (position: 0).

  • out_file (a pathlike object or string representing a file) – Output file. 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.

  • 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’ or ‘GIFTI’) – FSL output type.

Outputs:

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

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

Bases: SimpleInterface

Plot a parcellated (.pscalar.nii) CIFTI file.

Mandatory Inputs:

  • cortical_atlases (a list of items which are a string) – Atlases to select from ‘labels’.

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

  • labels (a list of items which are a string) – Labels for the CIFTI files.

Optional Inputs:

  • base_desc (a string) – Base description for the output file. (Nipype default value: "")

  • lh_underlay (a pathlike object or string representing an existing file) – Left hemisphere underlay.

  • out_file (a pathlike object or string representing a file) – Output file. (Nipype default value: plot.svg)

  • rh_underlay (a pathlike object or string representing an existing file) – Right hemisphere underlay.

  • vmax (a float) – Maximum value for the colormap. (Nipype default value: 0)

  • vmin (a float) – Minimum value for the colormap. (Nipype default value: 0)

Outputs:

  • desc (a string) – Description of the output file.

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

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

Bases: SimpleInterface

Plot a dense (.dscalar.nii) CIFTI file.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – CIFTI file to plot.

Optional Inputs:

  • base_desc (a string) – Base description for the output file. (Nipype default value: "")

  • lh_underlay (a pathlike object or string representing an existing file) – Left hemisphere underlay.

  • rh_underlay (a pathlike object or string representing an existing file) – Right hemisphere underlay.

Outputs:

  • desc (a string) – Description of the output file.

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

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

Bases: SimpleInterface

Plot a NIfTI file.

Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – CIFTI file to plot.

  • name_source (a pathlike object or string representing a file) – File to use as the name source.

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.bold_file = rawbold
qcplots.inputs.TR = TR
qcplots.inputs.temporal_mask = temporalmask
qcplots.inputs.mask_file = mask
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.

  • 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.

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

Optional Inputs:

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

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

Outputs:

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

  • 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:

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

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

  • 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 from the 2.5th percentile to the 97.5th percentile. If True, then the BOLD data will be z-scored and the color limits will be -2 and 2.

Optional Inputs:

  • TR (a float) – Repetition time. (Nipype default value: 1)

  • 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.

  • temporal_mask (a pathlike object or string representing an existing file or a _Undefined or None) – TSV file with temporal mask.

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’ or ‘GIFTI’) – 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) – Concatenated PNG files.

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