xb5_bag_utils (xb5 v1.0.1)

View Source

Additional utils for operating over xb5_bag contents.

Summary

Types

percentile()

A percentile value between 0.0 (0th) and 1.0 (100th).

percentile_bracket(Element)

The result of a percentile bracket calculation.

percentile_bracket_method()

The method used to calculate a percentile bracket.

percentile_bracket_opt()

An option for percentile functions. Currently only {method, Method} is supported; see percentile_bracket_method/0.

Functions

percentile(Percentile, Size, Root, ValueFun, Opts)

Calculates a percentile value in O(log n) time, using linear interpolation if the method is either inclusive or exclusive (default is inclusive, see percentile_bracket_method/0) and the bracket doesn't fall on one exact element. Returns {value, Result} or none.

percentile_bracket(Percentile, Size, Root, Opts)

Returns the percentile bracket for Percentile in Root node in O(log n) time, using the method selected (default is inclusive; see percentile_bracket_method/0).

percentile_rank(Element, Size, Root)

Returns the percentile rank of Element in non-empty Root as a float in [0.0, 1.0], in O(log n) time.

Types

percentile()

-type percentile() :: 0 | 1 | float().

A percentile value between 0.0 (0th) and 1.0 (100th).

percentile_bracket(Element)

-type percentile_bracket(Element) :: {exact, Element} | {between, Element, Element, T :: float()} | none.

The result of a percentile bracket calculation.

  • {exact, Element} -- the percentile falls exactly on an element.
  • {between, A, B, T} -- the percentile falls between elements A and B, where T is a float in (0.0, 1.0) representing the interpolation factor.
  • none -- the percentile cannot be calculated (empty bag, or out of range for the chosen method).

percentile_bracket_method()

-type percentile_bracket_method() :: inclusive | exclusive | nearest_rank.

The method used to calculate a percentile bracket.

  • inclusive (default) -- Pos = 1 + (N - 1) * P. Equivalent to Excel PERCENTILE.INC (Hyndman-Fan Type 7). Covers the full [0.0, 1.0] range.

  • exclusive -- Pos = (N + 1) * P. Equivalent to Excel PERCENTILE.EXC (Hyndman-Fan Type 6). Returns none for percentiles outside the representable range.

  • nearest_rank -- Pos = ceil(P * N). As described in Wikipedia. Always returns an exact element (no interpolation). Returns none for percentile 0.

percentile_bracket_opt()

-type percentile_bracket_opt() :: {method, percentile_bracket_method()}.

An option for percentile functions. Currently only {method, Method} is supported; see percentile_bracket_method/0.

Functions

percentile(Percentile, Size, Root, ValueFun, Opts)

-spec percentile(Percentile, Size, Root, ValueFun, Opts) -> ValueWrap | none
                    when
                        Percentile :: percentile(),
                        Size :: non_neg_integer(),
                        Root :: xb5_bag_node:t(Element),
                        ValueFun :: fun((Element | InterpolationResult) -> ValueWrap),
                        InterpolationResult :: number(),
                        Opts :: [percentile_bracket_opt()].

Calculates a percentile value in O(log n) time, using linear interpolation if the method is either inclusive or exclusive (default is inclusive, see percentile_bracket_method/0) and the bracket doesn't fall on one exact element. Returns {value, Result} or none.

Raises a {bracket_value_not_a_number, #{value => Bound, bracket => Bracket}} error if linear interpolation is required but the bracketing elements are not numbers.

percentile_bracket(Percentile, Size, Root, Opts)

-spec percentile_bracket(Percentile, Size, Root, Opts) -> Bracket
                            when
                                Percentile :: percentile(),
                                Size :: non_neg_integer(),
                                Root :: xb5_bag_node:t(Element),
                                Opts :: [percentile_bracket_opt()],
                                Bracket :: percentile_bracket(Element).

Returns the percentile bracket for Percentile in Root node in O(log n) time, using the method selected (default is inclusive; see percentile_bracket_method/0).

Returns {exact, Element} when the percentile falls exactly on an element, {between, A, B, T} when it falls between two elements, or none if the bag is empty.

percentile_rank(Element, Size, Root)

-spec percentile_rank(Element, Size, Root) -> Rank
                         when Size :: pos_integer(), Root :: xb5_bag_node:t(Element), Rank :: float().

Returns the percentile rank of Element in non-empty Root as a float in [0.0, 1.0], in O(log n) time.

Element does not have to be in the bag.