Simplex Documentation

This page contains the Simplex Package documentation.

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 length-1.

depth : int

Controls the density of the grid. The number of points on the simplex is given by:

(base**depth + length - 1)! / (base**depth)! / (length-1)!

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 inverse-log ratio transformation.

Parameters:

length : int

The number of elements in each distribution. The dimensionality of the simplex is length-1.

depth : int

Controls the density of the grid. The number of points on the simplex is given by:

(base**depth + length - 1)! / (base**depth)! / (length-1)!

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 (n-1)-simplex.

A point on the (n-1)-simplex is an n-dimensional vector. For example, a point on the 2-simplex (equilaterial triangle in 3-space) 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

A random number generator which returns `k’ random numbers when `prng.rand(k)’ is called. If unspecified, then we use the random number generator at cmpy.math.prng.

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 n-dimensional sample from the (n-1)-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 n-simplex.

A point on the (n-1)-simplex is an n-dimensional vector. For example, a point on the 2-simplex (equilaterial triangle in 3-space) 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

A random number generator which returns `k’ random numbers when `prng.rand(k)’ is called. If unspecified, then we use the random number generator at cmpy.math.prng.

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 n-dimensional sample from the (n-1)-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 (n-1)-simplex is an n-dimensional vector. For example, a point on the 2-simplex (equilaterial triangle in 3-space) 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^{n-1}).

cov : NumPy array, shape (n-1, n-1)

Covariance matrix of the normal distribution in R^{n-1}.

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 n-dimensional sample from the (n-1)-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 two-dimensional. If one-dimensional, it is treated as a single composition. If two-dimensional, 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 element-wise 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 element-wise 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 row-wise 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 log-ratio transformation of x.

The centered log-ratio 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 log-ratio transformation(s) of x.

cmpy.simplex.aitchison.alr(x)

Returns the additive log-ratio transformation of x.

The additive log-ratio 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_{D-1}}{x_D} ]

where x is a composition of length D. Essentially, take the first D-1 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 (n-1,) or (k,n-1)

Additive log-ratio transformation(s) of x.

cmpy.simplex.aitchison.ilr(x)

Returns the isometric log-ratio transformation of x.

The isometric log-ratio 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, ..., D-1.

Parameters:

x : NumPy array, shape (n,) or (k,n)

Composition(s) to be transformed by ilr.

Returns:

y : NumPy array, shape (n-1,) or (k, n-1)

Isometric log-ratio 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 2-simplex has a two-dimensional basis.

Returns:

b : NumPy array, shape (n, `n`+1)

The basis for the n-simplex, consisting of vectors of length `n`+1.

cmpy.simplex.aitchison.clr_inv(xclr)

“Returns the inverse centered log-ratio transformation of x.

Parameters:

xclr : NumPy array, shape (n,) or (k,n)

The centered log-ratio 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 log-ratio transformation of x.

Parameters:

xalr : NumPy array, shape (n,) or (k,n)

The additive log-ratio 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 log-ratio transformation of x.

Parameters:

xilr : NumPy array, shape (n,) or (k,n)

The isometric log-ratio transformations of x.

Returns:

x : NumPy array, shape (n+1,) or (k,n+1)

The original compositions.