# This file was auto generated by Styx.
# Do not edit this file directly.

import typing
import pathlib
from styxdefs import *

METRIC_SMOOTHING_METADATA = Metadata(
    id="0a396b41d5717355e9d6de5fcc33e96e22014d30.boutiques",
    name="metric-smoothing",
    package="workbench",
    container_image_tag="brainlife/connectome_workbench:1.5.0-freesurfer-update",
)


MetricSmoothingRoiParameters = typing.TypedDict('MetricSmoothingRoiParameters', {
    "@type": typing.NotRequired[typing.Literal["roi"]],
    "roi_metric": InputPathType,
    "opt_match_columns": bool,
})
MetricSmoothingRoiParametersTagged = typing.TypedDict('MetricSmoothingRoiParametersTagged', {
    "@type": typing.Literal["roi"],
    "roi_metric": InputPathType,
    "opt_match_columns": bool,
})


MetricSmoothingParameters = typing.TypedDict('MetricSmoothingParameters', {
    "@type": typing.NotRequired[typing.Literal["workbench/metric-smoothing"]],
    "surface": InputPathType,
    "metric_in": InputPathType,
    "smoothing_kernel": float,
    "metric_out": str,
    "opt_fwhm": bool,
    "roi": typing.NotRequired[MetricSmoothingRoiParameters | None],
    "opt_fix_zeros": bool,
    "opt_column_column": typing.NotRequired[str | None],
    "opt_corrected_areas_area_metric": typing.NotRequired[InputPathType | None],
    "opt_method_method": typing.NotRequired[str | None],
})
MetricSmoothingParametersTagged = typing.TypedDict('MetricSmoothingParametersTagged', {
    "@type": typing.Literal["workbench/metric-smoothing"],
    "surface": InputPathType,
    "metric_in": InputPathType,
    "smoothing_kernel": float,
    "metric_out": str,
    "opt_fwhm": bool,
    "roi": typing.NotRequired[MetricSmoothingRoiParameters | None],
    "opt_fix_zeros": bool,
    "opt_column_column": typing.NotRequired[str | None],
    "opt_corrected_areas_area_metric": typing.NotRequired[InputPathType | None],
    "opt_method_method": typing.NotRequired[str | None],
})


