# algorithms.clustering.gmm

## Module: `algorithms.clustering.gmm`

Inheritance diagram for `nipy.algorithms.clustering.gmm`:

Gaussian Mixture Model Class: contains the basic fields and methods of GMMs The class GMM _old uses C bindings which are computationally and memory efficient.

Author : Bertrand Thirion, 2006-2009

## Classes

### `GMM`

class nipy.algorithms.clustering.gmm.GMM(k=1, dim=1, prec_type='full', means=None, precisions=None, weights=None)

  Bases: `object`

  Standard GMM.

  this class contains the following members k (int): the number of components in the mixture dim (int): is the dimension of the data prec_type = ‘full’ (string) is the parameterization

  > of the precisions/covariance matrices: either ‘full’ or ‘diagonal’.

  means: array of shape (k,dim):

    all the means (mean parameters) of the components

  precisions: array of shape (k,dim,dim):

    the precisions (inverse covariance matrix) of the components

  weights: array of shape(k): weights of the mixture

  __init__(k=1, dim=1, prec_type='full', means=None, precisions=None, weights=None)

    Initialize the structure, at least with the dimensions of the problem

    Parameters:
      k (int) the number of classes of the model
      dim (int) the dimension of the problem
      prec_type = ‘full’coavriance:precision parameterization

        (diagonal ‘diag’ or full ‘full’).

      means = None: array of shape (self.k,self.dim)
      precisions = None: array of shape (self.k,self.dim,self.dim)

        or (self.k, self.dim)

      weights=None: array of shape (self.k)
      By default, means, precision and weights are set as
      zeros()
      eye()
      1/k ones()
      with the correct dimensions
  average_log_like(x, tiny=1e-15)

    returns the averaged log-likelihood of the mode for the dataset x

    Parameters:
      x: array of shape (n_samples,self.dim)

        the data used in the estimation process

      tiny = 1.e-15: a small constant to avoid numerical singularities
  bic(like, tiny=1e-15)

    Computation of bic approximation of evidence

    Parameters:
      like, array of shape (n_samples, self.k)

        component-wise likelihood

      tiny=1.e-15, a small constant to avoid numerical singularities
    Returns:
      the bic value, float
  check()

    Checking the shape of different matrices involved in the model

  check_x(x)

    essentially check that x.shape[1]==self.dim

    x is returned with possibly reshaping

  estimate(x, niter=100, delta=0.0001, verbose=0)

    Estimation of the model given a dataset x

    Parameters:
      x array of shape (n_samples,dim)

        the data from which the model is estimated

      niter=100: maximal number of iterations in the estimation process
      delta = 1.e-4: increment of data likelihood at which

        convergence is declared

      verbose=0: verbosity mode
    Returns:
      bic an asymptotic approximation of model evidence
  evidence(x)

    Computation of bic approximation of evidence

    Parameters:
      x array of shape (n_samples,dim)

        the data from which bic is computed

    Returns:
      the bic value
  guess_regularizing(x, bcheck=1)

    Set the regularizing priors as weakly informative according to Fraley and raftery; Journal of Classification 24:155-181 (2007)

    Parameters:
      x array of shape (n_samples,dim)

        the data used in the estimation process

  initialize(x)

    Initializes self according to a certain dataset x: 1. sets the regularizing hyper-parameters 2. initializes z using a k-means algorithm, then 3. update the parameters

    Parameters:
      x, array of shape (n_samples,self.dim)

        the data used in the estimation process

  initialize_and_estimate(x, z=None, niter=100, delta=0.0001, ninit=1, verbose=0)

    Estimation of self given x

    Parameters:
      x array of shape (n_samples,dim)

        the data from which the model is estimated

      z = None: array of shape (n_samples)

        a prior labelling of the data to initialize the computation

      niter=100: maximal number of iterations in the estimation process
      delta = 1.e-4: increment of data likelihood at which

        convergence is declared

      ninit=1: number of initialization performed

        to reach a good solution

      verbose=0: verbosity mode
    Returns:
      the best model is returned
  likelihood(x)

    return the likelihood of the model for the data x the values are weighted by the components weights

    Parameters:
      x array of shape (n_samples,self.dim)

        the data used in the estimation process

    Returns:
      like, array of shape(n_samples,self.k)

        component-wise likelihood

  map_label(x, like=None)

    return the MAP labelling of x

    Parameters:
      x array of shape (n_samples,dim)

        the data under study

      like=None array of shape(n_samples,self.k)

        component-wise likelihood if like==None, it is recomputed

    Returns:
      z: array of shape(n_samples): the resulting MAP labelling

        of the rows of x

  mixture_likelihood(x)

    Returns the likelihood of the mixture for x

    Parameters:
      x: array of shape (n_samples,self.dim)

        the data used in the estimation process

  plugin(means, precisions, weights)

    Set manually the weights, means and precision of the model

    Parameters:
      means: array of shape (self.k,self.dim)
      precisions: array of shape (self.k,self.dim,self.dim)

        or (self.k, self.dim)

      weights: array of shape (self.k)
  pop(like, tiny=1e-15)

    compute the population, i.e. the statistics of allocation

    Parameters:
      like: array of shape (n_samples,self.k):

        the likelihood of each item being in each class

  show(x, gd, density=None, axes=None)

    Function to plot a GMM, still in progress Currently, works only in 1D and 2D

    Parameters:
      x: array of shape(n_samples, dim)

        the data under study

      gd: GridDescriptor instance
      density: array os shape(prod(gd.n_bins))

        density of the model one the discrete grid implied by gd by default, this is recomputed

  show_components(x, gd, density=None, mpaxes=None)

    Function to plot a GMM – Currently, works only in 1D

    Parameters:
      x: array of shape(n_samples, dim)

        the data under study

      gd: GridDescriptor instance
      density: array os shape(prod(gd.n_bins))

        density of the model one the discrete grid implied by gd by default, this is recomputed

      mpaxes: axes handle to make the figure, optional,

        if None, a new figure is created

  test(x, tiny=1e-15)

    Returns the log-likelihood of the mixture for x

    Parameters:
      x array of shape (n_samples,self.dim)

        the data used in the estimation process

    Returns:
      ll: array of shape(n_samples)

        the log-likelihood of the rows of x

  train(x, z=None, niter=100, delta=0.0001, ninit=1, verbose=0)

    Idem initialize_and_estimate

  unweighted_likelihood(x)

    return the likelihood of each data for each component the values are not weighted by the component weights

    Parameters:
      x: array of shape (n_samples,self.dim)

        the data used in the estimation process

    Returns:
      like, array of shape(n_samples,self.k)

        unweighted component-wise likelihood

    Notes

    Hopefully faster

  unweighted_likelihood_(x)

    return the likelihood of each data for each component the values are not weighted by the component weights

    Parameters:
      x: array of shape (n_samples,self.dim)

        the data used in the estimation process

    Returns:
      like, array of shape(n_samples,self.k)

        unweighted component-wise likelihood

  update(x, l)

    Identical to self._Mstep(x,l)

