.. py:currentmodule:: mhi.psout

Combine Output Files
====================

Several related PSOUT files can be combined together into one large ``*.psout``
file.

Command Line
------------

Usage: ``py -m mhi.psout.combine [-h] [-o OUTPUT] [pattern]``

Combine multiple ``*.psout`` files into one single ``*.psout`` file.

``pattern`` is used to select the ``*.psout`` files to combine together.
It defaults to ``*/*.psout``, which finds all ``*.psout`` files in subdirectories
of the current working directory.

The ``OUTPUT`` defaults to a common prefix of all files which match the ``pattern``.

For example, if the directory ``Example.if18`` contains:

- ``Example_1_01.psout`` through ``Example_1_90.psout``,
- ``Example_2_01.psout`` through ``Example_2_90.psout``,
- ``Example_3_01.psout`` through ``Example_3_90.psout``

with one run in each file, then

- ``py -m mhi.psout.combine Example.if18\Example_1_*.psout`` would write in the
  current working directory ``Example_1.psout`` containing 90 runs from the 90
  matching ``*.psout`` files.
- ``py -m mhi.psout.combine Example.if18\*.psout`` would write in the current
  working directory ``Example.psout`` containing all runs from the 270
  ``*.psout`` files.
- ``py -m mhi.psout.combine`` might also write in the current working directory
  ``Example.psout`` containing all runs from the 270 ``*.psout`` files,
  assuming no other subdirectory containing ``*.psout`` files existed.

When runs are added to the output file, ``Source=`` and ``Run=`` attributes
are included in the run's variables, to identify where the run came from.

Method
------

.. autofunction:: mhi.psout.combine.combine
