Use VHC
*******

Usage
=====

Run ``vhc`` issuing the command::

  vhc path [arg1 [arg2 [...]]]

where ``path`` is the directory containing the data ``vhc`` should run on and
where the output files are located.

The first argument ``arg1``, if given, is interpreted as the name of the
``path`` subdirectory from which collect the data. The :ref:`output files
<output>` are saved under ``path``. Any other argument is ignored by the default
implementation of ``vhc``, but is passed to the function implementing the
drivers, to allow for custom behaviours.

.. _input:

Input files
===========

The main and only file ``vhc`` depends on for running is the configuration file
described in :doc:`configuration`.

After loading the configuration file and setting up the logging system, ``vhc``
looks for two files in ``path``::

  v_recipe.txt
  v_driver.txt

If any of them does not exist, they are created.

Recipe file: v_recipe.txt
-------------------------

The recipe file describe the type of files that ``vhc`` is going to analyse and
consists in one single line. The line is read and the recipe is compared with
the list of available recipes, provided in the configuration option ``recipes``
in the ``recipes`` section of file ``vhc_setting.cfg``.

VHC provides the following recipes::

  flat
  arc
  bias
  hetdex_dithers  # not yet implemented

If the recipe file is not found, ``vhc`` looks for a file matching
:data:`~libvhc.utils.generic_virus_match` and infer the corresponding name
comparing it with the expected files names from
:data:`~libvhc.utils.recipe_match`. If it doesn't find a file or the file do not
match set the recipe to ``unknown`` and abort.

Driver file: v_driver.txt
-------------------------

The driver file contains the list of checks (drivers) to execute. Each entry
comes in the form of::

  module:function

where ``module`` is a python module containing ``function``, the function that
implements the driver and that must have the following signature:

.. autofunction:: libvhc.function_signature
    :noindex:

The ``module`` is dynamically loaded and the ``function`` executed.

If the driver file is not found, a new one is created using a default set of
drivers for the recipe at hand. The default drivers are defined in
:data:`~libvhc.utils.default_drivers`.

Available drivers
+++++++++++++++++

* common:
    * common:n_files (not yet implemented)
    * common:n_pixels
    * common:exptime
    * common:check_overscan
* bias:
    * bias:compare
* flat:
    * flat:saturation
    * flat:n_fibers
    * flat:min_flux
* arc:
    * arc:find_peaks

For more details see :doc:`custom_drivers` for more details.

.. _output:

Output
======

``vhc`` stores execution information and the results of the drivers in two
text files and one html document.

Log files
---------

``vhc`` logs into two files:

* ``v_results.txt``: log all the errors and critical messages; it contains all
  the failed drivers as errors messages and exceptions, possibly with
  tracebacks, as critical messages.
* ``log.txt``: it contains all the log message starting from the
  :data:`libvhc.loggers.LOWER_LEVEL` level.

The html recap file
-------------------

For every vhc run, an html file recapping the drivers success of failure for
every IFU is created.