Main objects
=========================================

As previously introduced in the :ref:`quickstart` section, the main objects
used in this code are classes instances. Those are defined in the :py:mod:`vlf4ions.class_definition`
module or the  :py:mod:`vlf4ions.forecast_nowcast` module, depending if there are *local objects*
(e.g. a receiver, a transmetter, an alert), or *global procedures*
(e.g. a forecast, a nowcast).

Receiver
-------------------

The VLF receiver used should be defined by
the :py:class:`vlf4ions.class_definition.receiver` class. Each transmitter needs
five parameters:

* a :py:attr:`name`, which will appear in email alerts (:ref:`emails`)
* the lattitude and longitude (:py:attr:`lat` and :py:attr:`lon`), which will appear in plots (:ref:`plot_map`)
* a :py:attr:`threshold` parameter, which is the minimum amplitude below which we consider that a station is not transmitting (default: 0.5)
* :py:attr:`nb_error` is the number of consecutive times there was an error to read the data. If this number becomes too large, an alert email is sent (see the :py:meth:`~vlf4ions.class_definition.station.update_breakpoint` method below). This parameter is initialized to zero and updated as needed.

An additional parameter can be inputted if the receiver doesn't use the same file names convention as an AWESOME instrument (see note in :ref:`reading_files`)

.. _station_class:

Station
-------------------

Each station followed by the receiver should be an instance of the :py:class:`vlf4ions.class_definition.station` class. They countain important information about the receiver, as well as the main method that will be applied.
Below is a table with the main transmitters.

+-----------+-----------+---------+----------+-----------+-------------+
| Call-sign | Frequency | Power   | Latitude | Longitude | Country     |
+===========+===========+=========+==========+===========+=============+
| VTX       | 18.2 kHz  |         | +8.4°    | +77.8°    | India       |
+-----------+-----------+---------+----------+-----------+-------------+
| GVT       | 19.56 kHz | 60 kW   | +54.9°   | -3.3°     | UK          |
+-----------+-----------+---------+----------+-----------+-------------+
| NWC       | 19.8 kHz  | 1000 kW | -21.8°   | +114.1°   | Australia   |
+-----------+-----------+---------+----------+-----------+-------------+
| NPM       | 21.4 kHz  | 566 kW  | +21.4°   | -158.1°   | Hawaii (USA)|
+-----------+-----------+---------+----------+-----------+-------------+
| GQD       | 22.1 kHz  |         | +54.7°   | -2.9°     | UK          |
+-----------+-----------+---------+----------+-----------+-------------+
| DHO       | 23.4 kHz  | 800 kW  | +53.1°   | +7.6°     | Germany     |
+-----------+-----------+---------+----------+-----------+-------------+
| NAA       | 24 kHz    | 1000 kW | +44.6°   | -67.3°    | USA         |
+-----------+-----------+---------+----------+-----------+-------------+
| NLK       | 24.8 kHz  |         | +48.2°   | -121.9°   | USA         |
+-----------+-----------+---------+----------+-----------+-------------+
| NML       | 25.2 kHz  | 500 kW  | +46.4°   | -98.3°    | USA         |
+-----------+-----------+---------+----------+-----------+-------------+
| TBB       | 26.7 kHz  |         | +37.4°   | +27.3°    | Turkey      |
+-----------+-----------+---------+----------+-----------+-------------+
| NEGEV     | 29.7 kHz  |         | +31.9°   | +35.1°    | Israël      |
+-----------+-----------+---------+----------+-----------+-------------+
| NRK       | 37.5 kHz  | 100 kW  | +63.9°   | -22.5°    | Island      |
+-----------+-----------+---------+----------+-----------+-------------+
| NAU       | 40.75 kHz | 100 kW  | +18.4°   | -67.2°    | Puerto Rico |
+-----------+-----------+---------+----------+-----------+-------------+
| NSY       | 45.9 kHz  | 250 kW  | +37.1°   | +14.4°    | Italy       |
+-----------+-----------+---------+----------+-----------+-------------+

Attributes
^^^^^^^^^^^^^^^

Each instance of the class needs:

