SciPy 0.6.0 API Documentation Generated by Endo, 2007-10-17

Classes

• ClusterError

Function summary

• kmeans(obs, k_or_guess, iter = 20, thresh = 1.0000000000000001e-05)
• kmeans2(data, k, iter = 10, thresh = 1.0000000000000001e-05, minit = 'random', missing = 'warn')
• py_vq(obs, code_book)
• py_vq2(obs, code_book)
• vq(obs, code_book)
• whiten(obs)

Functions

• kmeans(obs, k_or_guess, iter = 20, thresh = 1.0000000000000001e-05)

  Generate a code book with minimum distortion.

  Parameters:	obs : ndarray Each row of the array is an observation. The columns are the "features" seen during each observation The features must be whitened first using the whiten function or something equivalent. k_or_guess : int or ndarray If integer, it is the number of code book elements. If a 2D array, the array is used as the intial guess for the code book. The array should have k rows, and the same number of columns (features) as the obs array. iter : int The number of times to restart the kmeans algorithm with a new initial guess. If k_or_guess is a 2D array (codebook), this argument is ignored and only 1 iteration is run. thresh : float Terminate each kmeans run when the distortion change from one iteration to the next is less than this value.
  Returns:	codesbook : ndarray The codes that best fit the observation distortion : float The distortion between the observations and the codes.
  SeeAlso:	kmeans2: similar function, but with more options for initialization, and returns label of each observation

  Examples

  >>> from numpy import array
  >>> from scipy.cluster.vq import vq, kmeans, whiten
  >>> features  = array([[ 1.9,2.3],
  ...                    [ 1.5,2.5],
  ...                    [ 0.8,0.6],
  ...                    [ 0.4,1.8],
  ...                    [ 0.1,0.1],
  ...                    [ 0.2,1.8],
  ...                    [ 2.0,0.5],
  ...                    [ 0.3,1.5],
  ...                    [ 1.0,1.0]])
  >>> whitened = whiten(features)
  >>> book = array((whitened[0],whitened[2]))
  >>> kmeans(whitened,book)
  (array([[ 2.3110306 ,  2.86287398],
         [ 0.93218041,  1.24398691]]), 0.85684700941625547)
  

  >>> from numpy import random
  >>> random.seed((1000,2000))
  >>> codes = 3
  >>> kmeans(whitened,codes)
  (array([[ 2.3110306 ,  2.86287398],
         [ 1.32544402,  0.65607529],
         [ 0.40782893,  2.02786907]]), 0.5196582527686241)
  

• kmeans2(data, k, iter = 10, thresh = 1.0000000000000001e-05, minit = 'random', missing = 'warn')

  Classify a set of points into k clusters using kmean algorithm.

  The algorithm works by minimizing the euclidian distance between data points of cluster means. This version is more complete than kmean (has several initialisation methods).

  Parameters:

  data : ndarray Expect a rank 1 or 2 array. Rank 1 are assumed to describe one dimensional data, rank 2 multidimensional data, in which case one row is one observation. k : int or ndarray Number of clusters. If minit arg is 'matrix', or if a ndarray is given instead, it is interpreted as initial cluster to use instead. niter : int Number of iterations to run. thresh : float (not used yet). minit : string Method for initialization. Available methods are random, points and uniform: random uses k points drawn from a Gaussian random generator which mean and variances are estimated from the data. points choses k points at random from the points in data. uniform choses k points from the data such are they form a uniform grid od the dataset (not supported yet). matrix means that k has to be interpreted as initial clusters (format is the same than data).

  Returns:

  clusters : ndarray the found clusters (one cluster per row). label : ndarray label[i] gives the label of the ith obversation, that its centroid is cluster[label[i]].

