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

import typing
import pathlib
from styxdefs import *

TCKSAMPLE_METADATA = Metadata(
    id="274c00456de615fd846529a52bdcb4684c1c52eb.boutiques",
    name="tcksample",
    package="mrtrix",
    container_image_tag="mrtrix3/mrtrix3:3.0.4",
)


_TcksampleConfigParamsDictNoTag = typing.TypedDict('_TcksampleConfigParamsDictNoTag', {
    "key": str,
    "value": str,
})
TcksampleConfigParamsDictTagged = typing.TypedDict('TcksampleConfigParamsDictTagged', {
    "@type": typing.Literal["config"],
    "key": str,
    "value": str,
})
TcksampleConfigParamsDict = _TcksampleConfigParamsDictNoTag | TcksampleConfigParamsDictTagged


_TcksampleParamsDictNoTag = typing.TypedDict('_TcksampleParamsDictNoTag', {
    "stat_tck": typing.NotRequired[str | None],
    "nointerp": bool,
    "precise": bool,
    "use_tdi_fraction": bool,
    "info": bool,
    "quiet": bool,
    "debug": bool,
    "force": bool,
    "nthreads": typing.NotRequired[int | None],
    "config": typing.NotRequired[list[TcksampleConfigParamsDict] | None],
    "help": bool,
    "version": bool,
    "tracks": InputPathType,
    "image": InputPathType,
    "values": str,
})
TcksampleParamsDictTagged = typing.TypedDict('TcksampleParamsDictTagged', {
    "@type": typing.Literal["mrtrix/tcksample"],
    "stat_tck": typing.NotRequired[str | None],
    "nointerp": bool,
    "precise": bool,
    "use_tdi_fraction": bool,
    "info": bool,
    "quiet": bool,
    "debug": bool,
    "force": bool,
    "nthreads": typing.NotRequired[int | None],
    "config": typing.NotRequired[list[TcksampleConfigParamsDict] | None],
    "help": bool,
    "version": bool,
    "tracks": InputPathType,
    "image": InputPathType,
    "values": str,
})
TcksampleParamsDict = _TcksampleParamsDictNoTag | TcksampleParamsDictTagged