* The :py:attr:`name` of the station (for reference to files, and present in email alerts). They must match the ones that are given to the antenna, and that are present in the VLF files' names.
* Its lattitude/longitude (:py:attr:`lat` and :py:attr:`lon`) for the plots
* Its :py:attr:`frequency`
* A :py:attr:`detection threshold`; this is the slope above which we decide that a flare has been detected. It should have been computed before running the script for the first time, for example by taking the 75th quantile of all the slopes found in quiet times
* :py:attr:`reading-time`, which is the time (in seconds after the minute) at which the data for this station is read. It should be inputted as a string (e.g. :py:obj:`':00'`)

Four optional parameters can also be inputted:

* the :py:attr:`delta` parameter (see :ref:`detection`). Its default value is 0.1, as this was found to be the optimal value when testing the algorithm on one year of data from the Nançay receiver with the NRK station. Similarly, the :py:attr:`time_average` parameter represents the time resolution of the data and the frequency at which it is read. It is set to 60s.
* the :py:attr:`Cal_NS` and :py:attr:`Cal_EW` parameters, which are the calibration number in each orientations. The defaults are\  ``0.14``\ and\  ``0.08``\ , which are the calibration numbers at Nançay for some stations. Each calibration number will depend on the frequency, so in principle they should depend on each station and receiver. However, they can also be set to\ ``1``\  if no calibration is wanted or available.
* the :py:attr:`orientation` parameter, which determines the orientation taken for the data. If this parameter is 1, then the E/W phase and amplitudes are considered, if not, the N/S data is analysed. If it is 2, then the two phase orientation are combined through the start phase (see :ref:`polarisation`) and the amplitude taken is given by the equation below. The default is 2
* the :py:attr:`sza_threshold`. If the computed solar zenith angle is above this value, the station will be declared to be in nighttime. The default is 85° (see :ref:`flags`)

.. math::

    amp = \sqrt{amp_{NS}^2 + amp_{EW}^2}

* :py:attr:`df`, which is the small frequency shift (in Hz) causing the phase drift to correct (see :ref:`phase_detrend`).


Some parameters are initially set and changed internally by the program:

* :py:attr:`nb_data_point` is the number of data points in the last file to be read. This is useful for flagging the data (see :ref:`flag_antenna_down`).
* :py:attr:`Ne`, :py:attr:`DA`, :py:attr:`DP`: electron density, amplitude and phase variations during a solar flare, as computed internally by the code
* :py:attr:`p1`: slope of the last breakpoint (see :ref:`detection`)
* :py:attr:`quiet`: Boolean, is `True` if the last breakpoint found with this station was  deemed to be in quiet times.
* :py:attr:`flag`: Integer, keeps track of the state of the station (see :ref:`flags`)
* :py:attr:`mu` and :py:attr:`sigma`: average and standard deviation error of the likelihood probabilities used to estimate the solar X-ray flux.Those are attributed internally, but they should have been computed beforehand (see :ref:`additional_files` and :ref:`estimating_flux`)
* :py:attr:`sza`: solar zenith angle. This is the mean between the sza at the transmitter site and the receiver site, and is computed in the :py:func:`~vlf4ions.flag.flags` function, by calling :py:func:`~vlf4ions.sunrise_sunset.is_daytime`.

Methods
^^^^^^^^^^^^^^^^

The :py:class:`~vlf4ions.class_definition.station` class has two methods: :meth:`update_breakpoint` and :meth:`get_pdf_coeff`.

:py:meth:`~vlf4ions.class_definition.station.get_pdf_coeff`
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

This method reads the files with the precomputed probability distribution functions for each :py:attr:`DP` (see :ref:`additional_files`) and return the coefficients :math:`mu` and :math:`\sigma` given the values of :py:attr:`DP` for the station.

:py:meth:`~vlf4ions.class_definition.station.update_breakpoints`
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

This is where most of the work is done. This is called at each :py:class:`~vlf4ions.class_definition.station`'s :py:attr:`reading-time`

.. _email_class:

Alerts
-----------------

