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

import typing
import pathlib
from styxdefs import *
import dataclasses

MERGE_METADATA = Metadata(
    id="cbb6884a58b75dfd14525a8a1395536bd76c6bd8.boutiques",
    name="merge",
    package="fsl",
    container_image_tag="mcin/fsl:6.0.5",
)


class MergeOutputs(typing.NamedTuple):
    """
    Output object returned when calling `merge(...)`.
    """
    root: OutputPathType
    """Output root folder. This is the root folder for all outputs."""
    output_file: OutputPathType
    """Merged output file."""


def merge(
    merged_file: str,
    in_files: list[InputPathType],
    dimension: typing.Literal["t", "x", "y", "z", "a"] | None = None,
    dimension_tr: bool = False,
    tr: float | None = None,
    volume_number: int | None = None,
    runner: Runner | None = None,
) -> MergeOutputs:
    """
    Concatenate image files into a single output. This concatenation can be in time,
    or in X, Y or Z. All image dimensions (except for the one being concatenated
    over) must be the same in all input images. For example, this can be used to
    take multiple 3D files (eg as output by SPM) and create a single 4D image file.
    
    Author: Oxford Centre for Functional MRI of the Brain (FMRIB)
    
    URL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Fslutils
    
    Args:
        merged_file: Merged output file.
        in_files: A list of images to merge together.
        dimension: 't' or 'x' or 'y' or 'z' or 'a'. Dimension along which to\
            merge, optionally set tr input when dimension is t.
        dimension_tr: Concatenate images in time and set out image tr to final\
            option value.
        tr: Use to specify tr in seconds (default is 1.00 sec), overrides\
            dimension and sets it to tr.
        volume_number: Only use volume <N> from each input file (first volume\
            is 0 and not 1).
        runner: Command runner.
    Returns:
        NamedTuple of outputs (described in `MergeOutputs`).
    """
    runner = runner or get_global_runner()
    execution = runner.start_execution(MERGE_METADATA)
    cargs = []
    cargs.append("fslmerge")
    if dimension is not None:
        cargs.append("-" + dimension)
    if dimension_tr:
        cargs.append("-tr")
    cargs.append(merged_file)
    cargs.extend([execution.input_file(f) for f in in_files])
    if tr is not None:
        cargs.append(str(tr))
    if volume_number is not None:
        cargs.extend([
            "-n",
            str(volume_number)
        ])
    ret = MergeOutputs(
        root=execution.output_file("."),
        output_file=execution.output_file(merged_file),
    )
    execution.run(cargs)
    return ret


__all__ = [
    "MERGE_METADATA",
    "MergeOutputs",
    "merge",
]
