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

import typing
import pathlib
from styxdefs import *

METRIC_WEIGHTED_STATS_METADATA = Metadata(
    id="59d1210ae1d155885888b93e8db71154f04e52bd.workbench",
    name="metric-weighted-stats",
    package="workbench",
    container_image_tag="nx10x/workbench:2.1.0",
)


_MetricWeightedStatsRoiParamsDictNoTag = typing.TypedDict('_MetricWeightedStatsRoiParamsDictNoTag', {
    "roi-metric": InputPathType,
    "match-maps": bool,
})
MetricWeightedStatsRoiParamsDictTagged = typing.TypedDict('MetricWeightedStatsRoiParamsDictTagged', {
    "@type": typing.Literal["roi"],
    "roi-metric": InputPathType,
    "match-maps": bool,
})
MetricWeightedStatsRoiParamsDict = _MetricWeightedStatsRoiParamsDictNoTag | MetricWeightedStatsRoiParamsDictTagged


_MetricWeightedStatsParamsDictNoTag = typing.TypedDict('_MetricWeightedStatsParamsDictNoTag', {
    "metric-in": InputPathType,
    "roi": typing.NotRequired[MetricWeightedStatsRoiParamsDict | None],
    "percent": typing.NotRequired[float | None],
    "sample": typing.NotRequired[bool | None],
    "column": typing.NotRequired[str | None],
    "weight-metric": typing.NotRequired[InputPathType | None],
    "area-surface": typing.NotRequired[InputPathType | None],
    "show-map-name": bool,
    "sum": bool,
    "mean": bool,
})
MetricWeightedStatsParamsDictTagged = typing.TypedDict('MetricWeightedStatsParamsDictTagged', {
    "@type": typing.Literal["workbench/metric-weighted-stats"],
    "metric-in": InputPathType,
    "roi": typing.NotRequired[MetricWeightedStatsRoiParamsDict | None],
    "percent": typing.NotRequired[float | None],
    "sample": typing.NotRequired[bool | None],
    "column": typing.NotRequired[str | None],
    "weight-metric": typing.NotRequired[InputPathType | None],
    "area-surface": typing.NotRequired[InputPathType | None],
    "show-map-name": bool,
    "sum": bool,
    "mean": bool,
})
MetricWeightedStatsParamsDict = _MetricWeightedStatsParamsDictNoTag | MetricWeightedStatsParamsDictTagged


def metric_weighted_stats_roi(
    roi_metric: InputPathType,
    match_maps: bool = False,
) -> MetricWeightedStatsRoiParamsDictTagged:
    """
    Build parameters.
    
    Args:
        roi_metric: the roi, as a metric file.
        match_maps: each column of input uses the corresponding column from the\
            roi file.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "roi",
        "roi-metric": roi_metric,
        "match-maps": match_maps,
    }
    return params


def metric_weighted_stats_roi_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `MetricWeightedStatsRoiParamsDict` object.
    
    Args:
        params: The parameters object to validate.
    """
    if params is None or not isinstance(params, dict):
        raise StyxValidationError(f'Params object has the wrong type \'{type(params)}\'')
    if params.get("roi-metric", None) is None:
        raise StyxValidationError("`roi-metric` must not be None")
    if not isinstance(params["roi-metric"], (pathlib.Path, str)):
        raise StyxValidationError(f'`roi-metric` has the wrong type: Received `{type(params.get("roi-metric", None))}` expected `InputPathType`')
    if params.get("match-maps", False) is None:
        raise StyxValidationError("`match-maps` must not be None")
    if not isinstance(params["match-maps"], bool):
        raise StyxValidationError(f'`match-maps` has the wrong type: Received `{type(params.get("match-maps", False))}` expected `bool`')


