.. _reading_files:

Reading files
==========================================

This section deals with reading the files in real-time or in post-processing. The only difference between
the real-time files and the others is their types (\  ``.mau``\  or\  ``.mat``\ ). Other than this, no differences
are noted.

It is assumed that the files end in\ ``101A.mau``\ or similar endings, and that the name of the files countains the station's call-sign.

In the\  ``read_files``\  module are two functions,\  ``read_Narrowband_postprocessing``\  and\  ``read_Narrowband_real_time``\ .
They require three arguments:

#. The date of interest, in the format\  ``yyyy_mm_dd``\ .
#. The call-sign of the station (e.g.\  ``'NRK'``\  ).
#. The path to the files.

Those functions return (in order) the amplitude in the N/S and the E/W directions, the phase in the N/S and E/W direction, a time-array and for the real_time function a number of reading errors (for the real-time function, to keep track of the number of errors in reading the files - this is handled internally).

Example:

.. code-block:: ruby

    >>> amp_NS, amp_EW, phase_NS, phase_EW = read_Narrowband_postprocessing('2023_11_05', 'NRK', '/Documents/VLF/MESURES')

.. note::
    If the antenna is not an AWESOME antenna, the naming convention may be different. In this case, an additionnal parameter can be inputted to the :py:class:`receiver` class instance as a list of strings. It should specify the endings of the files for the amplitude in N/S, phase in N/S, amplitude in E/W and phase in E/W in that order.

    For example, for an AWESOME instrument, this would be:

    .. code-block:: ruby

        file_endings = ['_100A', '_100B', '_101A', '_101B']

    The default parameter is the endings for an AWESOME instrument. For\  ``read_Narrowband_postprocessing``\,\ ``file_endings``\ is directly specified as an input

.. note::

    A time array is also built each time the file is read. Though it could rely on the start time indicated in the data file, this seems to fail in very specific cases when the recording is stopped during the day.

    Thus, the time-array is instead build on the time of the file reading, as determined by the\  ``datetime.now``\ Python method.