def metric_smoothing_roi_params(
    roi_metric: InputPathType,
    opt_match_columns: bool = False,
) -> MetricSmoothingRoiParametersTagged:
    """
    Build parameters.
    
    Args:
        roi_metric: the roi to smooth within, as a metric.
        opt_match_columns: for each input column, use the corresponding column\
            from the roi.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "roi",
        "roi_metric": roi_metric,
        "opt_match_columns": opt_match_columns,
    }
    return params


def metric_smoothing_roi_cargs(
    params: MetricSmoothingRoiParameters,
    execution: Execution,
) -> list[str]:
    """
    Build command-line arguments from parameters.
    
    Args:
        params: The parameters.
        execution: The execution object for resolving input paths.
    Returns:
        Command-line arguments.
    """
    cargs = []
    cargs.append("-roi")
    cargs.append(execution.input_file(params.get("roi_metric", None)))
    if params.get("opt_match_columns", False):
        cargs.append("-match-columns")
    return cargs


class MetricSmoothingOutputs(typing.NamedTuple):
    """
    Output object returned when calling `MetricSmoothingParameters(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    metric_out: OutputPathType
    """the output metric"""


def metric_smoothing_params(
    surface: InputPathType,
    metric_in: InputPathType,
    smoothing_kernel: float,
    metric_out: str,
    opt_fwhm: bool = False,
    roi: MetricSmoothingRoiParameters | None = None,
    opt_fix_zeros: bool = False,
    opt_column_column: str | None = None,
    opt_corrected_areas_area_metric: InputPathType | None = None,
    opt_method_method: str | None = None,
) -> MetricSmoothingParametersTagged:
    """
    Build parameters.
    
    Args:
        surface: the surface to smooth on.
        metric_in: the metric to smooth.
        smoothing_kernel: the size of the gaussian smoothing kernel in mm, as\
            sigma by default.
        metric_out: the output metric.
        opt_fwhm: kernel size is FWHM, not sigma.
        roi: select a region of interest to smooth.
        opt_fix_zeros: treat zero values as not being data.
        opt_column_column: select a single column to smooth: the column number\
            or name.
        opt_corrected_areas_area_metric: vertex areas to use instead of\
            computing them from the surface: the corrected vertex areas, as a\
            metric.
        opt_method_method: select smoothing method, default GEO_GAUSS_AREA: the\
            name of the smoothing method.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "workbench/metric-smoothing",
        "surface": surface,
        "metric_in": metric_in,
        "smoothing_kernel": smoothing_kernel,
        "metric_out": metric_out,
        "opt_fwhm": opt_fwhm,
        "opt_fix_zeros": opt_fix_zeros,
    }
    if roi is not None:
        params["roi"] = roi
    if opt_column_column is not None:
        params["opt_column_column"] = opt_column_column
    if opt_corrected_areas_area_metric is not None:
        params["opt_corrected_areas_area_metric"] = opt_corrected_areas_area_metric
    if opt_method_method is not None:
        params["opt_method_method"] = opt_method_method
    return params


def metric_smoothing_cargs(
    params: MetricSmoothingParameters,
    execution: Execution,
) -> list[str]:
    """
    Build command-line arguments from parameters.
    
    Args:
        params: The parameters.
        execution: The execution object for resolving input paths.
    Returns:
        Command-line arguments.
    """
    cargs = []
    cargs.append("wb_command")
    cargs.append("-metric-smoothing")
    cargs.append(execution.input_file(params.get("surface", None)))
    cargs.append(execution.input_file(params.get("metric_in", None)))
    cargs.append(str(params.get("smoothing_kernel", None)))
    cargs.append(params.get("metric_out", None))
    if params.get("opt_fwhm", False):
        cargs.append("-fwhm")
    if params.get("roi", None) is not None:
        cargs.extend(metric_smoothing_roi_cargs(params.get("roi", None), execution))
    if params.get("opt_fix_zeros", False):
        cargs.append("-fix-zeros")
    if params.get("opt_column_column", None) is not None:
        cargs.extend([
            "-column",
            params.get("opt_column_column", None)
        ])
    if params.get("opt_corrected_areas_area_metric", None) is not None:
        cargs.extend([
            "-corrected-areas",
            execution.input_file(params.get("opt_corrected_areas_area_metric", None))
        ])
    if params.get("opt_method_method", None) is not None:
        cargs.extend([
            "-method",
            params.get("opt_method_method", None)
        ])
    return cargs


def metric_smoothing_outputs(
    params: MetricSmoothingParameters,
    execution: Execution,
) -> MetricSmoothingOutputs:
    """
    Build outputs object containing output file paths and possibly stdout/stderr.
    
    Args:
        params: The parameters.
        execution: The execution object for resolving input paths.
    Returns:
        Outputs object.
    """
    ret = MetricSmoothingOutputs(
        root=execution.output_file("."),
        metric_out=execution.output_file(params.get("metric_out", None)),
    )
    return ret


def metric_smoothing_execute(
    params: MetricSmoothingParameters,
    runner: Runner | None = None,
) -> MetricSmoothingOutputs:
    """
    metric-smoothing
    
    Smooth a metric file.
    
    Smooth a metric file on a surface. By default, smooths all input columns on
    the entire surface, specify -column to use only one input column, and -roi
    to smooth only where the roi metric is greater than 0, outputting zeros
    elsewhere.
    
    When using -roi, input data outside the ROI is not used to compute the
    smoothed values. By default, the first column of the roi metric is used for
    all input columns. When -match-columns is specified to the -roi option, the
    input and roi metrics must have the same number of columns, and for each
    input column's index, the same column index is used in the roi metric. If
    the -match-columns option to -roi is used while the -column option is also
    used, the number of columns must match between the roi and input metric, and
    it will use the roi column with the index of the selected input column.
    
    The -fix-zeros option causes the smoothing to not use an input value if it
    is zero, but still write a smoothed value to the vertex. This is useful for
    zeros that indicate lack of information, preventing them from pulling down
    the intensity of nearby vertices, while giving the zero an extrapolated
    value.
    
    The -corrected-areas option is intended for when it is unavoidable to smooth
    on a group average surface, it is only an approximate correction for the
    reduction of structure in a group average surface. It is better to smooth
    the data on individuals before averaging, when feasible.
    
    Valid values for <method> are:
    
    GEO_GAUSS_AREA - uses a geodesic gaussian kernel, and normalizes based on
    vertex area in order to work more reliably on irregular surfaces
    
    GEO_GAUSS_EQUAL - uses a geodesic gaussian kernel, and normalizes assuming
    each vertex has equal importance
    
    GEO_GAUSS - matches geodesic gaussian smoothing from caret5, but does not
    check kernels for having unequal importance
    
    The GEO_GAUSS_AREA method is the default because it is usually the correct
    choice. GEO_GAUSS_EQUAL may be the correct choice when the sum of vertex
    values is more meaningful then the surface integral (sum of values .*
    areas), for instance when smoothing vertex areas (the sum is the total
    surface area, while the surface integral is the sum of squares of the vertex
    areas). The GEO_GAUSS method is not recommended, it exists mainly to
    replicate methods of studies done with caret5's geodesic smoothing.
    
    Author: Connectome Workbench Developers
    
    URL: https://github.com/Washington-University/workbench
    
    Args:
        params: The parameters.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `MetricSmoothingOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(METRIC_SMOOTHING_METADATA)
    params = execution.params(params)
    cargs = metric_smoothing_cargs(params, execution)
    ret = metric_smoothing_outputs(params, execution)
    execution.run(cargs)
    return ret


