jpt.base.utils

Submodules

Attributes

`Symbol`
`Collections`

Classes

`SYMBOL`
`Heap`	Min-heap with a custom key function and stable insertion-order tiebreaking.
`ClassPropertyDescriptor`

Functions

`pairwise`(→ Iterable[Tuple[Any, Any]])	Iterate over all consecutive pairs in `seq`.
`_write_error`(exc)
`mapstr`(seq[, fmt, limit, ellipse])	Convert the sequence `seq` into a list of strings by applying `str` to each of its elements.
`setstr`(seq[, fmt, limit, sep])	Return a string representing the given sequence `seq` as a set.
`setstr_int`(→ str)	Return a prettyfied string representing the given set of integers.
`prod`(it)	Compute the product of all elements in `it`.
`none2nan`(it)	Return a copy of the passed iterable `it`, in which all occurrence
`to_json`(obj)	Recursively generate a JSON representation of the object `obj`.
`format_path`(path, **kwargs)	Returns a readable string representation of a conjunction of variable assignments,
`entropy`(p)	Compute the entropy of the multinomial probability distribution `p`.
`max_entropy`(n)	Compute the maximal entropy that a multinomial random variable with `n` states can have,
`rel_entropy`(p)	Compute the entropy of the multinomial probability distribution `p` normalized
`gini`(p)	Compute the Gini impurity for the distribution `p`.
`classproperty`(func)	This decorator allows to define class properties in the same way as normal object properties.
`list2set`(→ Set[str])	Convert a list to a set.
`list2intset`(→ Set[int])	Convert a 2-element list specifying a lower and an upper bound into a
`normalized`(→ Union[List[numbers.Real], numpy.ndarray, ...)	Returns a modification of `seq` in which all elements sum to 1, but keep their proportions.
`count`([start, inc])
`chop`(→ Iterable[Tuple[Any, Iterable]])	Returns pairs of the first element ("head") and the remainder

Package Contents

class jpt.base.utils.SYMBOL

LAND = '∧'

LOR = '∨'

IN = '∈'

LT = '<'

GT = '>'

LTE = '≤'

GTE = '≥'

THETA = 'ϑ'

ARROW_BAR_LEFT = '⇤'

ARROW_BAR_RIGHT = '⇥'

class jpt.base.utils.Heap(data: Iterable[Any] = None, key: Callable = None, inc: int = 1)

Min-heap with a custom key function and stable insertion-order tiebreaking.

Elements are stored as (key(item), insertion_index, item) triples so that heapq never needs to compare item objects directly. The inc parameter controls how insertion indices advance:

inc=1 (default) — older elements have smaller indices and are therefore popped first when keys are equal (FIFO tiebreaking).
inc=-1 — newer elements have smaller indices and are therefore popped first when keys are equal (LIFO tiebreaking).

The public interface mirrors collections.deque where it makes sense: pop() / popleft() remove the minimum, while popright() removes the element at the tail of the internal array (useful for lazy-deletion patterns, but does not guarantee maximum).

Example:

>>> h = Heap(data=[5, 1, 3])
>>> h.pop()
1
>>> h.push(0)
>>> list(h)
[0, 3, 5]

Initialise the heap.

Parameters:

data – Optional iterable of initial elements. All items are inserted at once and the heap is built in O(n) time via heapq.heapify().
key – A one-argument callable used to derive the sort key from each item. Defaults to the identity function so that items are compared directly.
inc – Increment applied to the internal insertion counter after each push(). Use 1 for FIFO tiebreaking (default) and -1 for LIFO tiebreaking.

class Iterator(heap: Heap, reverse: bool = False)

Forward or reverse iterator over the items in heap storage order.

Iterates the underlying _data list directly — i.e. in heap-array order, not in sorted order — without disturbing the heap.

Parameters:

heap – The Heap to iterate.
reverse – If True, iterate from the tail to the head of the internal array.

heap

_list_iterator

__next__()

__iter__()

_key

_index = 0

_inc = 1

push(item: Any) → None

Push item onto the heap.

Parameters:: item – The element to add. Its sort key is computed via the key function supplied at construction time.

pop() → Any

Remove and return the smallest element.

Raises:: IndexError – If the heap is empty.

popleft() → Any

Alias for pop() — remove and return the smallest element.

Provided for API symmetry with collections.deque.

Raises:: IndexError – If the heap is empty.

popright() → Any

Remove and return the element at the tail of the internal array.

Warning

This is not guaranteed to return the maximum element. In a min-heap the tail of the backing array is a leaf node, which can hold any value. This method is intended for lazy-deletion: locate an item with index(), then remove it with del heap[idx] or swap-and-popright.

Raises:: IndexError – If the heap is empty.

index(item: Any) → int

Return the position of item in the internal storage array.

Uses identity comparison (==). When multiple equal items exist the index of the first match in array order is returned.

Parameters:: item – The element to search for.
Returns:: Zero-based index into the backing array.
Raises:: ValueError – If item is not present.

__len__() → int: Return the number of elements in the heap.

__getitem__(item: int) → Any

Return the element stored at raw array index item.

Index 0 always holds the minimum element (heap invariant).

Parameters:: item – Zero-based index into the backing array.
Raises:: IndexError – If item is out of range.

__delitem__(item: int) → None

Delete the element at raw array index item.

Note

Removing an element other than the root breaks the heap invariant. The backing array is mutated directly without re-heapifying. Prefer pop() for ordinary removal; use this only when you hold a valid index from index() and accept the invariant violation (e.g. inside a rebuild loop).

Parameters:: item – Zero-based index into the backing array.
Raises:: IndexError – If item is out of range.

__bool__() → bool: Return True if the heap contains at least one element.

__repr__() → str

__iter__() → Heap: Return a forward iterator over items in backing-array order.

__reversed__() → Heap: Return a reverse iterator over items in backing-array order.

jpt.base.utils.Symbol

jpt.base.utils.Collections

jpt.base.utils.pairwise(seq: Iterable[Any]) → Iterable[Tuple[Any, Any]]: Iterate over all consecutive pairs in seq.

jpt.base.utils._write_error(exc: BaseException)

jpt.base.utils.mapstr(seq: Iterable, fmt: Callable = None, limit: int = None, ellipse: str = '...')

Convert the sequence seq into a list of strings by applying str to each of its elements.

If a limit is passed, the resulting list of strings will be truncated to limit elements at most, and an additional three dots “…” in the middle.

fmt is an optional formating function that is applied to every sequence element, defaulting to the str builtin function, if None.

jpt.base.utils.setstr(seq: Iterable, fmt: Callable = None, limit: int = None, sep: str = ', ')

Return a string representing the given sequence seq as a set.

If a limit is passed, the resulting list of strings will be truncated to limit elements at most, and an additional three dots “…” in the middle.

fmt is an optional formating function that is applied to every sequence element, defaulting to the str builtin function, if None.

sep specifies the separator character to be used, defaulting to the comma.

jpt.base.utils.setstr_int(intset: Set[int], sep_inner: str = '', sep_outer: str = ', ') → str

Return a prettyfied string representing the given set of integers.

Consecutive numbers (e.g. 0, 1, 2) will be collapsed into a range representation “0…2”.

Parameters:

intset – the set of integers to be formatted.
sep_inner – the separator character to be used for separating consecutive (“inner”) numbers
sep_outer – the separator character to be used for separating non-consecutive (“outer”) numbers

jpt.base.utils.prod(it: Iterable[numbers.Number]): Compute the product of all elements in it.

jpt.base.utils.none2nan(it: Iterable[numbers.Number]): Return a copy of the passed iterable it, in which all occurrence of None have been replaced by np.nan.

jpt.base.utils.to_json(obj)

Recursively generate a JSON representation of the object obj.

Non-natively supported data types must provide a to_json() method that returns a representation that is in turn jsonifiable.

jpt.base.utils.format_path(path, **kwargs): Returns a readable string representation of a conjunction of variable assignments, given by the dictionary path. The kwargs are passed to the jpt.variables.Variable.str function to allow customized formatting.

jpt.base.utils.entropy(p): Compute the entropy of the multinomial probability distribution p. :param p: the probabilities :type p: [float] or {str:float} :return:

jpt.base.utils.max_entropy(n): Compute the maximal entropy that a multinomial random variable with n states can have, i.e. the entropy value assuming a uniform distribution over the values. :param n: :return:

jpt.base.utils.rel_entropy(p): Compute the entropy of the multinomial probability distribution p normalized by the maximal entropy that a multinomial distribution of the dimensionality of p can have. :type p: distribution

jpt.base.utils.gini(p): Compute the Gini impurity for the distribution p.

class jpt.base.utils.ClassPropertyDescriptor(fget, fset=None)

Bases: object

fget

fset = None

__get__(obj, klass=None)

__set__(obj, value)

setter(func)

jpt.base.utils.classproperty(func)

This decorator allows to define class properties in the same way as normal object properties.

https://stackoverflow.com/questions/5189699/how-to-make-a-class-property

jpt.base.utils.list2set(values: List[Symbol]) → Set[str]: Convert a list to a set.

jpt.base.utils.list2intset(bounds: List[int]) → Set[int]: Convert a 2-element list specifying a lower and an upper bound into a integer set containing the admissible values of the corresponding interval

jpt.base.utils.normalized(dist: List[numbers.Real] | numpy.ndarray | Dict[Any, numbers.Real], identity_on_zeros: bool = False, allow_neg: bool = False, zeros: float = 0.0) → List[numbers.Real] | numpy.ndarray | Dict[Any, numbers.Real]

Returns a modification of seq in which all elements sum to 1, but keep their proportions.

dist can be either a list or numpy array, or a dict mapping from random events of any type to their respective value.

Parameters:

dist – the values to be normalized
identity_on_zeros – if all values in dist are zero, the input argument is returned unchanged. If False, an error is raised in the case that the distribution cannot be normalized.
allow_neg – determines whether negative values are allowed. If True, negative values will be treated as positive values for the normalization, but will keep their sign in the output.
zeros – in [0,1], if zeros is a non-negative, non-zero float, all zeros in the distribution will be set to that fraction of the smallest non-zero value in the distribuition. This parameter can be used to artificially circumvent strict-0 values, which may be prohibitive in some cases.

jpt.base.utils.count(start: int = 0, inc: int = 1)

jpt.base.utils.chop(seq: Iterable[Any]) → Iterable[Tuple[Any, Iterable]]: Returns pairs of the first element (“head”) and the remainder (“tail”) for all right subsequences of seq :param seq: The sequence to yield from :return: Head and Tail of the sequence