niworkflows.interfaces.workbench module

This module provides interfaces for workbench surface commands.

class niworkflows.interfaces.workbench.MetricDilate(**inputs)[source]

Bases: WBCommand, OpenMPCommandMixin

Wrapped executable: wb_command -metric-dilate.

Dilate a metric file on a surface.

For all data values designated as bad, if they neighbor a good value or are within the specified distance of a good value in the same kind of model, replace the value with a distance weighted average of nearby good values, otherwise set the value to zero. If -nearest is specified, it will use the value from the closest good value within range instead of a weighted average. When the input file contains label data, nearest dilation is used on the surface, and weighted popularity is used in the volume.

The -corrected-areas options are intended for dilating on group average surfaces, but it is only an approximate correction for the reduction of structure in a group average surface.

If -bad-vertex-roi is specified, all values, including those with value zero, are good, except for locations with a positive value in the ROI. If it is not specified, only values equal to zero are bad.

Mandatory Inputs:

  • distance (a float) – Distance in mm to dilate. Maps to a command-line argument: %f (position: 2).

  • in_file (a pathlike object or string representing an existing file) – The metric to dilate. Maps to a command-line argument: %s (position: 0).

  • surf_file (a pathlike object or string representing an existing file) – The surface to compute on. 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.

  • bad_vertex_roi_file (a pathlike object or string representing a file) – Metric file, positive values denote vertices to have their values replaced. Maps to a command-line argument: -bad-vertex-roi %s (position: 4).

  • column (an integer) – The column number. Maps to a command-line argument: -column %d (position: 6).

  • corrected_areas (a pathlike object or string representing a file) – Vertex areas to use instead of computing them from the surface. Maps to a command-line argument: -corrected-areas %s (position: 10).

  • data_roi_file (a pathlike object or string representing a file) – Metric file, positive values denote vertices that have data. Maps to a command-line argument: -data-roi %s (position: 5).

  • 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: {})

  • exponent (a float) – Exponent n to use in (area / (distance ^ n)) as the weighting function (default 6). Maps to a command-line argument: -exponent %f (position: 9).

  • legacy_cutoff (a boolean) – Use the v1.3.2 method of choosing how many vertices to use when calculating the dilated value with weighted method. Maps to a command-line argument: -legacy-cutoff (position: 11).

  • linear (a boolean) – Fill in values with linear interpolation along strongest gradient. Maps to a command-line argument: -linear (position: 8).

  • nearest (a boolean) – Use the nearest good value instead of a weighted average. Maps to a command-line argument: -nearest (position: 7).

  • num_threads (an integer) – Allows for specifying more threads.

  • out_file (a pathlike object or string representing a file) – Output - the output metric. Maps to a command-line argument: %s (position: 3).

Outputs:

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

