``hifast.multi`` Multi-step Processing (Doppler Correction, etc)
================================================================

.. program:: python -m hifast.multi

Overview
--------

The ``hifast.multi`` module is a versatile tool for post-processing spectral data. It handles several critical steps in the reduction pipeline, including **RFI masking**, **reference frame correction** (Doppler correction), and **polarization merging**.

Processing Workflow
-------------------

1. **Reference Frame Correction**
   Raw telescope data is recorded in the Topocentric frame. To make the data scientifically useful, it usually needs to be corrected to a standard rest frame.
   
   *   **Enable Correction**: Set :option:`--fc` to True (default).
   *   **Target Frame**: Use :option:`--frame` to select the target frame. ``LSRK`` and ``HELIOCEN`` (Heliocentric) are lso supported.
   *   **Velocity Type**: Choose :option:`--vtype` for the velocity definition (``optical`` or ``radio``).
   
       .. note::
          This parameter is primarily for **tracking observations** or single-spectrum analysis. If you are proceeding to make a data cube with ``hifast.cube``, this step is optional because ``hifast.cube`` calculates velocity directly from frequency and ignores the velocity column generated here.

2. **RFI Masking**
   If your input file contains an ``is_rfi`` dataset (generated by an RFI flagging module), you can use :option:`--replace_rfi` (default: True) to replace the flagged data points with NaN. This ensures that contaminated data does not affect downstream analysis.

3. **Extrapolation Masking**
   If the coordinates were generated using `hifast.radec` with extrapolation, the file may contain an ``is_extrapo`` flag. Use :option:`--mask_extrapo` (default: False) to mask these extrapolated points.

4. **Polarization Merging**
   For unpolarized studies, the two linear polarizations (XX and YY) can be averaged to improve the signal-to-noise ratio. Use :option:`--merge_polar` (default: True) to perform this merge.

5. **Output**
   The module saves the processed data to a new HDF5 file. The filename is automatically suffixed based on the operations performed (e.g., ``-fc``).

Examples
--------

.. code-block:: bash

   # Standard usage: RFI masking, LSRK correction, and polarization merge
   python -m hifast.multi data/spec.hdf5

   # Change target frame to Heliocentric
   python -m hifast.multi data/spec.hdf5 --frame HELIOCEN

   # Disable polarization merging (keep XX and YY separate)
   python -m hifast.multi data/spec.hdf5 --merge_polar False

Full Parameter Reference
------------------------

.. tip::
   You can also view the full list of parameters and their descriptions directly in your terminal by running:
   
   .. code-block:: bash
   
      python -m hifast.multi --help

.. argparse::
   :module: hifast.multi
   :func: parser
   :prog: python -m hifast.multi
   :noepilog: