medcat2.utils.cdb_state
=======================

.. py:module:: medcat2.utils.cdb_state


Attributes
----------

.. autoapisummary::

   medcat2.utils.cdb_state.logger
   medcat2.utils.cdb_state.CDBState


Classes
-------

.. autoapisummary::

   medcat2.utils.cdb_state.NameInfo
   medcat2.utils.cdb_state.CUIInfo


Functions
---------

.. autoapisummary::

   medcat2.utils.cdb_state.copy_cdb_state
   medcat2.utils.cdb_state.save_cdb_state
   medcat2.utils.cdb_state.apply_cdb_state
   medcat2.utils.cdb_state.load_and_apply_cdb_state
   medcat2.utils.cdb_state.captured_state_cdb
   medcat2.utils.cdb_state.in_memory_state_capture
   medcat2.utils.cdb_state.on_disk_memory_capture


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

.. py:class:: NameInfo

   Bases: :py:obj:`TypedDict`


   dict() -> new empty dictionary
   dict(mapping) -> new dictionary initialized from a mapping object's
       (key, value) pairs
   dict(iterable) -> new dictionary initialized as if via:
       d = {}
       for k, v in iterable:
           d[k] = v
   dict(**kwargs) -> new dictionary initialized with the name=value pairs
       in the keyword argument list.  For example:  dict(one=1, two=2)


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: per_cui_status
      :type:  dict[str, str]


   .. py:attribute:: is_upper
      :type:  bool


   .. py:attribute:: count_train
      :type:  int


   .. py:method:: __contains__()

      True if the dictionary has the specified key, else False.



   .. py:method:: __delattr__()

      Implement delattr(self, name).



   .. py:method:: __delitem__()

      Delete self[key].



   .. py:method:: __dir__()

      Default dir() implementation.



   .. py:method:: __eq__()

      Return self==value.



   .. py:method:: __format__()

      Default object formatter.



   .. py:method:: __ge__()

      Return self>=value.



   .. py:method:: __getattribute__()

      Return getattr(self, name).



   .. py:method:: __getitem__()

      x.__getitem__(y) <==> x[y]



   .. py:method:: __gt__()

      Return self>value.



   .. py:method:: __init__()

      Initialize self.  See help(type(self)) for accurate signature.



   .. py:method:: __ior__()

      Return self|=value.



   .. py:method:: __iter__()

      Implement iter(self).



   .. py:method:: __le__()

      Return self<=value.



   .. py:method:: __len__()

      Return len(self).



   .. py:method:: __lt__()

      Return self<value.



   .. py:method:: __ne__()

      Return self!=value.



   .. py:method:: __new__()

      Create and return a new object.  See help(type) for accurate signature.



   .. py:method:: __or__()

      Return self|value.



   .. py:method:: __reduce__()

      Helper for pickle.



   .. py:method:: __reduce_ex__()

      Helper for pickle.



   .. py:method:: __repr__()

      Return repr(self).



   .. py:method:: __reversed__()

      Return a reverse iterator over the dict keys.



   .. py:method:: __ror__()

      Return value|self.



   .. py:method:: __setattr__()

      Implement setattr(self, name, value).



   .. py:method:: __setitem__()

      Set self[key] to value.



   .. py:method:: __sizeof__()

      D.__sizeof__() -> size of D in memory, in bytes



   .. py:method:: __str__()

      Return str(self).



   .. py:method:: __subclasshook__()

      Abstract classes can override this to customize issubclass().

      This is invoked early on by abc.ABCMeta.__subclasscheck__().
      It should return True, False or NotImplemented.  If it returns
      NotImplemented, the normal algorithm is used.  Otherwise, it
      overrides the normal algorithm (and the outcome is cached).



   .. py:method:: clear()

      D.clear() -> None.  Remove all items from D.



   .. py:method:: copy()

      D.copy() -> a shallow copy of D



   .. py:method:: get()

      Return the value for key if key is in the dictionary, else default.



   .. py:method:: items()

      D.items() -> a set-like object providing a view on D's items



   .. py:method:: keys()

      D.keys() -> a set-like object providing a view on D's keys



   .. py:method:: pop()

      D.pop(k[,d]) -> v, remove specified key and return the corresponding value.

      If the key is not found, return the default if given; otherwise,
      raise a KeyError.



   .. py:method:: popitem()

      Remove and return a (key, value) pair as a 2-tuple.

      Pairs are returned in LIFO (last-in, first-out) order.
      Raises KeyError if the dict is empty.



   .. py:method:: setdefault()

      Insert key with a value of default if key is not in the dictionary.

      Return the value for key if key is in the dictionary, else default.



   .. py:method:: update()

      D.update([E, ]**F) -> None.  Update D from dict/iterable E and F.
      If E is present and has a .keys() method, then does:  for k in E: D[k] = E[k]
      If E is present and lacks a .keys() method, then does:  for k, v in E: D[k] = v
      In either case, this is followed by: for k in F:  D[k] = F[k]



   .. py:method:: values()

      D.values() -> an object providing a view on D's values



