Simplex Documentation¶
This page contains the Simplex Package documentation.
Subpackages¶
The grid
Module¶
Functions for creating grids on the simplex.

cmpy.simplex.grid.
esimplex_gridsample
(length, depth, base=2, scale=1)¶ Returns a generator over simplex points, determined by a grid.
 For length = 3, the points will exist on the hyperplane:
 x + y + z = 1.
Note that x, y, and z are not necessarily limited to be in (0,1).
Parameters: length : int
The number of elements in each distribution. The dimensionality of the simplex is length1.
depth : int
Controls the density of the grid. The number of points on the simplex is given by:
(base**depth + length  1)! / (base**depth)! / (length1)!
At each depth, we exponentially increase the number of points.
base : int
The rate at which we divide probabilities.
scale : float
A specification of the sampling area. Essentially, the scale sets the radius of simplex relative to the standard simplex.
Examples
>>> list(cmpy.simplex_gridsample(2,2,scale=2)) [(0.70710678118654757, 1.7071067811865475), (0.10355339059327384, 1.1035533905932735), (0.49999999999999989, 0.49999999999999989), (1.1035533905932735, 0.10355339059327384), (1.7071067811865475, 0.70710678118654757)]

cmpy.simplex.grid.
simplex_gridsample
(length, depth, base=2)¶ Returns a generator over simplex points, determined by a grid.
The grid is “triangular” in Euclidean space. The grid is not a Cartesian grid in the inverselog ratio transformation.
Parameters: length : int
The number of elements in each distribution. The dimensionality of the simplex is length1.
depth : int
Controls the density of the grid. The number of points on the simplex is given by:
(base**depth + length  1)! / (base**depth)! / (length1)!
At each depth, we exponentially increase the number of points.
base : int
The rate at which we divide probabilities.
Examples
>>> list(cmpy.simplex_gridsample(2,2)) [(0.0, 1.0), (0.25, 0.75), (0.5, 0.5), (0.75, 0.25), (1.0, 0.0)]
The sampling
Module¶
Functions related to sampling distributions.

cmpy.simplex.sampling.
uniform_unitsum
(n, size=None, scale=1, prng=None)¶ Returns a point drawn uniformly from the (n1)simplex.
A point on the (n1)simplex is an ndimensional vector. For example, a point on the 2simplex (equilaterial triangle in 3space) consists of 3 elements which sum to one.
Parameters: n : int
The dimensionality of point on the simplex. Essentially, the length of the NumPy array that will be returned.
size : int, None
The number of samples to draw.
scale : float
By default, we sample from the standard simplex only. If scale is greater than one, we are sampling from the extended simplex and there is no longer a nonnegativity constaint on the elements of the vector. For scales less than 1, we are sampling from a restricted simplex. The scale sets the radius of the simplex as measured from the uniform distribution.
prng : random number generator
Returns: v : NumPy array
The drawn samples, arranged according to size. If size is None, then the shape of out is (n,). If size=k, then the shape of out is (k,n). Each row is an ndimensional sample from the (n1)dimensional distribution on the simplex.

cmpy.simplex.sampling.
uniform_zerosum
(n, size=None, scale=1, prng=None)¶ Returns the difference of two points drawn uniformly from the nsimplex.
A point on the (n1)simplex is an ndimensional vector. For example, a point on the 2simplex (equilaterial triangle in 3space) consists of 3 elements which sum to one.
Parameters: n : int
The dimensionality of point on the simplex. Essentially, the length of the NumPy array that will be returned.
size : int, None
The number of samples to draw.
scale : float
By default, we sample from the standard simplex only. If scale is greater than one, we are sampling from the extended simplex and there is no longer a nonnegativity constaint on the elements of the vector. For scales less than 1, we are sampling from a restricted simplex. The scale sets the radius of the simplex as measured from the uniform distribution.
prng : random number generator
Returns: v : NumPy array
The drawn samples, arranged according to size. If size is None, then the shape of out is (n,). If size=k, then the shape of out is (k,n). Each row is an ndimensional sample from the (n1)dimensional distribution on the simplex. The elements of each sample sum to zero.