The third class defined in the :py:class:`vlf4ions.class_definition` module is the alerts sent.

.. note::
    Those alerts are so far coded as email alerts. However, since each alert class instance is defined by the user, they can be replaced by whatever alert class the user wants and has written. The only two requirements is that the class has a method called :py:meth:`~vlf4ions.class_definition.alert.send_email` and a method :py:meth:`~vlf4ions.class_definition.alert.update_detection_body` as described below.

Alerts can be sent for various purposes (see :ref:`quickstart` and :ref:`diagram_main_algo`). Each class instance must have:

* A :py:attr:`subject`, a :py:attr:`body`, a :py:attr:`sender`, :py:attr:`recipients` and a :py:attr:`password`: those are the main characteristics of any email. See `Gmail app passwords <https://support.google.com/mail/answer/185833?hl=en>`_ to know how to setup the email password for Gmail accounts (it must be an app password, not the main account password). Note: :py:attr:`recipients` should be a list of email adresses.

* A :py:attr:`threshold` (default: 0). This is the flux threshold above which we send an alert (if the probability of the solar X-ray flux being above the threshold is 0.1 or more; see :ref:`estimating_flux`)

.. note::

    A threshold alert will only be sent if at least half of the usable stations have detected the flare (to limit the number of false positives)

* :py:attr:`files`: (default: :py:attr:`files = []`) this is a list of path to files that should be sent as attachment to the email alerts. Recommendation: for the alerts dealing with flare detection, at least the :py:obj:`last_pdf` file should be sent (see :ref:`estimating_flux`).

Alerts have two methods: :py:meth:`~vlf4ions.class_definition.email_alerts.send_email` and :py:meth:`~vlf4ions.class_definition.email_alerts.update_detection_body`. The first one sends the alert, while the second one automatically change the email body depending on the detection parameters.

.. tip::
    If an alert is defined with :py:attr:`threshold` = 0 and it is passed to the :py:class:`nowcast` class as an argument (in :py:attr:`alerts`), then alerts will be sent to warn the user that there can be no flare detection during a certain time (because it is nighttime or because all transmitters are in maintenance and none are transmitting)

.. tip::
    A newsletter can also be crafted from the flux estimate file (see :ref:`result_files`). To do this, you can either directly send the file, or use the :py:meth:`~vlf4ions.class_definition.email_alerts.craft_newsletter` method. It will update the email body to send the maximum flux, time of start, maximum and end of each detected solar flare with an estimated flux above M1.

    .. code-block:: ruby

        schedule.every().day.at('20:00:05').do(newsletter.craft_newsletter, path)
        schedule.every().day.at('20:00:07').do(newsletter.send_email)

.. _nowcast_class:

Nowcast
-----------------

The :py:class:`vlf4ions.forecast_nowcast.nowcast` class is the one that deals with reading the characteristics of each :py:class:`~vlf4ions.class_definition.station` to estimate the X-ray flux (see :ref:`estimating_flux`) and electron density (see :ref:`LMP`). Each :py:class:`~vlf4ions.class_definition.station` class instance is called in turn to estimate the flux and electron density and to send alerts if needed. It possesses four attributes:

* :py:attr:`stations`: list of :py:class:`~vlf4ions.class_definition.station` class instances representing each transmitter followed.

* :py:attr:`receiver`: :py:class:`~vlf4ions.class_definition.receiver` class instance representing the receiver

* :py:attr:`alerts`: list of :py:class:`~vlf4ions.class_definition.alert` class instances representing each alert that should be sent if there is a chance of strong flares. Each alert can have different :py:attr:`recipients`, :py:attr:`threshold`, or any other attributes.

* :py:attr:`reading_time`: time (in second after the minute, default: :py:obj:`':00'`) when the class is called.

* :py:attr:`debug`: By default, it is 0. If it is set to 1, display the stations' :py:attr:`DP` each time the :py:meth:`run` method is called. If it is set to 2, further display each station's flags.


Diagram
-------------------

.. _diagram_main_algo:

.. figure:: ../Figures/Diagram_vlf4ions.drawio.png

    Main step of the code and the interaction between the different objects and files