def metric_weighted_stats_roi_cargs(
    params: MetricWeightedStatsRoiParamsDict,
    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.extend([
        "-roi",
        execution.input_file(params.get("roi-metric", None))
    ])
    if params.get("match-maps", False):
        cargs.append("-match-maps")
    return cargs


class MetricWeightedStatsOutputs(typing.NamedTuple):
    """
    Output object returned when calling `MetricWeightedStatsParamsDict(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""


def metric_weighted_stats_params(
    metric_in: InputPathType,
    roi: MetricWeightedStatsRoiParamsDict | None = None,
    percent: float | None = None,
    sample: bool | None = None,
    column: str | None = None,
    weight_metric: InputPathType | None = None,
    area_surface: InputPathType | None = None,
    show_map_name: bool = False,
    sum_: bool = False,
    mean: bool = False,
) -> MetricWeightedStatsParamsDictTagged:
    """
    Build parameters.
    
    Args:
        metric_in: the input metric.
        roi: only consider data inside an roi.
        percent: compute weighted percentile\
            \
            the percentile to find, must be between 0 and 100.
        sample: compute weighted standard deviation\
            \
            estimate population stdev from the sample.
        column: only display output for one column\
            \
            the column number or name.
        weight_metric: use weights from a metric file\
            \
            metric file containing the weights.
        area_surface: use vertex areas as weights\
            \
            the surface to use for vertex areas.
        show_map_name: print map index and name before each output.
        sum_: compute weighted sum.
        mean: compute weighted mean.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "workbench/metric-weighted-stats",
        "metric-in": metric_in,
        "show-map-name": show_map_name,
        "sum": sum_,
        "mean": mean,
    }
    if roi is not None:
        params["roi"] = roi
    if percent is not None:
        params["percent"] = percent
    if sample is not None:
        params["sample"] = sample
    if column is not None:
        params["column"] = column
    if weight_metric is not None:
        params["weight-metric"] = weight_metric
    if area_surface is not None:
        params["area-surface"] = area_surface
    return params


def metric_weighted_stats_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `MetricWeightedStatsParamsDict` object.
    
    Args:
        params: The parameters object to validate.
    """
    if params is None or not isinstance(params, dict):
        raise StyxValidationError(f'Params object has the wrong type \'{type(params)}\'')
    if params.get("metric-in", None) is None:
        raise StyxValidationError("`metric-in` must not be None")
    if not isinstance(params["metric-in"], (pathlib.Path, str)):
        raise StyxValidationError(f'`metric-in` has the wrong type: Received `{type(params.get("metric-in", None))}` expected `InputPathType`')
    if params.get("roi", None) is not None:
        metric_weighted_stats_roi_validate(params["roi"])
    if params.get("percent", None) is not None:
        if not isinstance(params["percent"], (float, int)):
            raise StyxValidationError(f'`percent` has the wrong type: Received `{type(params.get("percent", None))}` expected `float | None`')
    if params.get("sample", None) is not None:
        if not isinstance(params["sample"], bool):
            raise StyxValidationError(f'`sample` has the wrong type: Received `{type(params.get("sample", None))}` expected `bool | None`')
    if params.get("column", None) is not None:
        if not isinstance(params["column"], str):
            raise StyxValidationError(f'`column` has the wrong type: Received `{type(params.get("column", None))}` expected `str | None`')
    if params.get("weight-metric", None) is not None:
        if not isinstance(params["weight-metric"], (pathlib.Path, str)):
            raise StyxValidationError(f'`weight-metric` has the wrong type: Received `{type(params.get("weight-metric", None))}` expected `InputPathType | None`')
    if params.get("area-surface", None) is not None:
        if not isinstance(params["area-surface"], (pathlib.Path, str)):
            raise StyxValidationError(f'`area-surface` has the wrong type: Received `{type(params.get("area-surface", None))}` expected `InputPathType | None`')
    if params.get("show-map-name", False) is None:
        raise StyxValidationError("`show-map-name` must not be None")
    if not isinstance(params["show-map-name"], bool):
        raise StyxValidationError(f'`show-map-name` has the wrong type: Received `{type(params.get("show-map-name", False))}` expected `bool`')
    if params.get("sum", False) is None:
        raise StyxValidationError("`sum` must not be None")
    if not isinstance(params["sum"], bool):
        raise StyxValidationError(f'`sum` has the wrong type: Received `{type(params.get("sum", False))}` expected `bool`')
    if params.get("mean", False) is None:
        raise StyxValidationError("`mean` must not be None")
    if not isinstance(params["mean"], bool):
        raise StyxValidationError(f'`mean` has the wrong type: Received `{type(params.get("mean", False))}` expected `bool`')


def metric_weighted_stats_cargs(
    params: MetricWeightedStatsParamsDict,
    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.extend([
        "wb_command",
        "-metric-weighted-stats"
    ])
    cargs.append(execution.input_file(params.get("metric-in", None)))
    if params.get("roi", None) is not None:
        cargs.extend(metric_weighted_stats_roi_cargs(params.get("roi", None), execution))
    if params.get("percent", None) is not None:
        cargs.extend([
            "-percentile",
            str(params.get("percent", None))
        ])
    if params.get("sample", None) is not None:
        cargs.extend([
            "-stdev",
            "-sample"
        ])
    if params.get("column", None) is not None:
        cargs.extend([
            "-column",
            params.get("column", None)
        ])
    if params.get("weight-metric", None) is not None:
        cargs.extend([
            "-weight-metric",
            execution.input_file(params.get("weight-metric", None))
        ])
    if params.get("area-surface", None) is not None:
        cargs.extend([
            "-area-surface",
            execution.input_file(params.get("area-surface", None))
        ])
    if params.get("show-map-name", False):
        cargs.append("-show-map-name")
    if params.get("sum", False):
        cargs.append("-sum")
    if params.get("mean", False):
        cargs.append("-mean")
    return cargs


def metric_weighted_stats_outputs(
    params: MetricWeightedStatsParamsDict,
    execution: Execution,
) -> MetricWeightedStatsOutputs:
    """
    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 = MetricWeightedStatsOutputs(
        root=execution.output_file("."),
    )
    return ret


