nipype.interfaces.workbench.metric module

This module provides interfaces for workbench surface commands

MetricResample

Link to code

Bases: WBCommand

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.

>>> from nipype.interfaces.workbench import MetricResample
>>> metres = MetricResample()
>>> metres.inputs.in_file = 'sub-01_task-rest_bold_space-fsaverage5.L.func.gii'
>>> metres.inputs.method = 'ADAP_BARY_AREA'
>>> metres.inputs.current_sphere = 'fsaverage5_std_sphere.L.10k_fsavg_L.surf.gii'
>>> metres.inputs.new_sphere = 'fs_LR-deformed_to-fsaverage.L.sphere.32k_fs_LR.surf.gii'
>>> metres.inputs.area_metrics = True
>>> metres.inputs.current_area = 'fsaverage5.L.midthickness_va_avg.10k_fsavg_L.shape.gii'
>>> metres.inputs.new_area = 'fs_LR.L.midthickness_va_avg.32k_fs_LR.shape.gii'
>>> metres.cmdline
'wb_command -metric-resample sub-01_task-rest_bold_space-fsaverage5.L.func.gii     fsaverage5_std_sphere.L.10k_fsavg_L.surf.gii     fs_LR-deformed_to-fsaverage.L.sphere.32k_fs_LR.surf.gii     ADAP_BARY_AREA fs_LR-deformed_to-fsaverage.L.sphere.32k_fs_LR.surf.out     -area-metrics fsaverage5.L.midthickness_va_avg.10k_fsavg_L.shape.gii     fs_LR.L.midthickness_va_avg.32k_fs_LR.shape.gii'
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).

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