From 852f60f525fdc6080387fe6a3b297736c83f0834 Mon Sep 17 00:00:00 2001 From: Vratko Polak Date: Tue, 23 Jan 2024 15:37:14 +0100 Subject: feat(PyPI): update metadata for jumpavg 0.4.2 + Convert readme to .rst + Add Usage including a basic example. - Detailed description points to C-DASH methodology. + That page is updated for new defaults and better description. + Unify readme layout and origins with MLRsearch metadata. - Not releasing new MLRsearch version just for readme improvements. + Update the TODO file. Change-Id: I76ac22b7f283f01349bf9a50459dc841e13b21ad Signed-off-by: Vratko Polak --- PyPI/jumpavg/README.rst | 74 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 PyPI/jumpavg/README.rst (limited to 'PyPI/jumpavg/README.rst') diff --git a/PyPI/jumpavg/README.rst b/PyPI/jumpavg/README.rst new file mode 100644 index 0000000000..b6b502c62b --- /dev/null +++ b/PyPI/jumpavg/README.rst @@ -0,0 +1,74 @@ +Jumpavg library +=============== + +Origins +------- + +This library was developed as anomaly detection logic for "PAL" component +of CSIT_ (Continuous System and Integration Testing) project +of fd.io_ ("Fast Data"), one of LFN_ (Linux Foundation Networking) projects. +Currently still being primarily used in PAL's successor: CSIT-DASH_. + +In order to make this code available in PyPI_ (Python Package Index), +the setuputils stuff (later converted to pyproject.toml) has been added, +but after some discussion, that directory_ ended up having +only a symlink to the original place of tightly coupled CSIT code. + +Usage +----- + +High level description +______________________ + +The main method is "classify", which partitions the input sequence of values +into consecutive "groups", so that standard deviation of samples within a group +is small. + +The design decisions that went into the final algorithm are heavily influenced +by typical results seen in CSIT testing, so it is better to read about +the inner workings of the classification procedure in CSIT documentation, +especially the Minimum Description Length sub-chapter of `trend analysis`_. + +Example +_______ + +A very basic example, showing some inputs and the structure of output. +The output is a single line, here shown wrapped for readability. + +.. code-block:: python3 + + >>> from jumpavg import classify + >>> classify(values=[2.1, 3.1, 3.2], unit=0.1) + BitCountingGroupList(max_value=3.2, unit=0.1, group_list=[BitCountingGroup(run_list= + [2.1], max_value=3.2, unit=0.1, comment='normal', prev_avg=None, stats=AvgStdevStats + (size=1, avg=2.1, stdev=0.0), cached_bits=6.044394119358453), BitCountingGroup(run_l + ist=[3.1, 3.2], max_value=3.2, unit=0.1, comment='progression', prev_avg=2.1, stats= + AvgStdevStats(size=2, avg=3.1500000000000004, stdev=0.050000000000000044), cached_bi + ts=10.215241265313393)], bits_except_last=6.044394119358453) + +Change log +---------- + +0.4.2: Should no longer divide by zero on empty inputs. + +0.4.1: Fixed bug of not penalizing large stdev enough (at all for size 2 stats). + +0.4.0: Added "unit" and "sbps" parameters so information content +is reasonable even if sample values are below one. + +0.3.0: Considerable speedup by avoiding unneeded copy. Dataclasses used. +Mostly API compatible, but repr looks different. + +0.2.0: API incompatible changes. Targeted to Python 3 now. + +0.1.3: Changed stdev computation to avoid negative variance due to rounding errors. + +0.1.2: First version published in PyPI. + +.. _CSIT: https://wiki.fd.io/view/CSIT +.. _CSIT-DASH: https://csit.fd.io +.. _directory: https://gerrit.fd.io/r/gitweb?p=csit.git;a=tree;f=PyPI/jumpavg +.. _fd.io: https://fd.io/ +.. _LFN: https://www.linuxfoundation.org/projects/networking/ +.. _PyPI: https://pypi.org/ +.. _trend analysis: https://csit.fd.io/cdocs/methodology/trending/analysis/#trend-analysis -- cgit 1.2.3-korg