Quickstart
==========

Once installed, you can activate the virtual environment inside the project directory
and run the CLI tool. The help message for the CLI can be accessed via the ``--help`` flag:

.. code-block:: console

  $ source <REPO-DIR>/.venv/bin/activate
  $ ska-sdp-continuum-imaging-qa --help
  usage: ska-sdp-continuum-imaging-qa [-h] [--output-dir OUTPUT_DIR] [--snr-threshold SNR_THRESHOLD] fits_image oskar_lsm

  Compute QA metrics for an input FITS image.

  positional arguments:
    fits_image            Path to the FITS image file.
    oskar_lsm             Path to the OSKAR-compatible ASCII LSM (stand-in for GSM).

  options:
    -h, --help            show this help message and exit
    --output-dir OUTPUT_DIR
                          Directory to write output files to (default: a directory named after the input image stem).
    --snr-threshold SNR_THRESHOLD
                          Minimum SNR for sources included in QA metrics (default: 10.0).

Generating the QA metrics
--------------------------

The only mandatory arguments are the paths to the input files, a FITS image and a reference sky model,
supplied to the CLI command via the two positional arguments:

.. code-block:: console

   ska-sdp-continuum-imaging-qa image.fits reference_lsm.txt

The command writes output files into the directory given by ``--output-dir`` or,
if omitted, into a directory named after the FITS image stem under the current working directory.
In the above case, the output files will be written to a directory named ``image/`` under the current working directory.

.. note::

  The following must be true of the two mandatory positional arguments:

  - The first positional argument is a FITS image file output by ``WSClean``.
  - The second positional argument is an ``OSKAR``-compatible `fixed-format ASCII LSM <https://ska-telescope.gitlab.io/sim/oskar/sky_model/sky_model.html#sky-model-file-fixed-format>`_ file.

A successful run of the above command will produce the following output files in the output directory:

.. code-block:: console

  $ ls image/

  image_flux_density_ratios.npy
  image_positional_offsets.npy
  image_qametrics.txt
  image_matched_catalogue.csv
  image_qa_summary.png