def metric_weighted_stats_execute(
    params: MetricWeightedStatsParamsDict,
    runner: Runner | None = None,
) -> MetricWeightedStatsOutputs:
    """
    WEIGHTED SPATIAL STATISTICS ON A METRIC FILE.
    
    For each column of the input, a line of text is printed, resulting from the
    specified operation. You must specify exactly one of -area-surface or
    -weight-metric. Use -column to only give output for a single column. If the
    -roi option is used without -match-maps, then each line will contain as many
    numbers as there are maps in the ROI file, separated by tab characters.
    Exactly one of -mean, -stdev, -percentile or -sum must be specified.
    
    Using -sum with -area-surface (or -weight-metric with a metric containing
    similar data) is equivalent to integrating with respect to surface area. For
    example, if you want to find the surface area within an roi, do this:
    
    $ wb_command -metric-weighted-stats roi.func.gii -sum -area-surface
    midthickness.surf.gii.
    
    Args:
        params: The parameters.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `MetricWeightedStatsOutputs`).
    """
    metric_weighted_stats_validate(params)
    runner = runner or get_global_runner()
    execution = runner.start_execution(METRIC_WEIGHTED_STATS_METADATA)
    params = execution.params(params)
    cargs = metric_weighted_stats_cargs(params, execution)
    ret = metric_weighted_stats_outputs(params, execution)
    execution.run(cargs)
    return ret


def metric_weighted_stats(
    metric_in: InputPathType,
    roi: MetricWeightedStatsRoiParamsDict | None = None,
    percent: float | None = None,
    sample: bool | None = None,
    column: str | None = None,
    weight_metric: InputPathType | None = None,
    area_surface: InputPathType | None = None,
    show_map_name: bool = False,
    sum_: bool = False,
    mean: bool = False,
    runner: Runner | None = None,
) -> MetricWeightedStatsOutputs:
    """
    WEIGHTED SPATIAL STATISTICS ON A METRIC FILE.
    
    For each column of the input, a line of text is printed, resulting from the
    specified operation. You must specify exactly one of -area-surface or
    -weight-metric. Use -column to only give output for a single column. If the
    -roi option is used without -match-maps, then each line will contain as many
    numbers as there are maps in the ROI file, separated by tab characters.
    Exactly one of -mean, -stdev, -percentile or -sum must be specified.
    
    Using -sum with -area-surface (or -weight-metric with a metric containing
    similar data) is equivalent to integrating with respect to surface area. For
    example, if you want to find the surface area within an roi, do this:
    
    $ wb_command -metric-weighted-stats roi.func.gii -sum -area-surface
    midthickness.surf.gii.
    
    Args:
        metric_in: the input metric.
        roi: only consider data inside an roi.
        percent: compute weighted percentile\
            \
            the percentile to find, must be between 0 and 100.
        sample: compute weighted standard deviation\
            \
            estimate population stdev from the sample.
        column: only display output for one column\
            \
            the column number or name.
        weight_metric: use weights from a metric file\
            \
            metric file containing the weights.
        area_surface: use vertex areas as weights\
            \
            the surface to use for vertex areas.
        show_map_name: print map index and name before each output.
        sum_: compute weighted sum.
        mean: compute weighted mean.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `MetricWeightedStatsOutputs`).
    """
    params = metric_weighted_stats_params(
        metric_in=metric_in,
        roi=roi,
        percent=percent,
        sample=sample,
        column=column,
        weight_metric=weight_metric,
        area_surface=area_surface,
        show_map_name=show_map_name,
        sum_=sum_,
        mean=mean,
    )
    return metric_weighted_stats_execute(params, runner)


__all__ = [
    "METRIC_WEIGHTED_STATS_METADATA",
    "MetricWeightedStatsOutputs",
    "MetricWeightedStatsParamsDict",
    "MetricWeightedStatsParamsDictTagged",
    "MetricWeightedStatsRoiParamsDict",
    "MetricWeightedStatsRoiParamsDictTagged",
    "metric_weighted_stats",
    "metric_weighted_stats_execute",
    "metric_weighted_stats_params",
    "metric_weighted_stats_roi",
]
