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

import typing
import pathlib
from styxdefs import *
import dataclasses

V_3D_HIST_METADATA = Metadata(
    id="5dff8f7ac913ce4a3781c6d59d7827316323eded.boutiques",
    name="3dHist",
    package="afni",
    container_image_tag="afni/afni_make_build:AFNI_24.2.06",
)


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


def v_3d_hist(
    input_: InputPathType,
    mask_dset: InputPathType | None = None,
    mask_range: list[float] | None = None,
    cmask: str | None = None,
    hist_file: InputPathType | None = None,
    prefix: str | None = None,
    equalized: str | None = None,
    nbin: float | None = None,
    min_: float | None = None,
    max_: float | None = None,
    binwidth: float | None = None,
    ignore_out: bool = False,
    range_hist: InputPathType | None = None,
    showhist: bool = False,
    at_val: float | None = None,
    get_params: str | None = None,
    voxvol: float | None = None,
    val_at: str | None = None,
    quiet: bool = False,
    runner: Runner | None = None,
) -> V3dHistOutputs:
    """
    Computes histograms using functions for generating priors.
    
    Author: AFNI Developers
    
    URL: https://afni.nimh.nih.gov/
    
    Args:
        input_: Dataset providing values for histogram.
        mask_dset: Provide mask dataset to select subset of input.
        mask_range: Specify the range of values to consider from MSET. Default\
            is anything non-zero.
        cmask: Provide cmask expression. Voxels where expression is 0 are\
            excluded from computations.
        hist_file: Read this previously created histogram instead of forming\
            one from DSET.
        prefix: Write histogram to niml file called PREF.niml.hist.
        equalized: Write a histogram equalized version of the input dataset.
        nbin: Use K bins.
        min_: Minimum intensity.
        max_: Maximum intensity.
        binwidth: Bin width.
        ignore_out: Do not count samples outside the user specified range.
        range_hist: Use previously created histogram to set range and binwidth\
            parameters.
        showhist: Display histogram to stdout.
        at_val: Set the value at which you want histogram values.
        get_params: Return the desired properties at a given value. You can\
            select multiple properties.
        voxvol: Specify voxel volume in mm^3. To be used with upvol.
        val_at: Return the value where histogram property PAR is equal to\
            PARVAL. PAR can be: cdf, rcdf, ncdf, nrcdf, upvol.
        quiet: Return a concise output to simplify parsing.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `V3dHistOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(V_3D_HIST_METADATA)
    cargs = []
    cargs.append("3dHist")
    cargs.append(execution.input_file(input_))
    if mask_dset is not None:
        cargs.extend([
            "-mask",
            execution.input_file(mask_dset)
        ])
    if mask_range is not None:
        cargs.extend([
            "-mask_range",
            *map(str, mask_range)
        ])
    if cmask is not None:
        cargs.extend([
            "-cmask",
            cmask
        ])
    if hist_file is not None:
        cargs.extend([
            "-thishist",
            execution.input_file(hist_file)
        ])
    if prefix is not None:
        cargs.extend([
            "-prefix",
            prefix
        ])
    if equalized is not None:
        cargs.extend([
            "-equalized",
            equalized
        ])
    if nbin is not None:
        cargs.extend([
            "-nbin",
            str(nbin)
        ])
    if min_ is not None:
        cargs.extend([
            "-min",
            str(min_)
        ])
    if max_ is not None:
        cargs.extend([
            "-max",
            str(max_)
        ])
    if binwidth is not None:
        cargs.extend([
            "-binwidth",
            str(binwidth)
        ])
    if ignore_out:
        cargs.append("-ignore_out")
    if range_hist is not None:
        cargs.extend([
            "-rhist",
            execution.input_file(range_hist)
        ])
    if showhist:
        cargs.append("-showhist")
    if at_val is not None:
        cargs.extend([
            "-at",
            str(at_val)
        ])
    if get_params is not None:
        cargs.extend([
            "-get",
            get_params
        ])
    if voxvol is not None:
        cargs.extend([
            "-voxvol",
            str(voxvol)
        ])
    if val_at is not None:
        cargs.extend([
            "-val_at",
            val_at
        ])
    if quiet:
        cargs.append("-quiet")
    ret = V3dHistOutputs(
        root=execution.output_file("."),
    )
    execution.run(cargs)
    return ret


__all__ = [
    "V3dHistOutputs",
    "V_3D_HIST_METADATA",
    "v_3d_hist",
]
