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

import typing
import pathlib
from styxdefs import *
import dataclasses

V_1DPLOT_PY_METADATA = Metadata(
    id="9a09a3b646afa4ae694c267932f8acdb6bcb6eec.boutiques",
    name="1dplot.py",
    package="afni",
    container_image_tag="afni/afni_make_build:AFNI_24.2.06",
)


class V1dplotPyOutputs(typing.NamedTuple):
    """
    Output object returned when calling `v_1dplot_py(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    output_image: OutputPathType
    """Output image file, default to .jpg"""


def v_1dplot_py(
    infiles: list[InputPathType],
    prefix: str,
    help_: bool = False,
    boxplot_on: bool = False,
    bplot_view: str | None = None,
    margin_off: bool = False,
    scale: list[str] | None = None,
    xfile: InputPathType | None = None,
    xvals: list[float] | None = None,
    yaxis: list[str] | None = None,
    ylabels: list[str] | None = None,
    ylabels_maxlen: float | None = None,
    legend_on: bool = False,
    legend_labels: list[str] | None = None,
    legend_locs: list[str] | None = None,
    xlabel: str | None = None,
    title: str | None = None,
    reverse_order: bool = False,
    sepscl: bool = False,
    one_graph: bool = False,
    dpi: float | None = None,
    figsize: list[float] | None = None,
    fontsize: float | None = None,
    fontfamily: str | None = None,
    fontstyles: str | None = None,
    colors: list[str] | None = None,
    patches: list[str] | None = None,
    censor_trs: list[str] | None = None,
    censor_files: list[InputPathType] | None = None,
    censor_hline: list[str] | None = None,
    censor_rgb: str | None = None,
    bkgd_color: str | None = None,
    runner: Runner | None = None,
) -> V1dplotPyOutputs:
    """
    This program is for making images to visualize columns of numbers from 1D text
    files. It uses Python, particularly matplotlib, to create plots.
    
    Author: AFNI Developers
    
    URL: https://afni.nimh.nih.gov/
    
    Args:
        infiles: One or more file names of text files. Each column in this file\
            will be treated as a separate time series for plotting.
        prefix: Output filename or prefix. Default output image type is .jpg.
        help_: See helpfile.
        boxplot_on: A fun feature to show an additional boxplot adjacent to\
            each time series.
        bplot_view: Adjust view for boxplots when using censoring.
        margin_off: Fill the plot frame completely, thus no labels, frame, or\
            titles will be visible.
        scale: Provide a list of scales to apply to the y-values.
        xfile: One way to input x-values explicitly: as a "1D" file containing\
            a single file of numbers.
        xvals: Provide exactly 3 numbers for x-values: start, stop, and\
            stepsize.
        yaxis: Optional range for each 'infile' y-axis.
        ylabels: Optional text labels for each 'infile' column.
        ylabels_maxlen: allows y-axis labels to wrap into multiple rows, each\
            of length <= which the user can decide.
        legend_on: Turn on the plotting of a legend in the plot(s).
        legend_labels: Optional legend labels, if using '-legend_on'.
        legend_locs: Optional legend locations, if using '-legend_on'.
        xlabel: Optional text labels for the abscissa/x-axis.
        title: Optional title for the set of plots.
        reverse_order: Reverses the order of plotted time series.
        sepscl: Make each graph have its own y-range.
        one_graph: Plot multiple infiles in a single subplot.
        dpi: Choose the output image's DPI. Default value is 150.
        figsize: Choose the output image's dimensions (units are inches).
        fontsize: Change image fontsize; default is 10.
        fontfamily: Change font-family used; default is monospace.
        fontstyles: Add a specific font name; should match with chosen\
            font-family.
        colors: Decide what color(s) to cycle through in plots (one or more).
        patches: Specify run lengths for background patches to distinguish runs.
        censor_trs: Specify time points where censoring has occurred using AFNI\
            index notation.
        censor_files: Specify time points where censoring has occurred using\
            one or more 1D files.
        censor_hline: Add a dotted horizontal line to the plot, representing\
            the censor threshold.
        censor_rgb: Choose the color of the censoring background; default is:\
            [1, 0.7, 0.7].
        bkgd_color: Change the background color outside of the plot windows.\
            Default is 0.9.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `V1dplotPyOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(V_1DPLOT_PY_METADATA)
    cargs = []
    cargs.append("1dplot.py")
    cargs.extend([
        "-infiles",
        *[execution.input_file(f) for f in infiles]
    ])
    cargs.extend([
        "-prefix",
        prefix
    ])
    if help_:
        cargs.append("-h")
    if boxplot_on:
        cargs.append("-boxplot_on")
    if bplot_view is not None:
        cargs.extend([
            "-bplot_view",
            bplot_view
        ])
    if margin_off:
        cargs.append("-margin_off")
    if scale is not None:
        cargs.extend([
            "-scale",
            *scale
        ])
    if xfile is not None:
        cargs.extend([
            "-xfile",
            execution.input_file(xfile)
        ])
    if xvals is not None:
        cargs.extend([
            "-xvals",
            *map(str, xvals)
        ])
    if yaxis is not None:
        cargs.extend([
            "-yaxis",
            *yaxis
        ])
    if ylabels is not None:
        cargs.extend([
            "-ylabels",
            *ylabels
        ])
    if ylabels_maxlen is not None:
        cargs.extend([
            "-ylabels_maxlen",
            str(ylabels_maxlen)
        ])
    if legend_on:
        cargs.append("-legend_on")
    if legend_labels is not None:
        cargs.extend([
            "-legend_labels",
            *legend_labels
        ])
    if legend_locs is not None:
        cargs.extend([
            "-legend_locs",
            *legend_locs
        ])
    if xlabel is not None:
        cargs.extend([
            "-xlabel",
            xlabel
        ])
    if title is not None:
        cargs.extend([
            "-title",
            title
        ])
    if reverse_order:
        cargs.append("-reverse_order")
    if sepscl:
        cargs.append("-sepscl")
    if one_graph:
        cargs.append("-one_graph")
    if dpi is not None:
        cargs.extend([
            "-dpi",
            str(dpi)
        ])
    if figsize is not None:
        cargs.extend([
            "-figsize",
            *map(str, figsize)
        ])
    if fontsize is not None:
        cargs.extend([
            "-fontsize",
            str(fontsize)
        ])
    if fontfamily is not None:
        cargs.extend([
            "-fontfamily",
            fontfamily
        ])
    if fontstyles is not None:
        cargs.extend([
            "-fontstyles",
            fontstyles
        ])
    if colors is not None:
        cargs.extend([
            "-colors",
            *colors
        ])
    if patches is not None:
        cargs.extend([
            "-patches",
            *patches
        ])
    if censor_trs is not None:
        cargs.extend([
            "-censor_trs",
            *censor_trs
        ])
    if censor_files is not None:
        cargs.extend([
            "-censor_files",
            *[execution.input_file(f) for f in censor_files]
        ])
    if censor_hline is not None:
        cargs.extend([
            "-censor_hline",
            *censor_hline
        ])
    if censor_rgb is not None:
        cargs.extend([
            "-censor_RGB",
            censor_rgb
        ])
    if bkgd_color is not None:
        cargs.extend([
            "-bkgd_color",
            bkgd_color
        ])
    ret = V1dplotPyOutputs(
        root=execution.output_file("."),
        output_image=execution.output_file(prefix + ".jpg"),
    )
    execution.run(cargs)
    return ret


__all__ = [
    "V1dplotPyOutputs",
    "V_1DPLOT_PY_METADATA",
    "v_1dplot_py",
]