cmpy.simplex.sampling.
normal_unitsum
(mean, cov, size=None, prng=None)¶ Returns random samples from a multivariate normal distribution.
A point on the (n1)simplex is an ndimensional vector. For example, a point on the 2simplex (equilaterial triangle in 3space) consists of 3 elements which sum to one.
Parameters: mean : NumPy array, shape (n,)
Mean of the normal distribution. Note, this distribution will be transformed into ilr coordinates (which is in R^{n1}).
cov : NumPy array, shape (n1, n1)
Covariance matrix of the normal distribution in R^{n1}.
size : int, None
The number of samples to draw.
prng : random number generator
A random number generator which has a method supporting the following call: multivariate_normal(mean, cov, size). If unspecified, then we use the random number generator at cmpy.math.prng.
Returns: out : NumPy array
The drawn samples, arranged according to size. If size is None, then the shape of out is (n,). If size=k, then the shape of out is (k,n). Each row is an ndimensional sample from the (n1)dimensional distribution.
The aitchison
Module¶
Functions for manipulating compositions using the Aitchison geometry.
Throughout, we assume the compositions are defined such that the sum of the components is 1.
http://www.springerlink.com/content/wx1166n56n685v82/

cmpy.simplex.aitchison.
closure
(x)¶ Returns the closure operation applied to the composition x.
The closure operation renormalizes x so that its components sum to one.
Parameters: x : NumPy array, shape (n,) or (k,n)
The array can be one or twodimensional. If onedimensional, it is treated as a single composition. If twodimensional, each row is treated as a composition and will be normalized individually.
Returns: cx : NumPy array, shape (n,) or (k,n)
The closure of x.

cmpy.simplex.aitchison.
subcomposition
(x, indexes)¶ Returns the subcomposition over the specified indexes.
The subcomposition is the closure of a subset of events in the composition.
Parameters: x : NumPy array, shape (n,) or (k,n)
The composition(s) that will be truncated and renormalized.
Returns: xsub : NumPy array, shape (len(indexes),) or (k, len(indexes))
The subcompositions of x.

cmpy.simplex.aitchison.
perturbation
(x, dx)¶ Returns the perturbation of x by dx.
Perturbation is the closure of the elementwise product. It is equivalent to translation (inner sum) in standard Euclidean space.
Parameters: x : NumPy array, shape (n,) or (k,n)
The composition (or k compositions) to be perturbed.
dx : NumPy array
The perturbation composition or (k perturbation compositions).
Returns: px : NumPy array, shape (n,) or (k,n)
The perturbation of x by dx.

cmpy.simplex.aitchison.
power
(x, a)¶ Returns the result of powering x by a.
The power transformation is the closure of raising each element to the `a`th power. It is equivalent to scalar multiplication (outer product).
Parameters: x : NumPy array, shape (n,) or (k,n)
The composition (or k compositions) which will be powered.
a : NumPy array, shape () or (k,)
The power (or k powers) to which the composition(s) is raised.
Returns: px : NumPy array, shape (n,) or (k,n)
The result of powering x by a.

cmpy.simplex.aitchison.
add
(x, dx)¶ Returns the perturbation of x by dx.
Perturbation is the closure of the elementwise product. It is equivalent to translation (inner sum) in standard Euclidean space.
Parameters: x : NumPy array, shape (n,) or (k,n)
The composition (or k compositions) to be perturbed.
dx : NumPy array
The perturbation composition or (k perturbation compositions).
Returns: px : NumPy array, shape (n,) or (k,n)
The perturbation of x by dx.

cmpy.simplex.aitchison.
sub
(x, y)¶ Returns the difference of compositions.
Parameters: x : NumPy array, shape (n,) or (k,n)
The composition that will be subtracted from.
y : NumPy array, shape (n,) or (k,n)
The composition to be subtracted.
Returns: z : NumPy array, shape (n,) or (k,n)
The result of y subtracted from x.

cmpy.simplex.aitchison.
inner
(x, y)¶ Returns the Aitchison inner product between x and y.
Parameters: x,y : NumPy array, shape (n,) or (k,n)
Compositions to be used in the inner product.
Returns: z : NumPy array, shape () or (k,)
The inner product of x and y. If x and y are 2D arrays, then the inner product is done rowwise and z is a 1D array of floats. Otherwise, a float is returned.

