spateo.tools.labels
===================

.. py:module:: spateo.tools.labels


Classes
-------

.. autoapisummary::

   spateo.tools.labels.Label


Functions
---------

.. autoapisummary::

   spateo.tools.labels.row_normalize
   spateo.tools.labels._rand_binary_array
   spateo.tools.labels.expand_labels
   spateo.tools.labels.match_labels
   spateo.tools.labels.match_label_series
   spateo.tools.labels.interlabel_connections
   spateo.tools.labels.create_label_class


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

.. py:function:: row_normalize(graph: scipy.sparse.csr_matrix, copy: bool = False, verbose: bool = True) -> scipy.sparse.csr_matrix

   Normalize a compressed sparse row (CSR) matrix by row- written for sparse pairwise distance arrays, but can be
   applied to any sparse matrix.

   :param graph: Sparse array of shape [n_samples, n_features]. If pairwise distance array, shape [n_samples, n_samples].
   :param copy: If True, create a copy of the graph before computations so that the original is preserved.
   :param verbose: If True, prints number of nonzero entries.

   :returns: Input array (or the copy of the input array) post-normalization.
   :rtype: graph


.. py:class:: Label(labels_dense: Union[numpy.ndarray, list], str_map: Union[None, dict] = None, verbose: bool = False)

   Bases: :py:obj:`object`


   Given categorizations for a set of points, wrap into a Label class.

   labels_dense: Numerical labels.
   str_map: Optional mapping of numerical labels (keys) to strings (values).
   verbose: whether to print running info of row_normalize.


   .. py:attribute:: dense


   .. py:attribute:: num_samples


   .. py:attribute:: bins


   .. py:attribute:: ids


   .. py:attribute:: counts


   .. py:attribute:: max_id


   .. py:attribute:: num_labels


   .. py:attribute:: verbose
      :value: False



   .. py:attribute:: onehot
      :value: None



   .. py:attribute:: normalized_onehot
      :value: None



   .. py:method:: __repr__() -> str


   .. py:method:: __str__() -> str


   .. py:method:: get_onehot() -> scipy.sparse.csr_matrix

      return one-hot sparse array of labels.
      If not already computed, generate the sparse array from dense label array



   .. py:method:: get_normalized_onehot() -> scipy.sparse.csr_matrix

      Return normalized one-hot sparse array of labels.



   .. py:method:: generate_normalized_onehot() -> scipy.sparse.csr_matrix

      Generate a normalized onehot matrix where each row is normalized by the count of that label
      e.g. a row [0 1 1 0 0] will be converted to [0 0.5 0.5 0 0]



   .. py:method:: generate_onehot() -> scipy.sparse.csr_matrix

      Convert an array of labels to a num_labels x num_samples sparse one-hot matrix
      Labels MUST be integers starting from 0, but can have gaps in between e.g. [0,1,5,9]



.. py:function:: _rand_binary_array(array_length, num_onbits)

.. py:function:: expand_labels(label: Label, max_label_id: int, sort_labels: bool = False) -> Label

   Spread out label IDs such that they range evenly from 0 to max_label_id, e.g. [0 1 2] -> [0 5 10]
   Useful if you need to be consistent with other label sets with many more label IDs.
   This spreads labels out along the color spectrum/map so that the colors are not too similar to each other.
   Use sort_labels if the list of IDs are not already sorted (although IDs are typically already sorted)


.. py:function:: match_labels(labels_1: Label, labels_2: Label, extra_labels_assignment: str = 'random', verbose: bool = False) -> Label

   Match second set of labels to first, returning a new Label object
   Uses scipy's version of the Hungarian algorithm (linear_sum_assigment)


.. py:function:: match_label_series(label_list: List[Label], least_labels_first: bool = True, extra_labels_assignment: str = 'greedy') -> Tuple[List[Label], int]

   Match a list of labels to each other, one after another in order of increasing (if least_labels_first is true)
   or decreasing (least_labels_first set to false) number of label ids.

   Returns the relabeled list in original order.


.. py:function:: interlabel_connections(label: Label, weights_matrix: Union[scipy.sparse.csr_matrix, numpy.ndarray]) -> numpy.ndarray

   Compute connections strength between labels (based on pairwise distances), normalized by counts of each label

   :param class: Instance of class 'Label', with one-hot dense label matrix in "dense", list of unique labels in "ids",
                 counts per label in "counts", etc.
   :param weights_matrix: Pairwise adjacency matrix, weighted by e.g. spatial distance between points.

   :returns: Pairwise connection strength array, shape [n_labels, n_labels].
   :rtype: connections


.. py:function:: create_label_class(adata: anndata.AnnData, cat_key: Union[str, List[str]]) -> Union[Label, List[Label]]

   Wraps categorical labels into custom Label class for downstream processing.

   :param adata: An anndata object.
   :param cat_key: Keys in .obs containing categorical labels. This function and the Label class provide the most utility
                   when this is used in conjunction with the results of multiple different runs of the Louvain algorithm.

   :returns:

             Either an object of Label class or a list where each element is an object of Label class. Will return a
                 list if given multiple arguments to 'cat_key'.
   :rtype: label