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

import typing
import pathlib
from styxdefs import *
import dataclasses

TIMING_TOOL_PY_METADATA = Metadata(
    id="e72448a163610156059a44280593b8076536b24a.boutiques",
    name="timing_tool.py",
    package="afni",
    container_image_tag="afni/afni_make_build:AFNI_24.2.06",
)


class TimingToolPyOutputs(typing.NamedTuple):
    """
    Output object returned when calling `timing_tool_py(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    output_timing_file: OutputPathType | None
    """Output timing file as specified"""
    timing_to_1_d_output: OutputPathType | None
    """Output 1D formatted stimulus data"""


def timing_tool_py(
    timing_file: InputPathType | None = None,
    output_file: str | None = None,
    run_length: list[float] | None = None,
    tr: float | None = None,
    offset: float | None = None,
    extend_file: InputPathType | None = None,
    sort: bool = False,
    scale_data: float | None = None,
    shift_to_run_offset: float | None = None,
    timing_to_1_d_file: str | None = None,
    stim_duration: float | None = None,
    multi_timing_files: list[InputPathType] | None = None,
    multi_show_isi_stats: bool = False,
    multi_show_timing: bool = False,
    show_timing: bool = False,
    multi_stim_duration: list[float] | None = None,
    round_times_frac: float | None = None,
    truncate_times: bool = False,
    multi_timing_event_list: str | None = None,
    runner: Runner | None = None,
) -> TimingToolPyOutputs:
    """
    Tool for manipulating and evaluating stimulus timing files.
    
    Author: AFNI Developers
    
    URL: https://afni.nimh.nih.gov/
    
    Args:
        timing_file: Specify a stimulus timing file to load.
        output_file: Specify the output timing file.
        run_length: Specify the run duration(s), in seconds.
        tr: Specify the time resolution in 1D output (in seconds).
        offset: Add OFFSET to every time in the main element.
        extend_file: Extend timing rows with those in NEW_FILE.
        sort: Sort the times, per row (run).
        scale_data: Multiply every stim time by SCALAR.
        shift_to_run_offset: Shift times so first event is at start of run.
        timing_to_1_d_file: Convert stim_times format to stim_file.
        stim_duration: Specify the stimulus duration, in seconds.
        multi_timing_files: Specify multiple timing files to load.
        multi_show_isi_stats: Display timing and ISI statistics for the\
            multiple timing files.
        multi_show_timing: Display info on multiple timing elements.
        show_timing: Display info on the main timing element.
        multi_stim_duration: Specify stimulus duration(s), in seconds, for\
            multiple timing elements.
        round_times_frac: Round times to multiples of the TR (0.0 <= FRAC <=\
            1.0).
        truncate_times: Truncate times to multiples of the TR.
        multi_timing_event_list: Create an event list file from multiple timing\
            files.
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `TimingToolPyOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(TIMING_TOOL_PY_METADATA)
    cargs = []
    cargs.append("timing_tool.py")
    if timing_file is not None:
        cargs.extend([
            "-timing",
            execution.input_file(timing_file)
        ])
    if output_file is not None:
        cargs.extend([
            "-write_timing",
            output_file
        ])
    if run_length is not None:
        cargs.extend([
            "-run_len",
            *map(str, run_length)
        ])
    if tr is not None:
        cargs.extend([
            "-tr",
            str(tr)
        ])
    if offset is not None:
        cargs.extend([
            "-add_offset",
            str(offset)
        ])
    if extend_file is not None:
        cargs.extend([
            "-extend",
            execution.input_file(extend_file)
        ])
    if sort:
        cargs.append("-sort")
    if scale_data is not None:
        cargs.extend([
            "-scale_data",
            str(scale_data)
        ])
    if shift_to_run_offset is not None:
        cargs.extend([
            "-shift_to_run_offset",
            str(shift_to_run_offset)
        ])
    if timing_to_1_d_file is not None:
        cargs.extend([
            "-timing_to_1D",
            timing_to_1_d_file
        ])
    if stim_duration is not None:
        cargs.extend([
            "-stim_dur",
            str(stim_duration)
        ])
    if multi_timing_files is not None:
        cargs.extend([
            "-multi_timing",
            *[execution.input_file(f) for f in multi_timing_files]
        ])
    if multi_show_isi_stats:
        cargs.append("-multi_show_isi_stats")
    if multi_show_timing:
        cargs.append("-multi_show_timing_ele")
    if show_timing:
        cargs.append("-show_timing_ele")
    if multi_stim_duration is not None:
        cargs.extend([
            "-multi_stim_dur",
            *map(str, multi_stim_duration)
        ])
    if round_times_frac is not None:
        cargs.extend([
            "-round_times",
            str(round_times_frac)
        ])
    if truncate_times:
        cargs.append("-truncate_times")
    if multi_timing_event_list is not None:
        cargs.extend([
            "-multi_timing_to_event_list",
            multi_timing_event_list
        ])
    ret = TimingToolPyOutputs(
        root=execution.output_file("."),
        output_timing_file=execution.output_file(output_file) if (output_file is not None) else None,
        timing_to_1_d_output=execution.output_file(timing_to_1_d_file) if (timing_to_1_d_file is not None) else None,
    )
    execution.run(cargs)
    return ret


__all__ = [
    "TIMING_TOOL_PY_METADATA",
    "TimingToolPyOutputs",
    "timing_tool_py",
]
