aisa.utils API documentation
Description: Utility functions and classes.

# Module `aisa.utils`

Utility functions and classes.

## Functions

`def entropy(array)`

  Compute the entropy of the array (or float).

  ## Parameters

  `array` :`float, SparseMat, np.array`
    An array or a float.

  ## Returns

  `entropy` :`float`
    The entropy of the array
`def range_dependent_graph(nnodes, alphas, gammas, symmetric=False)`

  Range depentent graph.

  The probability of each block is given by:

  p_{ij} = \alpha \gamma^{d_{ij}}

  where

  d_{ij} = \frac{d_\theta (i, j )}{2\pi} \sqrt{N_{c_i} N_{c_j}}

  where d_\theta (j,i)
  is the shorter angular path.

  ## Parameters

  `nnodes` :`list` of `ints`
    nodes of each class (len(nodes) = k)
  `alphas` :`matrix-like`
    matrix of parameter alpha (k x k)
  `gammas` :`matrix-like`
    matrix of parameter gamma (k x k)
  `symmetric` :`bool`, default=`False`
    force out graph to be symmetric (Default value = False)

  ## Returns

  `graph` :`nx.Graph` or `nx.DiGraph`
    the graph

## Classes

`class Prob (value)`

  A class to store the probability p
  and the p\log p
  value.

  Given a float or a Prob, store p
  and the p\log p
  .

  ## Parameters

  `value` :`float`
    The probability value

  ### Instance variables

  `var p`

    Return the value of p.

    ## Returns

    `p` :`float`
      the value of p
  `var plogp`

    Return p \log(p)
    .

    ## Returns

    `plogp` :`float`
      return the values of p \log(p)

  ### Methods

  `def copy(self)`

    Return a copy of itself.

    ## Returns

    `probability` :`Prob`
      a copy of self
`class SparseMat (mat, node_num=None, normalize=False, plength=None)`

  A sparse square matrix with column and row slicing capabilities.

  The aim of this matrix is to represent a probability distribution and facilitate entropy calculation. It may be of more that two dimensions.

  Initiate the matrix.

  ## Parameters

  `mat` :`scipy sparse matrix` or `list` or `dict`
    The values of the matrix which can be: - a scipy sparse matrix - a list of ((i, j, …), w) - a dict (i, j, …): w
  `node_num` :`int`
    number of nodes
  `normalize` :`bool`
    whether to normalize entries or not
  `plength` :`int`
    lenght of each path, to use only if len(mat) == 0

  ## Raises

  `ValueError :`
    if normalize is not a float, Prob or bool

  ### Instance variables

  `var nn`

    Return the number of nodes.

    ## Returns

    `nn` :`int`
      the number of nodes
  `var shape`

    Return the shapeof the matrix.

    ## Returns

    `shape` :`tuple`
      a tuple of ints representing the shape of the matrix

  ### Methods

  `def add_colrow(self)`

    Add a new empty node at the end.

  `def copy(self)`

    Return a copy of itself.

    ## Returns

    `sparse_mat` :`SparseMat`
      a copy of itself.
  `def entropy(self)`

    Return the entropy of self.

    ## Returns

    `entropy` :`float`
      The entropy (assuming this matrix is a probability distribution)
  `def get_egonet(self, inode, axis=None)`

    Extract ego-network of a node.

    ## Parameters

    `inode` :`int`
      node
    `axis` :`int` or `None`, default=`None`
      If not `None`, restricts the returned egonet to paths that pass through the given node at the `axis` step. Othewise all paths going through that node are returned.

    ## Returns

    `egonet` :`SparseMat`
      the egonet of the node.
  `def get_from_paths(self, paths, normalize=False)`

    Get weights from self on entries from a list of paths.

    ## Parameters

    `paths` :`list` of `tuples` of `ints`
      a list of paths.
    `normalize` :`(optional) bool`, default=`False`
      if True, renormalize before returning.

    ## Returns

    `matrix` :`SparseMat`
      the new matrix with entries only from the list of paths.
  `def get_from_sparse(self, other, normalize=False)`

    Get weights from self on entries from another SparseMat.

    ## Parameters

    `other` :`SparseMat`
      the matrix defining the paths of interest
    `normalize` :`(optional) bool`, default=`False`
      if True, renormalize before returning.

    ## Returns

    `matrix` :`SparseMat`
      the new matrix with entries from self where other is non-zero.
  `def get_random_entry(self, return_all_probs=False)`

    Get a random entry weighted by the weights.

    ## Parameters

    `return_all_probs` :`(optional) bool`, default=`False`
      if True return the probability of choosing any path

    ## Returns

    `path` :`tuple`
      the path
    `link_prob` :`float`
      the probability of choosing this path
    `probs` :`(optional) array`
      if `return_all_probs` is True, the probabilities to choose any path.
  `def get_submat(self, inodes)`

    Return a submatrix of self defined by nodes in `inodes`.

    ## Parameters

    `inodes` :`list` of `ints`
      nodes to extract from the matrix

    ## Returns

    `submatrix` :`SparseMat`
      the submatrix of all paths going through any of the nodes in `inodes`
  `def kron(self, other)`

    Kronecker product.

  `def merge_colrow(self, index_from, index_to)`

    Merge two indexes in each dimension.

    ## Parameters

    `index_from` :`int`
      index to merge (will be removed)
    `index_to` :`int`
      index to merge.

    ## Returns

    `new_matrix` :`SparseMat`
      new matrix with `index_to` and `index_from` merged.
  `def paths(self, axis=None, node=None)`

    Iterate over paths.

    ## Parameters

    `axis` :`(optional) int` or `None`
      if not None, return the paths that go through the node at this step.
    `node` :`(optional) int` or `None`
      if not None, return the paths that go through the node at this step.

    ## Yields

    `paths`, `value` :`tuple, Prob`
      paths and values. If both `axis` and `node` are not None, only paths going through that node at that step.
  `def paths_through_node(self, node, axis=0)`

    Retuns all paths going through a node at a given step.

    ## Parameters

    `node` :`int`
      the node
    `axis` :`int`, default=`0`
      The step at which the path should go through the node.

    ## Returns

    `paths` :`list` of `tuples`
      the list of paths going through the node at the given step.
  `def project(self, part, move_node=None)`

    Project the matrix to a partition subspace.

    ## Parameters

    `part` :`dict`
      a partition of the graph.
    `move_node` :`tuple` or `None`, default`: None`
      a tuple with (node, new_partition). If not None, this node is moved to the new partition before projecting.

    ## Returns

    `projected_matrix` :`SparseMat`
      the matrix projected to the partition space.
  `def set_path(self, path, weight)`

    Overwrite path weight.

    ## Parameters

    `path` :`tuple` of `ints`
      the new path
    `weight` :`float` or `Prob`
      the new weight
  `def size(self)`

    Return the number of non-zero elements.

    ## Returns

    `size` :`int`
      the number of non-zero elements.
  `def slice(self, axis=0, n=0)`

    Return a slice along an axis.

    ## Parameters

    `axis` :`{0, 1}`
      axis to slice (Default value = 0)

    n : (Default value = 0)

    ## Returns

    `output` :`array`
      description
  `def sum(self, axis=None)`

    Retuns the sum of all entries.

    ## Parameters

    `axis` :`(optional) int` or `None`, default=`None`
      if not `None`, project to the given axis (or step).

    ## Returns

    `sum` :`float`
  `def to_csr(self)`

    Return a scipy sparse matrix.

    It will be projected to the first two axis.