polymerist.genutils.sequences.discernment.inventory
===================================================

.. py:module:: polymerist.genutils.sequences.discernment.inventory

.. autoapi-nested-parse::

   Utilities and type-hinting for creating symbol inventories, which map symbols and bin labels to occurences
   Useful concrete data structure for representing ordered sequences of symbol multisets for generalized ransom note enumeration



Attributes
----------

.. autoapisummary::

   polymerist.genutils.sequences.discernment.inventory.LOGGER
   polymerist.genutils.sequences.discernment.inventory.T
   polymerist.genutils.sequences.discernment.inventory.L


Classes
-------

.. autoapisummary::

   polymerist.genutils.sequences.discernment.inventory.SymbolInventory


Functions
---------

.. autoapisummary::

   polymerist.genutils.sequences.discernment.inventory.full_arr_builtin


Module Contents
---------------

.. py:data:: LOGGER

.. py:data:: T

.. py:data:: L

.. py:function:: full_arr_builtin(*dims: Iterable[int], fill_value: Any = None) -> list[Any]

   Similar to numpy.full (https://numpy.org/doc/stable/reference/generated/numpy.full.html) but with builtin list type


.. py:class:: SymbolInventory(*args, _number_of_symbols: Optional[int] = None, _number_of_bins: Optional[int] = None, _symbol_index_map: Optional[dict[T, int]] = None, _bin_index_map: Optional[dict[L, int]] = None, **kwargs)

   Bases: :py:obj:`dict`, :py:obj:`Generic`\ [\ :py:obj:`T`\ , :py:obj:`L`\ ]


   Representation of a map from a set of symbols of type T and a set of bin labels of type L to integer counts
   Implemented as a dict, keyed by symbol, whose values count the number of occurrences of that symbol in all bins that symbol occurs

   Data structure with specific methods which are useful in solving the generalized ransom note enumeration problem


   .. py:method:: from_bin_sequence_mapping(choice_bin_map: Mapping[L, Sequence[Iterable[T]]], _symbol_index_map: Optional[dict[T, int]] = None, _bin_index_map: Optional[dict[L, int]] = None) -> SymbolInventory[T, L]
      :classmethod:


      Initialize inventory from a mapping of labels to bins



   .. py:method:: from_bin_sequence(choice_bins: Sequence[Iterable[T]]) -> SymbolInventory[T, int]
      :classmethod:


      Initialize inventory from an ordered sequence of bins
      Special case of mapping instantiation for sequences of bins; simply uses the index of a bin as its label



   .. py:method:: from_bins(choice_bins: Union[Sequence[Iterable[T]], dict[L, Sequence[Iterable[T]]]]) -> SymbolInventory[T, L]
      :classmethod:


      "Smart" initialization method which dispatches to from_bin_sequence() or from_bin_sequence_mapping(),
      depending on the nature of the "choice_bins" container provided



   .. py:property:: number_of_symbols
      :type: int


      Number of unique symbols present in the SymbolInventory


   .. py:property:: number_of_bins
      :type: int


      Number of unique symbols present in the SymbolInventory


   .. py:property:: symbol_index_map
      :type: dict[T, int]


      Arbitrary one-to-one mapping between all symbols present in the inventory and integer indices


   .. py:property:: bin_index_map
      :type: dict[T, int]


      Arbitrary one-to-one mapping between all bins present in the inventory and integer indices


   .. py:method:: contains_word(sequence: Sequence[T], ignore_multiplicities: bool = False) -> bool

      Check if a word (i.e. sequence of symbols of type T) could possibly be produced from a SymbolInventory

      Returns bool; True indicated the word can be made from the inventory
      False return indicates the sequence contains symbols not present in the inventory
      OR contains more of one particular symbol than are present in the whole inventory



   .. py:method:: deepcopy() -> SymbolInventory[T, L]

      Create a deep copy of the current SymbolInventory



   .. py:property:: involution
      :type: SymbolInventory[L, T]


      Returns a new SymbolInventory which switches the order of precedence of the symbols and bin labels
      So-called because self.involution.involution returns a SymbolInventory identical to self (by construction)


   .. py:property:: occurence_matrix
      :type: Union[list[list[int]], numpy.ndarray[Any, int]]


      Creates an NxM matrix (N is the number of symbols, and M is the number of bins) which represents a SymbolInventory
      Matrix element A_ij denotes the number of occurences of the i-th symbol (according to an arbitrary numbering) in the j-th bin

      Will attempt to return matrix as a 2-D numpy array, but will default to a doubly-nested list if numpy is not found to be installed