class niworkflows.interfaces.workbench.MetricFillHoles(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -metric-fill-holes.

Fill holes in an ROI metric.

Examples

>>> from niworkflows.interfaces.workbench import MetricFillHoles
>>> fill_holes = MetricFillHoles()
>>> fill_holes.inputs.surface_file = 'lh.midthickness.surf.gii'
>>> fill_holes.inputs.metric_file = 'lh.roi.shape.gii'
>>> fill_holes.cmdline  
'wb_command -metric-fill-holes lh.midthickness.surf.gii lh.roi.shape.gii     lh.roi.shape_filled.shape.gii'
Mandatory Inputs:

  • metric_file (a pathlike object or string representing an existing file) – Input ROI metric. Maps to a command-line argument: %s (position: 2).

  • surface_file (a pathlike object or string representing an existing file) – Surface to use for neighbor information. Maps to a command-line argument: %s (position: 1).

Optional Inputs:

  • corrected_areas (a pathlike object or string representing an existing file) – Vertex areas to use instead of computing them from the surface. Maps to a command-line argument: -corrected-areas %s.

  • out_file (a pathlike object or string representing a file) – Output ROI metric. Maps to a command-line argument: %s (position: 3).

Outputs:

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

class niworkflows.interfaces.workbench.MetricMask(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -metric-mask.

Mask a metric file.

Examples

>>> from niworkflows.interfaces.workbench import MetricMask
>>> metric_mask = MetricMask()
>>> metric_mask.inputs.in_file = 'lh.bold.func.gii'
>>> metric_mask.inputs.mask = 'lh.roi.shape.gii'
>>> metric_mask.cmdline
'wb_command -metric-mask lh.bold.func.gii lh.roi.shape.gii lh.bold.func_masked.func.gii'
Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – Input metric file. Maps to a command-line argument: %s (position: 1).

  • mask (a pathlike object or string representing an existing file) – Mask metric file. Maps to a command-line argument: %s (position: 2).

Optional Inputs:

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

  • column (an integer or a string) – Select a single column by number or name. Maps to a command-line argument: -column %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: {})

  • out_file (a pathlike object or string representing a file) – Output metric file. Maps to a command-line argument: %s (position: 3).

Outputs:

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

class niworkflows.interfaces.workbench.MetricRemoveIslands(command=None, terminal_output=None, write_cmdline=False, **inputs)[source]

Bases: WBCommand

Wrapped executable: wb_command -metric-remove-islands.

Remove islands in an ROI metric.

Examples

>>> from niworkflows.interfaces.workbench import MetricRemoveIslands
>>> remove_islands = MetricRemoveIslands()
>>> remove_islands.inputs.surface_file = 'lh.midthickness.surf.gii'
>>> remove_islands.inputs.metric_file = 'lh.roi.shape.gii'
>>> remove_islands.cmdline  
'wb_command -metric-remove-islands lh.midthickness.surf.gii     lh.roi.shape.gii lh.roi.shape_noislands.shape.gii'
Mandatory Inputs:

  • metric_file (a pathlike object or string representing an existing file) – Input ROI metric. Maps to a command-line argument: %s (position: 2).

  • surface_file (a pathlike object or string representing an existing file) – Surface to use for neighbor information. Maps to a command-line argument: %s (position: 1).

Optional Inputs:

  • corrected_areas (a pathlike object or string representing an existing file) – Vertex areas to use instead of computing them from the surface. Maps to a command-line argument: -corrected-areas %s.

  • out_file (a pathlike object or string representing a file) – Output ROI metric. Maps to a command-line argument: %s (position: 3).

Outputs:

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

class niworkflows.interfaces.workbench.MetricResample(**inputs)[source]

Bases: WBCommand, OpenMPCommandMixin

Wrapped executable: wb_command -metric-resample.

Resample a metric file to a different mesh.

Resamples a metric file, given two spherical surfaces that are in register. If ADAP_BARY_AREA is used, exactly one of -area-surfs or -area-metrics must be specified.

The ADAP_BARY_AREA method is recommended for ordinary metric data, because it should use all data while downsampling, unlike BARYCENTRIC. The recommended areas option for most data is individual midthicknesses for individual data, and averaged vertex area metrics from individual midthicknesses for group average data.

The -current-roi option only masks the input, the output may be slightly dilated in comparison, consider using -metric-mask on the output when using -current-roi.

The -largest option results in nearest vertex behavior when used with BARYCENTRIC. When resampling a binary metric, consider thresholding at 0.5 after resampling rather than using -largest.

Mandatory Inputs:

  • current_sphere (a pathlike object or string representing an existing file) – A sphere surface with the mesh that the metric is currently on. Maps to a command-line argument: %s (position: 1).

  • in_file (a pathlike object or string representing an existing file) – The metric file to resample. Maps to a command-line argument: %s (position: 0).

  • method (‘ADAP_BARY_AREA’ or ‘BARYCENTRIC’) – The method name - ADAP_BARY_AREA method is recommended for ordinary metric data, because it should use all data while downsampling, unlike BARYCENTRIC. If ADAP_BARY_AREA is used, exactly one of area_surfs or area_metrics must be specified. Maps to a command-line argument: %s (position: 3).

  • new_sphere (a pathlike object or string representing an existing file) – A sphere surface that is in register with <current-sphere> and has the desired output mesh. Maps to a command-line argument: %s (position: 2).

Optional Inputs:

  • area_metrics (a boolean) – Specify vertex area metrics to do area correction based on. Maps to a command-line argument: -area-metrics (position: 5). Mutually exclusive with inputs: area_surfs.

  • area_surfs (a boolean) – Specify surfaces to do vertex area correction based on. Maps to a command-line argument: -area-surfs (position: 5). Mutually exclusive with inputs: area_metrics.

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

  • current_area (a pathlike object or string representing an existing file) – A relevant anatomical surface with <current-sphere> mesh OR a metric file with vertex areas for <current-sphere> mesh. Maps to a command-line argument: %s (position: 6).

  • 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: {})

  • largest (a boolean) – Use only the value of the vertex with the largest weight. Maps to a command-line argument: -largest (position: 10).

  • new_area (a pathlike object or string representing an existing file) – A relevant anatomical surface with <current-sphere> mesh OR a metric file with vertex areas for <current-sphere> mesh. Maps to a command-line argument: %s (position: 7).

  • num_threads (an integer) – Allows for specifying more threads.

  • out_file (a pathlike object or string representing a file) – The output metric. Maps to a command-line argument: %s (position: 4).

  • roi_metric (a pathlike object or string representing an existing file) – Input roi on the current mesh used to exclude non-data vertices. Maps to a command-line argument: -current-roi %s (position: 8).

  • valid_roi_out (a boolean) – Output the ROI of vertices that got data from valid source vertices. Maps to a command-line argument: -valid-roi-out (position: 9).