.. py:class:: CUIInfo

   Bases: :py:obj:`TypedDict`


   dict() -> new empty dictionary
   dict(mapping) -> new dictionary initialized from a mapping object's
       (key, value) pairs
   dict(iterable) -> new dictionary initialized as if via:
       d = {}
       for k, v in iterable:
           d[k] = v
   dict(**kwargs) -> new dictionary initialized with the name=value pairs
       in the keyword argument list.  For example:  dict(one=1, two=2)


   .. py:attribute:: cui
      :type:  str


   .. py:attribute:: preferred_name
      :type:  str


   .. py:attribute:: names
      :type:  set[str]


   .. py:attribute:: subnames
      :type:  set[str]


   .. py:attribute:: type_ids
      :type:  set[str]


   .. py:attribute:: description
      :type:  Optional[str]


   .. py:attribute:: original_names
      :type:  Optional[set[str]]


   .. py:attribute:: tags
      :type:  Optional[list[str]]


   .. py:attribute:: group
      :type:  Optional[str]


   .. py:attribute:: in_other_ontology
      :type:  Optional[set[str]]


   .. py:attribute:: count_train
      :type:  int


   .. py:attribute:: context_vectors
      :type:  Optional[dict[str, numpy.ndarray]]


   .. py:attribute:: average_confidence
      :type:  float


   .. py:method:: __contains__()

      True if the dictionary has the specified key, else False.



   .. py:method:: __delattr__()

      Implement delattr(self, name).



   .. py:method:: __delitem__()

      Delete self[key].



   .. py:method:: __dir__()

      Default dir() implementation.



   .. py:method:: __eq__()

      Return self==value.



   .. py:method:: __format__()

      Default object formatter.



   .. py:method:: __ge__()

      Return self>=value.



   .. py:method:: __getattribute__()

      Return getattr(self, name).



   .. py:method:: __getitem__()

      x.__getitem__(y) <==> x[y]



   .. py:method:: __gt__()

      Return self>value.



   .. py:method:: __init__()

      Initialize self.  See help(type(self)) for accurate signature.



   .. py:method:: __ior__()

      Return self|=value.



   .. py:method:: __iter__()

      Implement iter(self).



   .. py:method:: __le__()

      Return self<=value.



   .. py:method:: __len__()

      Return len(self).



   .. py:method:: __lt__()

      Return self<value.



   .. py:method:: __ne__()

      Return self!=value.



   .. py:method:: __new__()

      Create and return a new object.  See help(type) for accurate signature.



   .. py:method:: __or__()

      Return self|value.



   .. py:method:: __reduce__()

      Helper for pickle.



   .. py:method:: __reduce_ex__()

      Helper for pickle.



   .. py:method:: __repr__()

      Return repr(self).



   .. py:method:: __reversed__()

      Return a reverse iterator over the dict keys.



   .. py:method:: __ror__()

      Return value|self.



   .. py:method:: __setattr__()

      Implement setattr(self, name, value).



   .. py:method:: __setitem__()

      Set self[key] to value.



   .. py:method:: __sizeof__()

      D.__sizeof__() -> size of D in memory, in bytes



   .. py:method:: __str__()

      Return str(self).



   .. py:method:: __subclasshook__()

      Abstract classes can override this to customize issubclass().

      This is invoked early on by abc.ABCMeta.__subclasscheck__().
      It should return True, False or NotImplemented.  If it returns
      NotImplemented, the normal algorithm is used.  Otherwise, it
      overrides the normal algorithm (and the outcome is cached).



   .. py:method:: clear()

      D.clear() -> None.  Remove all items from D.



   .. py:method:: copy()

      D.copy() -> a shallow copy of D



   .. py:method:: get()

      Return the value for key if key is in the dictionary, else default.



   .. py:method:: items()

      D.items() -> a set-like object providing a view on D's items



   .. py:method:: keys()

      D.keys() -> a set-like object providing a view on D's keys



   .. py:method:: pop()

      D.pop(k[,d]) -> v, remove specified key and return the corresponding value.

      If the key is not found, return the default if given; otherwise,
      raise a KeyError.



   .. py:method:: popitem()

      Remove and return a (key, value) pair as a 2-tuple.

      Pairs are returned in LIFO (last-in, first-out) order.
      Raises KeyError if the dict is empty.



   .. py:method:: setdefault()

      Insert key with a value of default if key is not in the dictionary.

      Return the value for key if key is in the dictionary, else default.



   .. py:method:: update()

      D.update([E, ]**F) -> None.  Update D from dict/iterable E and F.
      If E is present and has a .keys() method, then does:  for k in E: D[k] = E[k]
      If E is present and lacks a .keys() method, then does:  for k, v in E: D[k] = v
      In either case, this is followed by: for k in F:  D[k] = F[k]



   .. py:method:: values()

      D.values() -> an object providing a view on D's values



