HiFAST Command-Line Tools: General Usage
========================================

This page describes the general usage patterns for all ``hifast`` subcommands. There are two main ways to execute a command, depending on whether you are processing a single file or multiple files in parallel.

1. Single-File Processing (`hifast.<subcommand>`)
-------------------------------------------------

The most direct way to run a `hifast` module is by using a dot (`.`) between `hifast` and the subcommand name. This syntax is intended for processing a **single input file**.

**Syntax:**

.. code-block:: bash

   python -m hifast.<subcommand> [input_file] [options]

**Example:**

.. code-block:: bash

   python -m hifast.sep my_data_M01.fits --frange 1400 1440

2. Parallel Multi-File Processing (`hifast <subcommand>`)
---------------------------------------------------------

To make processing large datasets easier, `hifast` provides a convenient wrapper to run a command on **multiple files in parallel**. This method uses a space between `hifast` and the subcommand name.

Under the hood, this wrapper uses `xargs` to execute the single-file command (`hifast.<subcommand>`) for each input file.

**Syntax:**

.. code-block:: bash

   python -m hifast <subcommand> -p <N> [input_file_1] [input_file_2] ... [options]

- The `-p <N>` or `--nproc <N>` flag is crucial here; it specifies that `N` processes should be run in parallel.

**Example:**

.. code-block:: bash

   python -m hifast sep -p 4 M01.fits M02.fits M03.fits M04.fits --frange 1400 1440

.. note::

   Most processing subcommands (like `sep`, `bld`, `rfi`, etc.) support this parallel wrapper.

Other Parallel Processing Methods
---------------------------------

For more complex workflows, such as chaining multiple commands together to run on a set of files, the ``hifast.sh`` script is available. Please see the :doc:`parallel` page for detailed examples of its use.

Getting Help
------------

To see a comprehensive list of all available parameters for any subcommand, you can use the `-h` or `--help` flag. This works for both syntaxes:

.. code-block:: bash

   # Get help for a specific module's parameters
   python -m hifast.sep -h | more

   # Get help for the parallel wrapper itself
   python -m hifast sep -h | more

Inspecting Output Files
-----------------------

The intermediate files generated by `hifast` are typically in the HDF5 format (`.hdf5`). You can inspect these files from the command line to see their contents and metadata, or visualize them to see the spectra.

**Command-Line Inspection**

To see the commands and parameters used to create a file, use `h5dump`:

.. code-block:: bash

   h5dump -g /Header /path/to/your_file.hdf5

To see a detailed, recursive listing of the contents of an HDF5 file, use `h5ls`:

.. code-block:: bash

   h5ls -r /path/to/your_file.hdf5

**Visual Inspection (Waterfall Plots)**

A common way to inspect the data is to create a "waterfall plot" (a 2D plot of frequency vs. time). You can do this using the dedicated ``hifast.waterfall`` subcommand.

For detailed instructions on how to generate these plots and view them with tools like CARTA, please see the :doc:`hifast.waterfall` page.