Outputs:

  • out_file (a pathlike object or string representing an existing file) – The output metric.

  • roi_file (a pathlike object or string representing a file) – ROI of vertices that got data from valid source vertices.

class niworkflows.interfaces.workbench.OpenMPCommandMixin(**inputs)[source]

Bases: CommandLine

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: {})

  • num_threads (an integer) – Allows for specifying more threads.

run(**inputs)[source]

Execute this interface.

This interface will not raise an exception if runtime.returncode is non-zero.

Parameters:

  • cwd (specify a folder where the interface should be run)

  • inputs (allows the interface settings to be updated)

Returns:

results – A copy of the instance that was executed, provenance information and, if successful, results

Return type:

nipype.interfaces.base.support.InterfaceResult

class niworkflows.interfaces.workbench.VolumeToSurfaceMapping(**inputs)[source]

Bases: WBCommand, OpenMPCommandMixin

Wrapped executable: wb_command -volume-to-surface-mapping.

Map a volume to a surface using one of several methods.

From https://humanconnectome.org/software/workbench-command/-volume-to-surface-mapping:

You must specify exactly one mapping method.  Enclosing voxel uses the
value from the voxel the vertex lies inside, while trilinear does a 3D
linear interpolation based on the voxels immediately on each side of the
vertex's position.

The ribbon mapping method constructs a polyhedron from the vertex's
neighbors on each surface, and estimates the amount of this polyhedron's
volume that falls inside any nearby voxels, to use as the weights for
sampling.  If -thin-columns is specified, the polyhedron uses the edge
midpoints and triangle centroids, so that neighboring vertices do not
have overlapping polyhedra.  This may require increasing -voxel-subdiv to
get enough samples in each voxel to reliably land inside these smaller
polyhedra.  The volume ROI is useful to exclude partial volume effects of
voxels the surfaces pass through, and will cause the mapping to ignore
voxels that don't have a positive value in the mask.  The subdivision
number specifies how it approximates the amount of the volume the
polyhedron intersects, by splitting each voxel into NxNxN pieces, and
checking whether the center of each piece is inside the polyhedron.  If
you have very large voxels, consider increasing this if you get zeros in
your output.  The -gaussian option makes it act more like the myelin
method, where the distance of a voxel from <surface> is used to
downweight the voxel.  The -interpolate suboption, instead of doing a
weighted average of voxels, interpolates from the volume at the
subdivided points inside the ribbon.  If using both -interpolate and the
-weighted suboption to -volume-roi, the roi volume weights are linearly
interpolated, unless the -interpolate method is ENCLOSING_VOXEL, in which
case ENCLOSING_VOXEL is also used for sampling the roi volume weights.

The myelin style method uses part of the caret5 myelin mapping command to
do the mapping: for each surface vertex, take all voxels that are in a
cylinder with radius and height equal to cortical thickness, centered on
the vertex and aligned with the surface normal, and that are also within
the ribbon ROI, and apply a gaussian kernel with the specified sigma to
them to get the weights to use.  The -legacy-bug flag reverts to the
unintended behavior present from the initial implementation up to and
including v1.2.3, which had only the tangential cutoff and a bounding box
intended to be larger than where the cylinder cutoff should have been.

Examples: >>> from niworkflows.interfaces.workbench import VolumeToSurfaceMapping >>> vol2surf = VolumeToSurfaceMapping() >>> vol2surf.inputs.volume_file = ‘bold.nii.gz’ >>> vol2surf.inputs.surface_file = ‘lh.midthickness.surf.gii’ >>> vol2surf.inputs.method = ‘ribbon-constrained’ >>> vol2surf.inputs.inner_surface = ‘lh.white.surf.gii’ >>> vol2surf.inputs.outer_surface = ‘lh.pial.surf.gii’ >>> vol2surf.cmdline # doctest: +NORMALIZE_WHITESPACE ‘wb_command -volume-to-surface-mapping bold.nii.gz lh.midthickness.surf.gii lh.midthickness.surf_mapped.func.gii -ribbon-constrained lh.white.surf.gii lh.pial.surf.gii’