.. py:data:: logger

.. py:data:: CDBState

   CDB State.

   This is a dictionary of the parts of the CDB that change during
   (supervised) training. It can be used to store and restore the
   state of a CDB after modifying it.

   Currently, the following fields are saved:
    - name2info
    - cui2info
    - token_counts

.. py:function:: copy_cdb_state(cdb)

   Creates a (deep) copy of the CDB state.

   Grabs the fields that correspond to the state,
   creates deep copies, and returns the copies.

   :param cdb: The CDB from which to grab the state.

   :Returns: **CDBState** -- The copied state.


.. py:function:: save_cdb_state(cdb, file_path)

   Saves CDB state in a file.

   Currently uses `dill.dump` to save the relevant fields/values.

   :param cdb: The CDB from which to grab the state.
   :param file_path: The file to dump the state.
   :type file_path: str


.. py:function:: apply_cdb_state(cdb, state)

   Apply the specified state to the specified CDB.

   This overwrites the current state of the CDB with one provided.

   :param cdb: The CDB to apply the state to.
   :param state: The state to use.
   :type state: CDBState


.. py:function:: load_and_apply_cdb_state(cdb, file_path)

   Delete current CDB state and apply CDB state from file.

   This first deletes the current state of the CDB.
   This is to save memory. The idea is that saving the staet
   on disk will save on RAM usage. But it wouldn't really
   work too well if upon load, two instances were still in
   memory.

   :param cdb: The CDB to apply the state to.
   :param file_path: The file where the state has been saved to.
   :type file_path: str


.. py:function:: captured_state_cdb(cdb, save_state_to_disk = False)

   A context manager that captures and re-applies the initial CDB state.

   The context manager captures/copies the initial state of the CDB when
   entering. It then allows the user to modify the state (i.e training).
   Upon exit re-applies the initial CDB state.

   If RAM is an issue, it is recommended to use `save_state_to_disk`.
   Otherwise the copy of the original state will be held in memory.
   If saved on disk, a temporary file is used and removed afterwards.

   :param cdb: The CDB to use.
   :param save_state_to_disk: Whether to save state on disk or hold
                              in memory. Defaults to False.
   :type save_state_to_disk: bool

   :Yields: None


.. py:function:: in_memory_state_capture(cdb)

   Capture the CDB state in memory.

   :param cdb: The CDB to use.

   :Yields: None


.. py:function:: on_disk_memory_capture(cdb)

   Capture the CDB state in a temporary file.

   :param cdb: The CDB to use

   :Yields: None