def metric_smoothing(
    surface: InputPathType,
    metric_in: InputPathType,
    smoothing_kernel: float,
    metric_out: str,
    opt_fwhm: bool = False,
    roi: MetricSmoothingRoiParameters | None = None,
    opt_fix_zeros: bool = False,
    opt_column_column: str | None = None,
    opt_corrected_areas_area_metric: InputPathType | None = None,
    opt_method_method: str | None = None,
    runner: Runner | None = None,
) -> MetricSmoothingOutputs:
    """
    metric-smoothing
    
    Smooth a metric file.
    
    Smooth a metric file on a surface. By default, smooths all input columns on
    the entire surface, specify -column to use only one input column, and -roi
    to smooth only where the roi metric is greater than 0, outputting zeros
    elsewhere.
    
    When using -roi, input data outside the ROI is not used to compute the
    smoothed values. By default, the first column of the roi metric is used for
    all input columns. When -match-columns is specified to the -roi option, the
    input and roi metrics must have the same number of columns, and for each
    input column's index, the same column index is used in the roi metric. If
    the -match-columns option to -roi is used while the -column option is also
    used, the number of columns must match between the roi and input metric, and
    it will use the roi column with the index of the selected input column.
    
    The -fix-zeros option causes the smoothing to not use an input value if it
    is zero, but still write a smoothed value to the vertex. This is useful for
    zeros that indicate lack of information, preventing them from pulling down
    the intensity of nearby vertices, while giving the zero an extrapolated
    value.
    
    The -corrected-areas option is intended for when it is unavoidable to smooth
    on a group average surface, it is only an approximate correction for the
    reduction of structure in a group average surface. It is better to smooth
    the data on individuals before averaging, when feasible.
    
    Valid values for <method> are:
    
    GEO_GAUSS_AREA - uses a geodesic gaussian kernel, and normalizes based on
    vertex area in order to work more reliably on irregular surfaces
    
    GEO_GAUSS_EQUAL - uses a geodesic gaussian kernel, and normalizes assuming
    each vertex has equal importance
    
    GEO_GAUSS - matches geodesic gaussian smoothing from caret5, but does not
    check kernels for having unequal importance
    
    The GEO_GAUSS_AREA method is the default because it is usually the correct
    choice. GEO_GAUSS_EQUAL may be the correct choice when the sum of vertex
    values is more meaningful then the surface integral (sum of values .*
    areas), for instance when smoothing vertex areas (the sum is the total
    surface area, while the surface integral is the sum of squares of the vertex
    areas). The GEO_GAUSS method is not recommended, it exists mainly to
    replicate methods of studies done with caret5's geodesic smoothing.
    
    Author: Connectome Workbench Developers
    
    URL: https://github.com/Washington-University/workbench
    
    Args:
        surface: the surface to smooth on.
        metric_in: the metric to smooth.
        smoothing_kernel: the size of the gaussian smoothing kernel in mm, as\
            sigma by default.
        metric_out: the output metric.
        opt_fwhm: kernel size is FWHM, not sigma.
        roi: select a region of interest to smooth.
        opt_fix_zeros: treat zero values as not being data.
        opt_column_column: select a single column to smooth: the column number\
            or name.
        opt_corrected_areas_area_metric: vertex areas to use instead of\
            computing them from the surface: the corrected vertex areas, as a\
            metric.
        opt_method_method: select smoothing method, default GEO_GAUSS_AREA: the\
            name of the smoothing method.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `MetricSmoothingOutputs`).
    """
    params = metric_smoothing_params(
        surface=surface,
        metric_in=metric_in,
        smoothing_kernel=smoothing_kernel,
        metric_out=metric_out,
        opt_fwhm=opt_fwhm,
        roi=roi,
        opt_fix_zeros=opt_fix_zeros,
        opt_column_column=opt_column_column,
        opt_corrected_areas_area_metric=opt_corrected_areas_area_metric,
        opt_method_method=opt_method_method,
    )
    return metric_smoothing_execute(params, runner)


__all__ = [
    "METRIC_SMOOTHING_METADATA",
    "MetricSmoothingOutputs",
    "metric_smoothing",
    "metric_smoothing_execute",
    "metric_smoothing_params",
    "metric_smoothing_roi_params",
]
