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

import typing
import pathlib
from styxdefs import *

METRIC_FALSE_CORRELATION_METADATA = Metadata(
    id="c5fa55ac073dd0a51eb97deb240c610fa9ebef79.workbench",
    name="metric-false-correlation",
    package="workbench",
    container_image_tag="nx10x/workbench:2.1.0",
)


_MetricFalseCorrelationParamsDictNoTag = typing.TypedDict('_MetricFalseCorrelationParamsDictNoTag', {
    "surface": InputPathType,
    "metric-in": InputPathType,
    "3D-dist": float,
    "geo-outer": float,
    "geo-inner": float,
    "metric-out": str,
    "text-out": typing.NotRequired[str | None],
    "roi-metric": typing.NotRequired[InputPathType | None],
})
MetricFalseCorrelationParamsDictTagged = typing.TypedDict('MetricFalseCorrelationParamsDictTagged', {
    "@type": typing.Literal["workbench/metric-false-correlation"],
    "surface": InputPathType,
    "metric-in": InputPathType,
    "3D-dist": float,
    "geo-outer": float,
    "geo-inner": float,
    "metric-out": str,
    "text-out": typing.NotRequired[str | None],
    "roi-metric": typing.NotRequired[InputPathType | None],
})
MetricFalseCorrelationParamsDict = _MetricFalseCorrelationParamsDictNoTag | MetricFalseCorrelationParamsDictTagged


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


def metric_false_correlation_params(
    surface: InputPathType,
    metric_in: InputPathType,
    v_3_d_dist: float,
    geo_outer: float,
    geo_inner: float,
    metric_out: str,
    text_out: str | None = None,
    roi_metric: InputPathType | None = None,
) -> MetricFalseCorrelationParamsDictTagged:
    """
    Build parameters.
    
    Args:
        surface: the surface to compute geodesic and 3D distance with.
        metric_in: the metric to correlate.
        v_3_d_dist: maximum 3D distance to check around each vertex.
        geo_outer: maximum geodesic distance to use for neighboring correlation.
        geo_inner: minimum geodesic distance to use for neighboring correlation.
        metric_out: the output metric.
        text_out: dump the raw measures used to a text file\
            \
            the output text file.
        roi_metric: select a region of interest that has data\
            \
            the region, as a metric file.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "workbench/metric-false-correlation",
        "surface": surface,
        "metric-in": metric_in,
        "3D-dist": v_3_d_dist,
        "geo-outer": geo_outer,
        "geo-inner": geo_inner,
        "metric-out": metric_out,
    }
    if text_out is not None:
        params["text-out"] = text_out
    if roi_metric is not None:
        params["roi-metric"] = roi_metric
    return params


def metric_false_correlation_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `MetricFalseCorrelationParamsDict` 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("surface", None) is None:
        raise StyxValidationError("`surface` must not be None")
    if not isinstance(params["surface"], (pathlib.Path, str)):
        raise StyxValidationError(f'`surface` has the wrong type: Received `{type(params.get("surface", None))}` expected `InputPathType`')
    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("3D-dist", None) is None:
        raise StyxValidationError("`3D-dist` must not be None")
    if not isinstance(params["3D-dist"], (float, int)):
        raise StyxValidationError(f'`3D-dist` has the wrong type: Received `{type(params.get("3D-dist", None))}` expected `float`')
    if params.get("geo-outer", None) is None:
        raise StyxValidationError("`geo-outer` must not be None")
    if not isinstance(params["geo-outer"], (float, int)):
        raise StyxValidationError(f'`geo-outer` has the wrong type: Received `{type(params.get("geo-outer", None))}` expected `float`')
    if params.get("geo-inner", None) is None:
        raise StyxValidationError("`geo-inner` must not be None")
    if not isinstance(params["geo-inner"], (float, int)):
        raise StyxValidationError(f'`geo-inner` has the wrong type: Received `{type(params.get("geo-inner", None))}` expected `float`')
    if params.get("metric-out", None) is None:
        raise StyxValidationError("`metric-out` must not be None")
    if not isinstance(params["metric-out"], str):
        raise StyxValidationError(f'`metric-out` has the wrong type: Received `{type(params.get("metric-out", None))}` expected `str`')
    if params.get("text-out", None) is not None:
        if not isinstance(params["text-out"], str):
            raise StyxValidationError(f'`text-out` has the wrong type: Received `{type(params.get("text-out", None))}` expected `str | None`')
    if params.get("roi-metric", None) is not 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 | None`')


def metric_false_correlation_cargs(
    params: MetricFalseCorrelationParamsDict,
    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-false-correlation"
    ])
    cargs.append(execution.input_file(params.get("surface", None)))
    cargs.append(execution.input_file(params.get("metric-in", None)))
    cargs.append(str(params.get("3D-dist", None)))
    cargs.append(str(params.get("geo-outer", None)))
    cargs.append(str(params.get("geo-inner", None)))
    cargs.append(params.get("metric-out", None))
    if params.get("text-out", None) is not None:
        cargs.extend([
            "-dump-text",
            params.get("text-out", None)
        ])
    if params.get("roi-metric", None) is not None:
        cargs.extend([
            "-roi",
            execution.input_file(params.get("roi-metric", None))
        ])
    return cargs


def metric_false_correlation_outputs(
    params: MetricFalseCorrelationParamsDict,
    execution: Execution,
) -> MetricFalseCorrelationOutputs:
    """
    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 = MetricFalseCorrelationOutputs(
        root=execution.output_file("."),
        metric_out=execution.output_file(params.get("metric-out", None)),
    )
    return ret