def tcksample_config(
    key: str,
    value: str,
) -> TcksampleConfigParamsDictTagged:
    """
    Build parameters.
    
    Args:
        key: temporarily set the value of an MRtrix config file entry.
        value: temporarily set the value of an MRtrix config file entry.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "config",
        "key": key,
        "value": value,
    }
    return params


def tcksample_config_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `TcksampleConfigParamsDict` 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("key", None) is None:
        raise StyxValidationError("`key` must not be None")
    if not isinstance(params["key"], str):
        raise StyxValidationError(f'`key` has the wrong type: Received `{type(params.get("key", None))}` expected `str`')
    if params.get("value", None) is None:
        raise StyxValidationError("`value` must not be None")
    if not isinstance(params["value"], str):
        raise StyxValidationError(f'`value` has the wrong type: Received `{type(params.get("value", None))}` expected `str`')


def tcksample_config_cargs(
    params: TcksampleConfigParamsDict,
    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("-config")
    cargs.append(params.get("key", None))
    cargs.append(params.get("value", None))
    return cargs


class TcksampleOutputs(typing.NamedTuple):
    """
    Output object returned when calling `TcksampleParamsDict(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    values_: OutputPathType
    """the output sampled values"""


def tcksample_params(
    tracks: InputPathType,
    image: InputPathType,
    values_: str,
    stat_tck: str | None = None,
    nointerp: bool = False,
    precise: bool = False,
    use_tdi_fraction: bool = False,
    info: bool = False,
    quiet: bool = False,
    debug: bool = False,
    force: bool = False,
    nthreads: int | None = None,
    config: list[TcksampleConfigParamsDict] | None = None,
    help_: bool = False,
    version: bool = False,
) -> TcksampleParamsDictTagged:
    """
    Build parameters.
    
    Args:
        tracks: the input track file.
        image: the image to be sampled.
        values_: the output sampled values.
        stat_tck: compute some statistic from the values along each streamline\
            (options are: mean,median,min,max).
        nointerp: do not use trilinear interpolation when sampling image values.
        precise: use the precise mechanism for mapping streamlines to voxels\
            (obviates the need for trilinear interpolation) (only applicable if\
            some per-streamline statistic is requested).
        use_tdi_fraction: each streamline is assigned a fraction of the image\
            intensity in each voxel based on the fraction of the track density\
            contributed by that streamline (this is only appropriate for processing\
            a whole-brain tractogram, and images for which the quantiative\
            parameter is additive).
        info: display information messages.
        quiet: do not display information messages or progress status;\
            alternatively, this can be achieved by setting the MRTRIX_QUIET\
            environment variable to a non-empty string.
        debug: display debugging messages.
        force: force overwrite of output files (caution: using the same file as\
            input and output might cause unexpected behaviour).
        nthreads: use this number of threads in multi-threaded applications\
            (set to 0 to disable multi-threading).
        config: temporarily set the value of an MRtrix config file entry.
        help_: display this information page and exit.
        version: display version information and exit.
    Returns:
        Parameter dictionary
    """
    params = {
        "@type": "mrtrix/tcksample",
        "nointerp": nointerp,
        "precise": precise,
        "use_tdi_fraction": use_tdi_fraction,
        "info": info,
        "quiet": quiet,
        "debug": debug,
        "force": force,
        "help": help_,
        "version": version,
        "tracks": tracks,
        "image": image,
        "values": values_,
    }
    if stat_tck is not None:
        params["stat_tck"] = stat_tck
    if nthreads is not None:
        params["nthreads"] = nthreads
    if config is not None:
        params["config"] = config
    return params


def tcksample_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `TcksampleParamsDict` 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("stat_tck", None) is not None:
        if not isinstance(params["stat_tck"], str):
            raise StyxValidationError(f'`stat_tck` has the wrong type: Received `{type(params.get("stat_tck", None))}` expected `str | None`')
    if params.get("nointerp", False) is None:
        raise StyxValidationError("`nointerp` must not be None")
    if not isinstance(params["nointerp"], bool):
        raise StyxValidationError(f'`nointerp` has the wrong type: Received `{type(params.get("nointerp", False))}` expected `bool`')
    if params.get("precise", False) is None:
        raise StyxValidationError("`precise` must not be None")
    if not isinstance(params["precise"], bool):
        raise StyxValidationError(f'`precise` has the wrong type: Received `{type(params.get("precise", False))}` expected `bool`')
    if params.get("use_tdi_fraction", False) is None:
        raise StyxValidationError("`use_tdi_fraction` must not be None")
    if not isinstance(params["use_tdi_fraction"], bool):
        raise StyxValidationError(f'`use_tdi_fraction` has the wrong type: Received `{type(params.get("use_tdi_fraction", False))}` expected `bool`')
    if params.get("info", False) is None:
        raise StyxValidationError("`info` must not be None")
    if not isinstance(params["info"], bool):
        raise StyxValidationError(f'`info` has the wrong type: Received `{type(params.get("info", False))}` expected `bool`')
    if params.get("quiet", False) is None:
        raise StyxValidationError("`quiet` must not be None")
    if not isinstance(params["quiet"], bool):
        raise StyxValidationError(f'`quiet` has the wrong type: Received `{type(params.get("quiet", False))}` expected `bool`')
    if params.get("debug", False) is None:
        raise StyxValidationError("`debug` must not be None")
    if not isinstance(params["debug"], bool):
        raise StyxValidationError(f'`debug` has the wrong type: Received `{type(params.get("debug", False))}` expected `bool`')
    if params.get("force", False) is None:
        raise StyxValidationError("`force` must not be None")
    if not isinstance(params["force"], bool):
        raise StyxValidationError(f'`force` has the wrong type: Received `{type(params.get("force", False))}` expected `bool`')
    if params.get("nthreads", None) is not None:
        if not isinstance(params["nthreads"], int):
            raise StyxValidationError(f'`nthreads` has the wrong type: Received `{type(params.get("nthreads", None))}` expected `int | None`')
    if params.get("config", None) is not None:
        if not isinstance(params["config"], list):
            raise StyxValidationError(f'`config` has the wrong type: Received `{type(params.get("config", None))}` expected `list[TcksampleConfigParamsDict] | None`')
        for e in params["config"]:
            tcksample_config_validate(e)
    if params.get("help", False) is None:
        raise StyxValidationError("`help` must not be None")
    if not isinstance(params["help"], bool):
        raise StyxValidationError(f'`help` has the wrong type: Received `{type(params.get("help", False))}` expected `bool`')
    if params.get("version", False) is None:
        raise StyxValidationError("`version` must not be None")
    if not isinstance(params["version"], bool):
        raise StyxValidationError(f'`version` has the wrong type: Received `{type(params.get("version", False))}` expected `bool`')
    if params.get("tracks", None) is None:
        raise StyxValidationError("`tracks` must not be None")
    if not isinstance(params["tracks"], (pathlib.Path, str)):
        raise StyxValidationError(f'`tracks` has the wrong type: Received `{type(params.get("tracks", None))}` expected `InputPathType`')
    if params.get("image", None) is None:
        raise StyxValidationError("`image` must not be None")
    if not isinstance(params["image"], (pathlib.Path, str)):
        raise StyxValidationError(f'`image` has the wrong type: Received `{type(params.get("image", None))}` expected `InputPathType`')
    if params.get("values", None) is None:
        raise StyxValidationError("`values` must not be None")
    if not isinstance(params["values"], str):
        raise StyxValidationError(f'`values` has the wrong type: Received `{type(params.get("values", None))}` expected `str`')


def tcksample_cargs(
    params: TcksampleParamsDict,
    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("tcksample")
    if params.get("stat_tck", None) is not None:
        cargs.extend([
            "-stat_tck",
            params.get("stat_tck", None)
        ])
    if params.get("nointerp", False):
        cargs.append("-nointerp")
    if params.get("precise", False):
        cargs.append("-precise")
    if params.get("use_tdi_fraction", False):
        cargs.append("-use_tdi_fraction")
    if params.get("info", False):
        cargs.append("-info")
    if params.get("quiet", False):
        cargs.append("-quiet")
    if params.get("debug", False):
        cargs.append("-debug")
    if params.get("force", False):
        cargs.append("-force")
    if params.get("nthreads", None) is not None:
        cargs.extend([
            "-nthreads",
            str(params.get("nthreads", None))
        ])
    if params.get("config", None) is not None:
        cargs.extend([a for c in [tcksample_config_cargs(s, execution) for s in params.get("config", None)] for a in c])
    if params.get("help", False):
        cargs.append("-help")
    if params.get("version", False):
        cargs.append("-version")
    cargs.append(execution.input_file(params.get("tracks", None)))
    cargs.append(execution.input_file(params.get("image", None)))
    cargs.append(params.get("values", None))
    return cargs


def tcksample_outputs(
    params: TcksampleParamsDict,
    execution: Execution,
) -> TcksampleOutputs:
    """
    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 = TcksampleOutputs(
        root=execution.output_file("."),
        values_=execution.output_file(params.get("values", None)),
    )
    return ret


def tcksample_execute(
    params: TcksampleParamsDict,
    runner: Runner | None = None,
) -> TcksampleOutputs:
    """
    tcksample
    
    Sample values of an associated image along tracks.
    
    By default, the value of the underlying image at each point along the track
    is written to either an ASCII file (with all values for each track on the
    same line), or a track scalar file (.tsf). Alternatively, some statistic can
    be taken from the values along each streamline and written to a vector file.
    
    References:
    
    * If using -precise option: Smith, R. E.; Tournier, J.-D.; Calamante, F. &
    Connelly, A. SIFT: Spherical-deconvolution informed filtering of
    tractograms. NeuroImage, 2013, 67, 298-312.
    
    Author: MRTrix3 Developers
    
    URL: https://www.mrtrix.org/
    
    Args:
        params: The parameters.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `TcksampleOutputs`).
    """
    tcksample_validate(params)
    runner = runner or get_global_runner()
    execution = runner.start_execution(TCKSAMPLE_METADATA)
    params = execution.params(params)
    cargs = tcksample_cargs(params, execution)
    ret = tcksample_outputs(params, execution)
    execution.run(cargs)
    return ret


def tcksample(
    tracks: InputPathType,
    image: InputPathType,
    values_: str,
    stat_tck: str | None = None,
    nointerp: bool = False,
    precise: bool = False,
    use_tdi_fraction: bool = False,
    info: bool = False,
    quiet: bool = False,
    debug: bool = False,
    force: bool = False,
    nthreads: int | None = None,
    config: list[TcksampleConfigParamsDict] | None = None,
    help_: bool = False,
    version: bool = False,
    runner: Runner | None = None,
) -> TcksampleOutputs:
    """
    tcksample
    
    Sample values of an associated image along tracks.
    
    By default, the value of the underlying image at each point along the track
    is written to either an ASCII file (with all values for each track on the
    same line), or a track scalar file (.tsf). Alternatively, some statistic can
    be taken from the values along each streamline and written to a vector file.
    
    References:
    
    * If using -precise option: Smith, R. E.; Tournier, J.-D.; Calamante, F. &
    Connelly, A. SIFT: Spherical-deconvolution informed filtering of
    tractograms. NeuroImage, 2013, 67, 298-312.
    
    Author: MRTrix3 Developers
    
    URL: https://www.mrtrix.org/
    
    Args:
        tracks: the input track file.
        image: the image to be sampled.
        values_: the output sampled values.
        stat_tck: compute some statistic from the values along each streamline\
            (options are: mean,median,min,max).
        nointerp: do not use trilinear interpolation when sampling image values.
        precise: use the precise mechanism for mapping streamlines to voxels\
            (obviates the need for trilinear interpolation) (only applicable if\
            some per-streamline statistic is requested).
        use_tdi_fraction: each streamline is assigned a fraction of the image\
            intensity in each voxel based on the fraction of the track density\
            contributed by that streamline (this is only appropriate for processing\
            a whole-brain tractogram, and images for which the quantiative\
            parameter is additive).
        info: display information messages.
        quiet: do not display information messages or progress status;\
            alternatively, this can be achieved by setting the MRTRIX_QUIET\
            environment variable to a non-empty string.
        debug: display debugging messages.
        force: force overwrite of output files (caution: using the same file as\
            input and output might cause unexpected behaviour).
        nthreads: use this number of threads in multi-threaded applications\
            (set to 0 to disable multi-threading).
        config: temporarily set the value of an MRtrix config file entry.
        help_: display this information page and exit.
        version: display version information and exit.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `TcksampleOutputs`).
    """
    params = tcksample_params(
        stat_tck=stat_tck,
        nointerp=nointerp,
        precise=precise,
        use_tdi_fraction=use_tdi_fraction,
        info=info,
        quiet=quiet,
        debug=debug,
        force=force,
        nthreads=nthreads,
        config=config,
        help_=help_,
        version=version,
        tracks=tracks,
        image=image,
        values_=values_,
    )
    return tcksample_execute(params, runner)


__all__ = [
    "TCKSAMPLE_METADATA",
    "TcksampleConfigParamsDict",
    "TcksampleConfigParamsDictTagged",
    "TcksampleOutputs",
    "TcksampleParamsDict",
    "TcksampleParamsDictTagged",
    "tcksample",
    "tcksample_config",
    "tcksample_execute",
    "tcksample_params",
]
