:tocdepth: 3

base/bif/top-k.bif.bro
======================
.. bro:namespace:: GLOBAL

Functions to probabilistically determine top-k elements.

:Namespace: GLOBAL
:Source File: :download:`/scripts/base/bif/top-k.bif.bro`

Summary
~~~~~~~
Functions
#########
================================================ ==========================================================================
:bro:id:`topk_add`: :bro:type:`function`         Add a new observed object to the data structure.
:bro:id:`topk_count`: :bro:type:`function`       Get an overestimated count of how often a value has been encountered.
:bro:id:`topk_epsilon`: :bro:type:`function`     Get the maximal overestimation for count.
:bro:id:`topk_get_top`: :bro:type:`function`     Get the first *k* elements of the top-k data structure.
:bro:id:`topk_init`: :bro:type:`function`        Creates a top-k data structure which tracks *size* elements.
:bro:id:`topk_merge`: :bro:type:`function`       Merge the second top-k data structure into the first.
:bro:id:`topk_merge_prune`: :bro:type:`function` Merge the second top-k data structure into the first and prunes the final
                                                 data structure back to the size given on initialization.
:bro:id:`topk_size`: :bro:type:`function`        Get the number of elements this data structure is supposed to track (given
                                                 on init).
:bro:id:`topk_sum`: :bro:type:`function`         Get the sum of all counts of all elements in the data structure.
================================================ ==========================================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Functions
#########
.. bro:id:: topk_add

   :Type: :bro:type:`function` (handle: :bro:type:`opaque`, value: :bro:type:`any`) : :bro:type:`any`

   Add a new observed object to the data structure.
   
   .. note:: The first added object sets the type of data tracked by
      the top-k data structure. All following values have to be of the same
      type.
   

   :handle: the TopK handle.
   

   :value: observed value.
   
   .. bro:see:: topk_init topk_get_top topk_count topk_epsilon
      topk_size topk_sum topk_merge topk_merge_prune

.. bro:id:: topk_count

   :Type: :bro:type:`function` (handle: :bro:type:`opaque`, value: :bro:type:`any`) : :bro:type:`count`

   Get an overestimated count of how often a value has been encountered.
   
   .. note:: The value has to be part of the currently tracked elements,
      otherwise 0 will be returned and an error message will be added to
      reporter.
   

   :handle: the TopK handle.
   

   :value: Value to look up count for.
   

   :returns: Overestimated number for how often the element has been encountered.
   
   .. bro:see:: topk_init topk_add topk_get_top topk_epsilon
      topk_size topk_sum topk_merge topk_merge_prune

.. bro:id:: topk_epsilon

   :Type: :bro:type:`function` (handle: :bro:type:`opaque`, value: :bro:type:`any`) : :bro:type:`count`

   Get the maximal overestimation for count.
   
   .. note:: Same restrictions as for :bro:id:`topk_count` apply.
   

   :handle: the TopK handle.
   

   :value: Value to look up epsilon for.
   

   :returns: Number which represents the maximal overestimation for the count of
            this element.
   
   .. bro:see:: topk_init topk_add topk_get_top topk_count
      topk_size topk_sum topk_merge topk_merge_prune

.. bro:id:: topk_get_top

   :Type: :bro:type:`function` (handle: :bro:type:`opaque`, k: :bro:type:`count`) : :bro:type:`any_vec`

   Get the first *k* elements of the top-k data structure.
   

   :handle: the TopK handle.
   

   :k: number of elements to return.
   

   :returns: vector of the first k elements.
   
   .. bro:see:: topk_init topk_add topk_count topk_epsilon
      topk_size topk_sum topk_merge topk_merge_prune

.. bro:id:: topk_init

   :Type: :bro:type:`function` (size: :bro:type:`count`) : :bro:type:`opaque`

   Creates a top-k data structure which tracks *size* elements.
   

   :size: number of elements to track.
   

   :returns: Opaque pointer to the data structure.
   
   .. bro:see:: topk_add topk_get_top topk_count topk_epsilon
      topk_size topk_sum topk_merge topk_merge_prune

.. bro:id:: topk_merge

   :Type: :bro:type:`function` (handle1: :bro:type:`opaque`, handle2: :bro:type:`opaque`) : :bro:type:`any`

   Merge the second top-k data structure into the first.
   

   :handle1: the first TopK handle.
   

   :handle2: the second TopK handle.
   
   .. note:: This does not remove any elements, the resulting data structure
      can be bigger than the maximum size given on initialization.
   
   .. bro:see:: topk_init topk_add topk_get_top topk_count topk_epsilon
      topk_size topk_sum topk_merge_prune

.. bro:id:: topk_merge_prune

   :Type: :bro:type:`function` (handle1: :bro:type:`opaque`, handle2: :bro:type:`opaque`) : :bro:type:`any`

   Merge the second top-k data structure into the first and prunes the final
   data structure back to the size given on initialization.
   
   .. note:: Use with care and only when being aware of the restrictions this
      entails. Do not call :bro:id:`topk_size` or :bro:id:`topk_add` afterwards,
      results will probably not be what you expect.
   

   :handle1: the TopK handle in which the second TopK structure is merged.
   

   :handle2: the TopK handle in which is merged into the first TopK structure.
   
   .. bro:see:: topk_init topk_add topk_get_top topk_count topk_epsilon
      topk_size topk_sum topk_merge

.. bro:id:: topk_size

   :Type: :bro:type:`function` (handle: :bro:type:`opaque`) : :bro:type:`count`

   Get the number of elements this data structure is supposed to track (given
   on init).
   
   .. note:: Note that the actual number of elements in the data structure can
      be lower or higher (due to non-pruned merges) than this.
   

   :handle: the TopK handle.
   

   :returns: size given during initialization.
   
   .. bro:see:: topk_init topk_add topk_get_top topk_count topk_epsilon
      topk_sum topk_merge topk_merge_prune

.. bro:id:: topk_sum

   :Type: :bro:type:`function` (handle: :bro:type:`opaque`) : :bro:type:`count`

   Get the sum of all counts of all elements in the data structure.
   
   .. note:: This is equal to the number of all inserted objects if the data
      structure never has been pruned. Do not use after
      calling :bro:id:`topk_merge_prune` (will throw a warning message if used
      afterwards).
   

   :handle: the TopK handle.
   

   :returns: sum of all counts.
   
   .. bro:see:: topk_init topk_add topk_get_top topk_count topk_epsilon
      topk_size topk_merge topk_merge_prune


