jpt.base.utils ============== .. py:module:: jpt.base.utils Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/jpt/base/utils/heap/index /autoapi/jpt/base/utils/multicore/index /autoapi/jpt/base/utils/pyximporter/index /autoapi/jpt/base/utils/sampling/index Attributes ---------- .. autoapisummary:: jpt.base.utils.Symbol jpt.base.utils.Collections Classes ------- .. autoapisummary:: jpt.base.utils.SYMBOL jpt.base.utils.Heap jpt.base.utils.ClassPropertyDescriptor Functions --------- .. autoapisummary:: jpt.base.utils.pairwise jpt.base.utils._write_error jpt.base.utils.mapstr jpt.base.utils.setstr jpt.base.utils.setstr_int jpt.base.utils.prod jpt.base.utils.none2nan jpt.base.utils.to_json jpt.base.utils.format_path jpt.base.utils.entropy jpt.base.utils.max_entropy jpt.base.utils.rel_entropy jpt.base.utils.gini jpt.base.utils.classproperty jpt.base.utils.list2set jpt.base.utils.list2intset jpt.base.utils.normalized jpt.base.utils.count jpt.base.utils.chop Package Contents ---------------- .. py:class:: SYMBOL .. py:attribute:: LAND :value: '∧' .. py:attribute:: LOR :value: '∨' .. py:attribute:: IN :value: '∈' .. py:attribute:: LT :value: '<' .. py:attribute:: GT :value: '>' .. py:attribute:: LTE :value: '≤' .. py:attribute:: GTE :value: '≥' .. py:attribute:: THETA :value: 'ϑ' .. py:attribute:: ARROW_BAR_LEFT :value: '⇤' .. py:attribute:: ARROW_BAR_RIGHT :value: '⇥' .. py:class:: 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 :class:`collections.deque` where it makes sense: :meth:`pop` / :meth:`popleft` remove the *minimum*, while :meth:`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. :param data: Optional iterable of initial elements. All items are inserted at once and the heap is built in O(n) time via :func:`heapq.heapify`. :param 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. :param inc: Increment applied to the internal insertion counter after each :meth:`push`. Use ``1`` for FIFO tiebreaking (default) and ``-1`` for LIFO tiebreaking. .. py: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. :param heap: The :class:`Heap` to iterate. :param reverse: If ``True``, iterate from the tail to the head of the internal array. .. py:attribute:: heap .. py:attribute:: _list_iterator .. py:method:: __next__() .. py:method:: __iter__() .. py:attribute:: _key .. py:attribute:: _index :value: 0 .. py:attribute:: _inc :value: 1 .. py:method:: push(item: Any) -> None Push *item* onto the heap. :param item: The element to add. Its sort key is computed via the ``key`` function supplied at construction time. .. py:method:: pop() -> Any Remove and return the smallest element. :raises IndexError: If the heap is empty. .. py:method:: popleft() -> Any Alias for :meth:`pop` — remove and return the smallest element. Provided for API symmetry with :class:`collections.deque`. :raises IndexError: If the heap is empty. .. py:method:: 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 :meth:`index`, then remove it with ``del heap[idx]`` or swap-and-``popright``. :raises IndexError: If the heap is empty. .. py:method:: 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. :param item: The element to search for. :returns: Zero-based index into the backing array. :raises ValueError: If *item* is not present. .. py:method:: __len__() -> int Return the number of elements in the heap. .. py:method:: __getitem__(item: int) -> Any Return the element stored at raw array index *item*. Index ``0`` always holds the minimum element (heap invariant). :param item: Zero-based index into the backing array. :raises IndexError: If *item* is out of range. .. py:method:: __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 :meth:`pop` for ordinary removal; use this only when you hold a valid index from :meth:`index` and accept the invariant violation (e.g. inside a rebuild loop). :param item: Zero-based index into the backing array. :raises IndexError: If *item* is out of range. .. py:method:: __bool__() -> bool Return ``True`` if the heap contains at least one element. .. py:method:: __repr__() -> str .. py:method:: __iter__() -> Heap Return a forward iterator over items in backing-array order. .. py:method:: __reversed__() -> Heap Return a reverse iterator over items in backing-array order. .. py:data:: Symbol .. py:data:: Collections .. py:function:: pairwise(seq: Iterable[Any]) -> Iterable[Tuple[Any, Any]] Iterate over all consecutive pairs in ``seq``. .. py:function:: _write_error(exc: BaseException) .. py:function:: 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``. .. py:function:: 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. .. py:function:: 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". :param intset: the set of integers to be formatted. :param sep_inner: the separator character to be used for separating consecutive ("inner") numbers :param sep_outer: the separator character to be used for separating non-consecutive ("outer") numbers .. py:function:: prod(it: Iterable[numbers.Number]) Compute the product of all elements in ``it``. .. py:function:: 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``. .. py:function:: 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. .. py:function:: 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. .. py:function:: entropy(p) Compute the entropy of the multinomial probability distribution ``p``. :param p: the probabilities :type p: [float] or {str:float} :return: .. py:function:: 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: .. py:function:: 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 .. py:function:: gini(p) Compute the Gini impurity for the distribution ``p``. .. py:class:: ClassPropertyDescriptor(fget, fset=None) Bases: :py:obj:`object` .. py:attribute:: fget .. py:attribute:: fset :value: None .. py:method:: __get__(obj, klass=None) .. py:method:: __set__(obj, value) .. py:method:: setter(func) .. py:function:: 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 .. py:function:: list2set(values: List[Symbol]) -> Set[str] Convert a list to a set. .. py:function:: 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 .. py:function:: normalized(dist: Union[List[numbers.Real], numpy.ndarray, Dict[Any, numbers.Real]], identity_on_zeros: bool = False, allow_neg: bool = False, zeros: float = 0.0) -> Union[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. :param dist: the values to be normalized :param 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. :param 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. :param 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. .. py:function:: count(start: int = 0, inc: int = 1) .. py:function:: 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