cmpy.simplex.aitchison.
norm
(x)¶ Returns the norm of x.
Parameters: x : NumPy array, shape (n,) or (k,n)
The composition(s) to be normed.
Returns: n : NumPy array, shape () or (k,)
The norm(s) of the composition(s).

cmpy.simplex.aitchison.
dist
(x, y)¶ Returns the distance between x and y.
Parameters: x, y : NumPy array, shape (n,) or (k,n)
The compositions whose distance is computed.
Returns: d : NumPy array, shape () or (k,)
The distance between x and y.

cmpy.simplex.aitchison.
metric
(x, y)¶ Returns the distance between x and y.
Parameters: x, y : NumPy array, shape (n,) or (k,n)
The compositions whose distance is computed.
Returns: d : NumPy array, shape () or (k,)
The distance between x and y.

cmpy.simplex.aitchison.
clr
(x)¶ Returns the centered logratio transformation of x.
The centered logratio transformation of x is defined as:
 clr(x) = log_2( frac{x}{g(x)} )
 = log_2(x)  <log_2 x_i>
where g(x) is the geometric mean of x.
Parameters: x : NumPy array, shape (n,) or (k,n)
Composition(s) to be transformed by clr.
Returns: y : NumPy array, shape (n,) or (k,n)
Centered logratio transformation(s) of x.

cmpy.simplex.aitchison.
alr
(x)¶ Returns the additive logratio transformation of x.
The additive logratio transformation of x (with respect to the last component in the composition) is defined as:
alr(x) = [ log_2 x_1 / x_D, ldots, log_2 frac{x_{D1}}{x_D} ]where x is a composition of length D. Essentially, take the first D1 components and divide them by the Dth component.
Parameters: x : NumPy array, shape (n,) or (k,n)
Composition(s) to be transformed by alr.
Returns: y : NumPy array, shape (n1,) or (k,n1)
Additive logratio transformation(s) of x.

cmpy.simplex.aitchison.
ilr
(x)¶ Returns the isometric logratio transformation of x.
The isometric logratio transformation of x, with respect to the canonical, orthonormal basis defined on the simplex (equation 18 in the paper), is defined as:
y_i = ilr(x)_i = k_i log_2 frac{g(x_1,ldots,x_i)}{x_{i+1}}where
k_i = sqrt{ frac{i}{i+1} }
g_i = bigl( prod_{k=1}^i x_k bigr)^{1/i}
for i = 1, 2, ..., D1.
Parameters: x : NumPy array, shape (n,) or (k,n)
Composition(s) to be transformed by ilr.
Returns: y : NumPy array, shape (n1,) or (k, n1)
Isometric logratio transformation(s) of x.

cmpy.simplex.aitchison.
basis
(n)¶ Returns an orthonormal basis wrt the Aitchison inner product.
Parameters: n : int
The dimensionality of the basis. For example, the 2simplex has a twodimensional basis.
Returns: b : NumPy array, shape (n, `n`+1)
The basis for the nsimplex, consisting of vectors of length `n`+1.

cmpy.simplex.aitchison.
clr_inv
(xclr)¶ “Returns the inverse centered logratio transformation of x.
Parameters: xclr : NumPy array, shape (n,) or (k,n)
The centered logratio transformations of x.
Returns: x : NumPy array, shape (n,) or (k,n)
The original compositions.

cmpy.simplex.aitchison.
alr_inv
(xalr)¶ Returns the inverse additive logratio transformation of x.
Parameters: xalr : NumPy array, shape (n,) or (k,n)
The additive logratio transformations of x.
Returns: x : NumPy array, shape (n+1,) or (k,n+1)
The original compositions
Notes
The sum of the composition is assumed to be 1.

cmpy.simplex.aitchison.
ilr_inv
(xilr)¶ Returns the inverse isometric logratio transformation of x.
Parameters: xilr : NumPy array, shape (n,) or (k,n)
The isometric logratio transformations of x.
Returns: x : NumPy array, shape (n+1,) or (k,n+1)
The original compositions.