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

import typing
import pathlib
from styxdefs import *

SHBASIS_METADATA = Metadata(
    id="8d1c3a9e142d8ac3b0cfbca9e0fcd6b3d41e317e.boutiques",
    name="shbasis",
    package="mrtrix",
    container_image_tag="mrtrix3/mrtrix3:3.0.4",
)


_ShbasisConfigParamsDictNoTag = typing.TypedDict('_ShbasisConfigParamsDictNoTag', {
    "key": str,
    "value": str,
})
ShbasisConfigParamsDictTagged = typing.TypedDict('ShbasisConfigParamsDictTagged', {
    "@type": typing.Literal["config"],
    "key": str,
    "value": str,
})
ShbasisConfigParamsDict = _ShbasisConfigParamsDictNoTag | ShbasisConfigParamsDictTagged


_ShbasisParamsDictNoTag = typing.TypedDict('_ShbasisParamsDictNoTag', {
    "convert": typing.NotRequired[str | None],
    "info": bool,
    "quiet": bool,
    "debug": bool,
    "force": bool,
    "nthreads": typing.NotRequired[int | None],
    "config": typing.NotRequired[list[ShbasisConfigParamsDict] | None],
    "help": bool,
    "version": bool,
    "SH": list[InputPathType],
})
ShbasisParamsDictTagged = typing.TypedDict('ShbasisParamsDictTagged', {
    "@type": typing.Literal["mrtrix/shbasis"],
    "convert": typing.NotRequired[str | None],
    "info": bool,
    "quiet": bool,
    "debug": bool,
    "force": bool,
    "nthreads": typing.NotRequired[int | None],
    "config": typing.NotRequired[list[ShbasisConfigParamsDict] | None],
    "help": bool,
    "version": bool,
    "SH": list[InputPathType],
})
ShbasisParamsDict = _ShbasisParamsDictNoTag | ShbasisParamsDictTagged


def shbasis_config(
    key: str,
    value: str,
) -> ShbasisConfigParamsDictTagged:
    """
    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 shbasis_config_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `ShbasisConfigParamsDict` 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 shbasis_config_cargs(
    params: ShbasisConfigParamsDict,
    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 ShbasisOutputs(typing.NamedTuple):
    """
    Output object returned when calling `ShbasisParamsDict(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""


def shbasis_params(
    sh: list[InputPathType],
    convert: str | None = None,
    info: bool = False,
    quiet: bool = False,
    debug: bool = False,
    force: bool = False,
    nthreads: int | None = None,
    config: list[ShbasisConfigParamsDict] | None = None,
    help_: bool = False,
    version: bool = False,
) -> ShbasisParamsDictTagged:
    """
    Build parameters.
    
    Args:
        sh: the input image(s) of SH coefficients.
        convert: convert the image data in-place to the desired basis; options\
            are: old,new,force_oldtonew,force_newtoold.
        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/shbasis",
        "info": info,
        "quiet": quiet,
        "debug": debug,
        "force": force,
        "help": help_,
        "version": version,
        "SH": sh,
    }
    if convert is not None:
        params["convert"] = convert
    if nthreads is not None:
        params["nthreads"] = nthreads
    if config is not None:
        params["config"] = config
    return params


def shbasis_validate(
    params: typing.Any,
) -> None:
    """
    Validate parameters. Throws an error if `params` is not a valid
    `ShbasisParamsDict` 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("convert", None) is not None:
        if not isinstance(params["convert"], str):
            raise StyxValidationError(f'`convert` has the wrong type: Received `{type(params.get("convert", None))}` expected `str | None`')
    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[ShbasisConfigParamsDict] | None`')
        for e in params["config"]:
            shbasis_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("SH", None) is None:
        raise StyxValidationError("`SH` must not be None")
    if not isinstance(params["SH"], list):
        raise StyxValidationError(f'`SH` has the wrong type: Received `{type(params.get("SH", None))}` expected `list[InputPathType]`')
    for e in params["SH"]:
        if not isinstance(e, (pathlib.Path, str)):
            raise StyxValidationError(f'`SH` has the wrong type: Received `{type(params.get("SH", None))}` expected `list[InputPathType]`')


