PyPI/jumpavg/README.rst

   1 Jumpavg library
   2 ===============
   3
   4 Origins
   5 -------
   6
   7 This library was developed as anomaly detection logic for "PAL" component
   8 of CSIT_ (Continuous System and Integration Testing) project
   9 of fd.io_ ("Fast Data"), one of LFN_ (Linux Foundation Networking) projects.
  10 Currently still being primarily used in PAL's successor: CSIT-DASH_.
  11
  12 In order to make this code available in PyPI_ (Python Package Index),
  13 the setuputils stuff (later converted to pyproject.toml) has been added,
  14 but after some discussion, that directory_ ended up having
  15 only a symlink to the original place of tightly coupled CSIT code.
  16
  17 Usage
  18 -----
  19
  20 High level description
  21 ______________________
  22
  23 The main method is "classify", which partitions the input sequence of values
  24 into consecutive "groups", so that standard deviation of samples within a group
  25 is small.
  26
  27 The design decisions that went into the final algorithm are heavily influenced
  28 by typical results seen in CSIT testing, so it is better to read about
  29 the inner workings of the classification procedure in CSIT documentation,
  30 especially the Minimum Description Length sub-chapter of `trend analysis`_.
  31
  32 Example
  33 _______
  34
  35 A very basic example, showing some inputs and the structure of output.
  36 The output is a single line, here shown wrapped for readability.
  37
  38 ..  code-block:: python3
  39
  40     >>> from jumpavg import classify
  41     >>> classify(values=[2.1, 3.1, 3.2], unit=0.1)
  42     BitCountingGroupList(max_value=3.2, unit=0.1, group_list=[BitCountingGroup(run_list=
  43     [2.1], max_value=3.2, unit=0.1, comment='normal', prev_avg=None, stats=AvgStdevStats
  44     (size=1, avg=2.1, stdev=0.0), cached_bits=6.044394119358453), BitCountingGroup(run_l
  45     ist=[3.1, 3.2], max_value=3.2, unit=0.1, comment='progression', prev_avg=2.1, stats=
  46     AvgStdevStats(size=2, avg=3.1500000000000004, stdev=0.050000000000000044), cached_bi
  47     ts=10.215241265313393)], bits_except_last=6.044394119358453)
  48
  49 Change log
  50 ----------
  51
  52 0.4.2: Should no longer divide by zero on empty inputs.
  53
  54 0.4.1: Fixed bug of not penalizing large stdev enough (at all for size 2 stats).
  55
  56 0.4.0: Added "unit" and "sbps" parameters so information content
  57 is reasonable even if sample values are below one.
  58
  59 0.3.0: Considerable speedup by avoiding unneeded copy. Dataclasses used.
  60 Mostly API compatible, but repr looks different.
  61
  62 0.2.0: API incompatible changes. Targeted to Python 3 now.
  63
  64 0.1.3: Changed stdev computation to avoid negative variance due to rounding errors.
  65
  66 0.1.2: First version published in PyPI.
  67
  68 .. _CSIT: https://wiki.fd.io/view/CSIT
  69 .. _CSIT-DASH: https://csit.fd.io
  70 .. _directory: https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/jumpavg
  71 .. _fd.io: https://fd.io/
  72 .. _LFN: https://www.linuxfoundation.org/projects/networking/
  73 .. _PyPI: https://pypi.org/
  74 .. _trend analysis: https://csit.fd.io/cdocs/methodology/trending/analysis/#trend-analysis