Mandatory Inputs:

  • surface_file (a pathlike object or string representing an existing file) – The surface to map the data onto. Maps to a command-line argument: %s (position: 2).

  • volume_file (a pathlike object or string representing an existing file) – The volume to map data from. 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.

  • bad_vertices_out (a pathlike object or string representing a file) – Output an ROI of which vertices didn’t intersect any valid voxels. Maps to a command-line argument: -bad-vertices-out %s. Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • 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: {})

  • gaussian (a float) – Reduce weight to voxels that aren’t near <surface> [-ribbon-constrained]. Maps to a command-line argument: -gaussian %g. Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • inner_surface (a pathlike object or string representing an existing file) – The inner surface of the ribbon [-ribbon-constrained]. Maps to a command-line argument: %s (position: 5). Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • interpolate (‘CUBIC’ or ‘TRILINEAR’ or ‘ENCLOSING_VOXEL’) – Instead of a weighted average of voxels, interpolate at subpoints inside the ribbon [-ribbon-constrained]. Maps to a command-line argument: -interpolate %s. Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • legacy_bug (a boolean) – Use the old bug in the myelin-style algorithm [-myelin-style]. Maps to a command-line argument: -legacy-bug (position: 8). Mutually exclusive with inputs: inner_surface, outer_surface, volume_roi, weighted, voxel_subdiv, gaussian, interpolate, bad_vertices_out, output_weights, output_weights_text.

  • method (‘trilinear’ or ‘enclosing’ or ‘cubic’ or ‘ribbon-constrained’ or ‘myelin-style’) – The interpolation method to use. Maps to a command-line argument: -%s (position: 4).

  • num_threads (an integer) – Allows for specifying more threads.

  • out_file (a pathlike object or string representing a file) – The output metric file. Maps to a command-line argument: %s (position: 3).

  • outer_surface (a pathlike object or string representing an existing file) – The outer surface of the ribbon [-ribbon-constrained]. Maps to a command-line argument: %s (position: 6). Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • output_weights (an integer) – Write the voxel weights for a vertex to a volume file. Maps to a command-line argument: -output-weights %(0)d output_weights.nii.gz. Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • output_weights_text (a string or os.PathLike object) – Write the voxel weights for all vertices to a text file. Maps to a command-line argument: -output-weights-text %s. Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • ribbon_roi (a pathlike object or string representing an existing file) – An roi volume of the cortical ribbon for this hemisphere [-myelin-style]. Maps to a command-line argument: %s (position: 5). Mutually exclusive with inputs: inner_surface, outer_surface, volume_roi, weighted, voxel_subdiv, gaussian, interpolate, bad_vertices_out, output_weights, output_weights_text.

  • sigma (a float) – Gaussian kernel in mm for weighting voxels within range [-myelin-style]. Maps to a command-line argument: %g (position: 7). Mutually exclusive with inputs: inner_surface, outer_surface, volume_roi, weighted, voxel_subdiv, gaussian, interpolate, bad_vertices_out, output_weights, output_weights_text.

  • subvol_select (an integer) – Select a single subvolume to map. Maps to a command-line argument: -subvol-select %d.

  • thickness (a pathlike object or string representing an existing file) – The thickness metric file for this hemisphere [-myelin-style]. Maps to a command-line argument: %s (position: 6). Mutually exclusive with inputs: inner_surface, outer_surface, volume_roi, weighted, voxel_subdiv, gaussian, interpolate, bad_vertices_out, output_weights, output_weights_text.

  • thin_columns (a boolean) – Use non-overlapping polyhedra [-ribbon-constrained]. Maps to a command-line argument: -thin-columns. Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • volume_roi (a pathlike object or string representing an existing file) – Use a volume roi [-ribbon-constrained]. Maps to a command-line argument: -volume-roi %s (position: 7). Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • voxel_subdiv (an integer) – Voxel divisions while estimating voxel weights [-ribbon-constrained]. Maps to a command-line argument: -voxel-subdiv %d. Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug.

  • weighted (a boolean) – Treat the roi values as weightings rather than binary [-ribbon-constrained]. Maps to a command-line argument: -weighted (position: 8). Mutually exclusive with inputs: ribbon_roi, thickness, sigma, legacy_bug. Requires inputs: volume_roi.

Outputs:

  • bad_vertices_file (a pathlike object or string representing a file) – The output metric file of vertices that have no data.

  • out_file (a pathlike object or string representing a file) – The output metric file.

  • weights_file (a pathlike object or string representing a file) – Volume to write the weights to.

  • weights_text_file (a pathlike object or string representing a file) – The output text filename.