pipeline.src.shared_tasks.alerts
================================

.. py:module:: pipeline.src.shared_tasks.alerts


Functions
---------

.. autoapisummary::

   pipeline.src.shared_tasks.alerts.extract_silenced_alerts
   pipeline.src.shared_tasks.alerts.extract_active_reportings
   pipeline.src.shared_tasks.alerts.extract_pending_alerts_ids_of_type
   pipeline.src.shared_tasks.alerts.extract_non_archived_reportings_ids_of_type
   pipeline.src.shared_tasks.alerts.archive_reporting
   pipeline.src.shared_tasks.alerts.validate_pending_alert
   pipeline.src.shared_tasks.alerts.make_alerts
   pipeline.src.shared_tasks.alerts.filter_alerts
   pipeline.src.shared_tasks.alerts.load_alerts


Module Contents
---------------

.. py:function:: extract_silenced_alerts(alert_type: str, number_of_hours: int = 0, alert_id: str | None = None) -> pandas.DataFrame

   Return DataFrame of vessels with active silenced alerts of the given type.

   :param alert_type: Type of alert for which to extract silenced alerts
   :type alert_type: str
   :param number_of_hours: Number of hours from current time to extract.
                           Defaults to 0.
   :type number_of_hours: int, optional

   :returns: Silenced alerts with columns
   :rtype: pd.DataFrame


.. py:function:: extract_active_reportings(alert_type: str) -> pandas.DataFrame

   Return DataFrame of vessels with active (non archived) reporting originating from
   alerts of the given type.


.. py:function:: extract_pending_alerts_ids_of_type(alert_type: str) -> List[int]

   Return ids of pending alerts corresponding to `alert_type`


.. py:function:: extract_non_archived_reportings_ids_of_type(alert_type: str) -> List[int]

   Return ids of reportings corresponding to `alert_type`


.. py:function:: archive_reporting(id: int)

.. py:function:: validate_pending_alert(id: int)

.. py:function:: make_alerts(vessels_in_alert: pandas.DataFrame, alert_type: str, name: str, *, natinf_code: int, threat: str, threat_characterization: str, alert_id: int | None = None, description: str | None = None) -> pandas.DataFrame

   Generates alerts from the input `vessels_in_alert`, which must contain the
   following columns :

     - `cfr`
     - `external_immatriculation`
     - `ircs`
     - `vessel_id`
     - `vessel_identifier`
     - `vessel_name`
     - `facade`
     - `dml`
     - `flag_state`
     - `risk_factor`
     - `triggering_behaviour_datetime_utc`
     - and optionally, `depth`, `latitude` and `longitude`

   If `latitude` and `longitude` are not columns of the input, they are added and
   filled with null values in the result.

   If `depth` is a column of the input, it is added to the `value` attributes.

   :param vessels_in_alert: `DateFrame` of vessels for which to
                            create an alert.
   :type vessels_in_alert: pd.DataFrame
   :param alert_type: `type` to specify in the built alerts.
   :type alert_type: str
   :param name: name of the alert.
   :type name: str
   :param natinf_code): natinf code associated with the alert.
   :param threat: threat associated with the alert.
   :type threat: str
   :param threat_characterization: threat_characterization associated with
                                   the alert.
   :type threat_characterization: str
   :param alert_id: `alert_id` to specify in the built alerts,
                    defaults to None.
   :type alert_id: str | None
   :param description: description of the alert, defaults to None.
   :type description: str | None

   :returns: `DataFrame` of alerts.
   :rtype: pd.DataFrame


.. py:function:: filter_alerts(alerts: pandas.DataFrame, vessels_with_silenced_alerts: pandas.DataFrame, vessels_with_active_reportings: pandas.DataFrame = None) -> pandas.DataFrame

   Filters `alerts` to keep only alerts of vessels that are not in
   `vessels_with_silenced_alerts`. If `vessels_with_active_reportings` is provided,
   alerts of vessels that are in this DataFrame are also removed.

   All input DataFrames must have columns :

     - internal_reference_number
     - external_reference_number
     - ircs

   In addition, the `alerts` DataFrame must have columns :

     - vessel_id
     - vessel_name
     - vessel_identifier
     - flag_state
     - facade
     - triggering_behaviour_datetime_utc
     - creation_date
     - latitude
     - longitude
     - value
     - alert_config_name

   and the `silenced_alerts` DataFrame must have a `silenced_before_date`
   column.

   :param alerts: positions alerts.
   :type alerts: pd.DataFrame
   :param vessels_with_silenced_alerts: vessels with silenced alerts.
   :type vessels_with_silenced_alerts: pd.DataFrame

   :returns: same as input with some rows removed.
   :rtype: pd.DataFrame


.. py:function:: load_alerts(alerts: pandas.DataFrame, alert_config_name: str)

   Updates the `pending_alerts` that have the specified `alert_config_name` by:

   - deleting alerts in the `pending_alerts`table of the specified `alert_config_name`
   - inserting alerts of the `alerts` dataframe into the `pending_alerts` table

   :param alerts: Alerts to load into the `pending_alerts` table
   :type alerts: pd.DataFrame
   :param alert_config_name: Name that uniquely identifies the set of parameters
                             used for the flow run
   :type alert_config_name: str