def shbasis_cargs(
    params: ShbasisParamsDict,
    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("shbasis")
    if params.get("convert", None) is not None:
        cargs.extend([
            "-convert",
            params.get("convert", None)
        ])
    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 [shbasis_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.extend([execution.input_file(f) for f in params.get("SH", None)])
    return cargs


def shbasis_outputs(
    params: ShbasisParamsDict,
    execution: Execution,
) -> ShbasisOutputs:
    """
    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 = ShbasisOutputs(
        root=execution.output_file("."),
    )
    return ret


def shbasis_execute(
    params: ShbasisParamsDict,
    runner: Runner | None = None,
) -> ShbasisOutputs:
    """
    shbasis
    
    Examine the values in spherical harmonic images to estimate (and optionally
    change) the SH basis used.
    
    In previous versions of MRtrix, the convention used for storing spherical
    harmonic coefficients was a non-orthonormal basis (the m!=0 coefficients
    were a factor of sqrt(2) too large). This error has been rectified in newer
    versions of MRtrix, but will cause issues if processing SH data that was
    generated using an older version of MRtrix (or vice-versa).
    
    This command provides a mechanism for testing the basis used in storage of
    image data representing a spherical harmonic series per voxel, and allows
    the user to forcibly modify the raw image data to conform to the desired
    basis.
    
    Note that the "force_*" conversion choices should only be used in cases
    where this command has previously been unable to automatically determine the
    SH basis from the image data, but the user themselves are confident of the
    SH basis of the data.
    
    The spherical harmonic coefficients are stored according the conventions
    described the main documentation, which can be found at the following link:
    https://mrtrix.readthedocs.io/en/3.0.4/concepts/spherical_harmonics.html
    
    References:
    
    .
    
    Author: MRTrix3 Developers
    
    URL: https://www.mrtrix.org/
    
    Args:
        params: The parameters.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `ShbasisOutputs`).
    """
    shbasis_validate(params)
    runner = runner or get_global_runner()
    execution = runner.start_execution(SHBASIS_METADATA)
    params = execution.params(params)
    cargs = shbasis_cargs(params, execution)
    ret = shbasis_outputs(params, execution)
    execution.run(cargs)
    return ret


def shbasis(
    sh: list[InputPathType],
    convert: str | None = None,
    info: bool = False,
    quiet: bool = False,
    debug: bool = False,
    force: bool = False,
    nthreads: int | None = None,
    config: list[ShbasisConfigParamsDict] | None = None,
    help_: bool = False,
    version: bool = False,
    runner: Runner | None = None,
) -> ShbasisOutputs:
    """
    shbasis
    
    Examine the values in spherical harmonic images to estimate (and optionally
    change) the SH basis used.
    
    In previous versions of MRtrix, the convention used for storing spherical
    harmonic coefficients was a non-orthonormal basis (the m!=0 coefficients
    were a factor of sqrt(2) too large). This error has been rectified in newer
    versions of MRtrix, but will cause issues if processing SH data that was
    generated using an older version of MRtrix (or vice-versa).
    
    This command provides a mechanism for testing the basis used in storage of
    image data representing a spherical harmonic series per voxel, and allows
    the user to forcibly modify the raw image data to conform to the desired
    basis.
    
    Note that the "force_*" conversion choices should only be used in cases
    where this command has previously been unable to automatically determine the
    SH basis from the image data, but the user themselves are confident of the
    SH basis of the data.
    
    The spherical harmonic coefficients are stored according the conventions
    described the main documentation, which can be found at the following link:
    https://mrtrix.readthedocs.io/en/3.0.4/concepts/spherical_harmonics.html
    
    References:
    
    .
    
    Author: MRTrix3 Developers
    
    URL: https://www.mrtrix.org/
    
    Args:
        sh: the input image(s) of SH coefficients.
        convert: convert the image data in-place to the desired basis; options\
            are: old,new,force_oldtonew,force_newtoold.
        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 `ShbasisOutputs`).
    """
    params = shbasis_params(
        convert=convert,
        info=info,
        quiet=quiet,
        debug=debug,
        force=force,
        nthreads=nthreads,
        config=config,
        help_=help_,
        version=version,
        sh=sh,
    )
    return shbasis_execute(params, runner)


__all__ = [
    "SHBASIS_METADATA",
    "ShbasisConfigParamsDict",
    "ShbasisConfigParamsDictTagged",
    "ShbasisOutputs",
    "ShbasisParamsDict",
    "ShbasisParamsDictTagged",
    "shbasis",
    "shbasis_config",
    "shbasis_execute",
    "shbasis_params",
]
