=========
Insights
=========

Insights module was initially created to implement in :task:`26830` "MEG Smart alerts".

.. uml::
    :caption: Updated Insights module integration with megforms and emails

    namespace megforms {
        class AuditForm {
            + observations
        }
    }

    namespace Insights {
        class BaseMetric {
            - name
            + filters
        }

        class Metric {
            - form
            + frequency
            + aggregate()
            + get_value()
        }

        class TrendMetric {
            - form
            + wards
            + fast_window
            + slow_window
            + get_compliance_or_count_time_series()
            + get_value()
        }

        class MetricAlertConfig {
            - metric_id
            - content_type
            + metric (GenericForeignKey)
            + value
            + triggered
            + message
            + trigger_rules
            + evaluate()
            + trigger()
            + untrigger()
            + update_state()
        }

        interface Signal {
            + alert_triggered
            + alert_untriggered
        }

        interface Celery {
            - crontab
            + calculate_metric()
        }

        BaseMetric <|-- Metric
        BaseMetric <|-- TrendMetric
        MetricAlertConfig ..> BaseMetric : Generic relation
        MetricAlertConfig ..> Signal : Trigger change
        Celery ..> MetricAlertConfig : Periodic metric evaluation
    }

    namespace email {
        interface Celery {
            trigger_alert_report_rules()
        }
    }

    Insights.Metric --> megforms.AuditForm : many to one relation
    email.Celery ..> Insights.Signal : Subscribes



Glossary
---------

.. glossary::
    :sorted:

    metric
        Defines a value to track within a :term:`form <audit form>` (:term:`compliance`, or count of observations),
        how often to sample and how to :term:`aggregate<aggregation>` the values.

        For example: "Minimum compliance" **metric** would define "compliance" as the field, and "min" as the aggregation method.

        Metric is represented by :class:`~insights.models.Metric` model.

    trend metric
        Also defines a value to track within a :term:`form <audit form>` (:term:`compliance`, or count of observations).
        However here a time series of compliance or count values is created as well as moving averages. These moving averages
        are used to return the magnitude of the current trend, returned in get_value.

        If get_value returns > 0 the data is in an uptrend, with higher values meaning a larger trend
        (a value of 1 meaning fast moving average is 100% above the slow moving average).
        if get_value returns < 0 the data is in a down trend.

        Example use - On ward 10 falls have been trending upwards, take action.

        Trend metric is represented by :class:`~insights.models.TrendMetric` model.

    aggregation
        A method of consolidating multiple values into a single value.

        For example "min" **aggregation** method returns only the lowest value, and "avg" is an average of multiple values.

    metric alert
        defines an action to be performed (notification e-mail) when metric exceeds a predefined ``value``.


Modules
-------

Models
^^^^^^^^^^^^^^
.. automodule:: insights.models
    :members:

Utils
^^^^^^^^^^^^^^
.. automodule:: insights.utils
    :members:

Celery tasks
^^^^^^^^^^^^^^
.. automodule:: insights.tasks
    :members: