# Simplex 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. 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. 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. 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.

`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. 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. 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). 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. 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). 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. x : NumPy array, shape (n+1,) or (k,n+1) The original compositions.