def metric_false_correlation_execute(
    params: MetricFalseCorrelationParamsDict,
    runner: Runner | None = None,
) -> MetricFalseCorrelationOutputs:
    """
    COMPARE CORRELATION LOCALLY AND ACROSS/THROUGH SULCI/GYRI.
    
    For each vertex, compute the average correlation within a range of geodesic
    distances that don't cross a sulcus/gyrus, and the correlation to the
    closest vertex crossing a sulcus/gyrus. A vertex is considered to cross a
    sulcus/gyrus if the 3D distance is less than a third of the geodesic
    distance. The output file contains the ratio between these correlations, and
    some additional maps to help explain the ratio.
    
    Args:
        params: The parameters.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `MetricFalseCorrelationOutputs`).
    """
    metric_false_correlation_validate(params)
    runner = runner or get_global_runner()
    execution = runner.start_execution(METRIC_FALSE_CORRELATION_METADATA)
    params = execution.params(params)
    cargs = metric_false_correlation_cargs(params, execution)
    ret = metric_false_correlation_outputs(params, execution)
    execution.run(cargs)
    return ret


def metric_false_correlation(
    surface: InputPathType,
    metric_in: InputPathType,
    v_3_d_dist: float,
    geo_outer: float,
    geo_inner: float,
    metric_out: str,
    text_out: str | None = None,
    roi_metric: InputPathType | None = None,
    runner: Runner | None = None,
) -> MetricFalseCorrelationOutputs:
    """
    COMPARE CORRELATION LOCALLY AND ACROSS/THROUGH SULCI/GYRI.
    
    For each vertex, compute the average correlation within a range of geodesic
    distances that don't cross a sulcus/gyrus, and the correlation to the
    closest vertex crossing a sulcus/gyrus. A vertex is considered to cross a
    sulcus/gyrus if the 3D distance is less than a third of the geodesic
    distance. The output file contains the ratio between these correlations, and
    some additional maps to help explain the ratio.
    
    Args:
        surface: the surface to compute geodesic and 3D distance with.
        metric_in: the metric to correlate.
        v_3_d_dist: maximum 3D distance to check around each vertex.
        geo_outer: maximum geodesic distance to use for neighboring correlation.
        geo_inner: minimum geodesic distance to use for neighboring correlation.
        metric_out: the output metric.
        text_out: dump the raw measures used to a text file\
            \
            the output text file.
        roi_metric: select a region of interest that has data\
            \
            the region, as a metric file.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `MetricFalseCorrelationOutputs`).
    """
    params = metric_false_correlation_params(
        surface=surface,
        metric_in=metric_in,
        v_3_d_dist=v_3_d_dist,
        geo_outer=geo_outer,
        geo_inner=geo_inner,
        metric_out=metric_out,
        text_out=text_out,
        roi_metric=roi_metric,
    )
    return metric_false_correlation_execute(params, runner)


__all__ = [
    "METRIC_FALSE_CORRELATION_METADATA",
    "MetricFalseCorrelationOutputs",
    "MetricFalseCorrelationParamsDict",
    "MetricFalseCorrelationParamsDictTagged",
    "metric_false_correlation",
    "metric_false_correlation_execute",
    "metric_false_correlation_params",
]
