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

import typing
import pathlib
from styxdefs import *
import dataclasses

V_3D_ROISTATS_METADATA = Metadata(
    id="837cb344ffaa7fe7aa684a462d2ab5e156a15242.boutiques",
    name="3dROIstats",
    package="afni",
    container_image_tag="afni/afni_make_build:AFNI_24.2.06",
)


class V3dRoistatsOutputs(typing.NamedTuple):
    """
    Output object returned when calling `v_3d_roistats(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    out_file: OutputPathType
    """Output file."""
    out_file_: OutputPathType
    """Output tab-separated values file."""


def v_3d_roistats(
    in_file: InputPathType,
    mask: InputPathType | None = None,
    debug: bool = False,
    format1_d: bool = False,
    format1_dr: bool = False,
    mask_f2short: bool = False,
    mask_file: InputPathType | None = None,
    nobriklab: bool = False,
    nomeanout: bool = False,
    num_roi: int | None = None,
    quiet: bool = False,
    roisel: InputPathType | None = None,
    stat_: list[InputPathType] | None = None,
    zerofill: str | None = None,
    runner: Runner | None = None,
) -> V3dRoistatsOutputs:
    """
    Display statistics over masked regions.
    
    Author: AFNI Team
    
    URL: https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dROIstats.html
    
    Args:
        in_file: Input dataset.
        mask: Input mask.
        debug: Print debug information.
        format1_d: Output results in a 1d format that includes commented\
            labels.
        format1_dr: Output results in a 1d format that includes uncommented\
            labels. may not work optimally with typical 1d functions, but is useful\
            for r functions.
        mask_f2short: Tells the program to convert a float mask to short\
            integers, by simple rounding.
        mask_file: Input mask.
        nobriklab: Do not print the sub-brick label next to its index.
        nomeanout: Do not include the (zero-inclusive) mean among computed\
            stats.
        num_roi: Forces the assumption that the mask dataset's rois are denoted\
            by 1 to n inclusive. normally, the program figures out the rois on its\
            own. this option is useful if a) you are certain that the mask dataset\
            has no values outside the range [0 n], b) there may be some rois\
            missing between [1 n] in the mask data-set and c) you want those\
            columns in the output any-way so the output lines up with the output\
            from other invocations of 3droistats.
        quiet: Execute quietly.
        roisel: Only considers rois denoted by values found in the specified\
            file. note that the order of the rois as specified in the file is not\
            preserved. so an sel.1d of '2 8 20' produces the same output as '8 20\
            2'.
        stat_: A list of items which are 'mean' or 'sum' or 'voxels' or\
            'minmax' or 'sigma' or 'median' or 'mode' or 'summary' or 'zerominmax'\
            or 'zerosigma' or 'zeromedian' or 'zeromode'. Statistics to compute.\
            options include: * mean = compute the mean using only non_zero voxels.\
            implies the opposite for the mean computed by default. * median =\
            compute the median of nonzero voxels * mode = compute the mode of\
            nonzero voxels. (integral valued sets only) * minmax = compute the\
            min/max of nonzero voxels * sum = compute the sum using only nonzero\
            voxels. * voxels = compute the number of nonzero voxels * sigma =\
            compute the standard deviation of nonzero voxelsstatistics that include\
            zero-valued voxels: * zerominmax = compute the min/max of all voxels. *\
            zerosigma = compute the standard deviation of all voxels. * zeromedian\
            = compute the median of all voxels. * zeromode = compute the mode of\
            all voxels. * summary = only output a summary line with the grand mean\
            across all briks in the input dataset. this option cannot be used with\
            nomeanout.more that one option can be specified.
        zerofill: For roi labels not found, use the provided string instead of\
            a '0' in the output file. only active if `num_roi` is enabled.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `V3dRoistatsOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(V_3D_ROISTATS_METADATA)
    cargs = []
    cargs.append("3dROIstats")
    cargs.append(execution.input_file(in_file))
    if mask is not None:
        cargs.extend([
            "-mask",
            execution.input_file(mask)
        ])
    cargs.append("[OUT_FILE]")
    if debug:
        cargs.append("-debug")
    if format1_d:
        cargs.append("-1Dformat")
    if format1_dr:
        cargs.append("-1DRformat")
    if mask_f2short:
        cargs.append("-mask_f2short")
    if mask_file is not None:
        cargs.extend([
            "-mask",
            execution.input_file(mask_file)
        ])
    if nobriklab:
        cargs.append("-nobriklab")
    if nomeanout:
        cargs.append("-nomeanout")
    if num_roi is not None:
        cargs.extend([
            "-numroi",
            str(num_roi)
        ])
    if quiet:
        cargs.append("-quiet")
    if roisel is not None:
        cargs.extend([
            "-roisel",
            execution.input_file(roisel)
        ])
    if stat_ is not None:
        cargs.extend([execution.input_file(f) for f in stat_])
    if zerofill is not None:
        cargs.extend([
            "-zerofill",
            zerofill
        ])
    ret = V3dRoistatsOutputs(
        root=execution.output_file("."),
        out_file=execution.output_file(pathlib.Path(in_file).name + "_roistat.1D"),
        out_file_=execution.output_file("out_file"),
    )
    execution.run(cargs)
    return ret


__all__ = [
    "V3dRoistatsOutputs",
    "V_3D_ROISTATS_METADATA",
    "v_3d_roistats",
]