### `GridDescriptor`

class nipy.algorithms.clustering.gmm.GridDescriptor(dim=1, lim=None, n_bins=None)

  Bases: `object`

  A tiny class to handle cartesian grids

  __init__(dim=1, lim=None, n_bins=None)
    Parameters:
      dim: int, optional,

        the dimension of the grid

      lim: list of len(2*self.dim),

        the limits of the grid as (xmin, xmax, ymin, ymax, …)

      n_bins: list of len(self.dim),

        the number of bins in each direction

  make_grid()

    Compute the grid points

    Returns:
      grid: array of shape (nb_nodes, self.dim)

        where nb_nodes is the prod of self.n_bins

  set(lim, n_bins=10)

    set the limits of the grid and the number of bins

    Parameters:
      lim: list of len(2*self.dim),

        the limits of the grid as (xmin, xmax, ymin, ymax, …)

      n_bins: list of len(self.dim), optional

        the number of bins in each direction

## Functions

nipy.algorithms.clustering.gmm.best_fitting_GMM(x, krange, prec_type='full', niter=100, delta=0.0001, ninit=1, verbose=0)

  Given a certain dataset x, find the best-fitting GMM with a number k of classes in a certain range defined by krange

  Parameters:
    x: array of shape (n_samples,dim)

      the data from which the model is estimated

    krange: list of floats,

      the range of values to test for k

    prec_type: string (to be chosen within ‘full’,’diag’), optional,

      the covariance parameterization

    niter: int, optional,

      maximal number of iterations in the estimation process

    delta: float, optional,

      increment of data likelihood at which convergence is declared

    ninit: int

      number of initialization performed

    verbose=0: verbosity mode
  Returns:
    mg the best-fitting GMM instance

nipy.algorithms.clustering.gmm.plot2D(x, my_gmm, z=None, with_dots=True, log_scale=False, mpaxes=None, verbose=0)

  Given a set of points in a plane and a GMM, plot them

  Parameters:
    x: array of shape (npoints, dim=2),

      sample points

    my_gmm: GMM instance,

      whose density has to be plotted

    z: array of shape (npoints), optional

      that gives a labelling of the points in x by default, it is not taken into account

    with_dots, bool, optional

      whether to plot the dots or not

    log_scale: bool, optional

      whether to plot the likelihood in log scale or not

    mpaxes=None, int, optional

      if not None, axes handle for plotting

    verbose: verbosity mode, optional
  Returns:
    gd, GridDescriptor instance,

      that represents the grid used in the function

    ax, handle to the figure axes

  Notes

  `my_gmm` is assumed to have have a ‘nixture_likelihood’ method that takes an array of points of shape (np, dim) and returns an array of shape (np,my_gmm.k) that represents the likelihood component-wise