• py_vq(obs, code_book)

  Python version of vq algorithm.

  The algorithm simply computes the euclidian distance between each observation and every frame in the code_book.

  Parameters:	obs : ndarray Expects a rank 2 array. Each row is one observation. code_book : ndarray Code book to use. Same format than obs. Should have same number of features (eg columns) than obs.
  Note:	This function is slower than the C versions, but it works for all input types. If the inputs have the wrong types for the C versions of the function, this one is called as a last resort. Its about 20 times slower than the C versions.
  Returns:	code : ndarray code[i] gives the label of the ith obversation, that its code is code_book[code[i]]. mind_dist : ndarray min_dist[i] gives the distance between the ith observation and its corresponding code.

• py_vq2(obs, code_book)

  2nd Python version of vq algorithm.

  The algorithm simply computes the euclidian distance between each observation and every frame in the code_book/

  Parameters:	obs : ndarray Expect a rank 2 array. Each row is one observation. code_book : ndarray Code book to use. Same format than obs. Should have same number of features (eg columns) than obs.
  Note:	This could be faster when number of codebooks is small, but it becomes a real memory hog when codebook is large. It requires NxMxO storage where N=number of obs, M = number of features, and O = number of codes.
  Returns:	code : ndarray code[i] gives the label of the ith obversation, that its code is code_book[code[i]]. mind_dist : ndarray min_dist[i] gives the distance between the ith observation and its corresponding code.

• vq(obs, code_book)

  Vector Quantization: assign features sets to codes in a code book.

  Vector quantization determines which code in the code book best represents an observation of a target. The features of each observation are compared to each code in the book, and assigned the one closest to it. The observations are contained in the obs array. These features should be "whitened," or nomalized by the standard deviation of all the features before being quantized. The code book can be created using the kmeans algorithm or something similar.

  Parameters:

  obs : ndarray Each row of the array is an observation. The columns are the "features" seen during each observation The features must be whitened first using the whiten function or something equivalent. code_book : ndarray. The code book is usually generated using the kmeans algorithm. Each row of the array holds a different code, and the columns are the features of the code. # f0 f1 f2 f3 code_book = [[ 1., 2., 3., 4.], #c0 [ 1., 2., 3., 4.], #c1 [ 1., 2., 3., 4.]]) #c2

  Returns:

  code : ndarray If obs is a NxM array, then a length N array is returned that holds the selected code book index for each observation. dist : ndarray The distortion (distance) between the observation and its nearest code

  Notes

  This currently forces 32 bit math precision for speed. Anyone know of a situation where this undermines the accuracy of the algorithm?

  Examples

  >>> from numpy import array
  >>> from scipy.cluster.vq import vq
  >>> code_book = array([[1.,1.,1.],
  ...                    [2.,2.,2.]])
  >>> features  = array([[  1.9,2.3,1.7],
  ...                    [  1.5,2.5,2.2],
  ...                    [  0.8,0.6,1.7]])
  >>> vq(features,code_book)
  (array([1, 1, 0],'i'), array([ 0.43588989,  0.73484692,  0.83066239]))
  

• whiten(obs)

  Normalize a group of observations on a per feature basis.

  Before running kmeans algorithms, it is beneficial to "whiten", or scale, the observation data on a per feature basis. This is done by dividing each feature by its standard deviation across all observations.

  Parameters:	obs : ndarray Each row of the array is an observation. The columns are the "features" seen during each observation # f0 f1 f2 obs = [[ 1., 1., 1.], #o0 [ 2., 2., 2.], #o1 [ 3., 3., 3.], #o2 [ 4., 4., 4.]]) #o3 XXX perhaps should have an axis variable here.
  Returns:	result : ndarray Contains the values in obs scaled by the standard devation of each column.

  Examples

  >>> from numpy import array
  >>> from scipy.cluster.vq import whiten
  >>> features  = array([[  1.9,2.3,1.7],
  ...                    [  1.5,2.5,2.2],
  ...                    [  0.8,0.6,1.7,]])
  >>> whiten(features)
  array([[ 3.41250074,  2.20300046,  5.88897275],
         [ 2.69407953,  2.39456571,  7.62102355],
         [ 1.43684242,  0.57469577,  5.88897275]])
  

Imported Names