skbio.stats.composition.clr#

skbio.stats.composition.clr(mat, axis=-1, validate=True)[source]#

Perform centre log ratio (CLR) transformation.

This function transforms compositions from Aitchison geometry to the real space. The \(clr\) transform is both an isometry and an isomorphism defined on the following spaces:

\[clr: S^D \rightarrow U\]

where \(U= \{x :\sum\limits_{i=1}^D x = 0 \; \forall x \in \mathbb{R}^D\}\)

It is defined for a composition \(x\) as follows:

\[clr(x) = \ln\left[\frac{x_1}{g_m(x)}, \ldots, \frac{x_D}{g_m(x)}\right]\]

where \(g_m(x) = (\prod\limits_{i=1}^{D} x_i)^{1/D}\) is the geometric mean of \(x\).

Changed in version 0.7.0: The function now works on any dimension in arrays of any number of dimensions.

Parameters:
matarray_like of shape (…, n_components, …)

A matrix of positive proportions.

axisint, optional

Axis along which CLR transformation will be performed. Each vector on this axis is considered as a composition. Default is the last axis (-1).

Added in version 0.7.0.

validatebool, default True

Check if the matrix consists of strictly positive values.

Added in version 0.7.0.

Returns:
ndarray of shape (…, n_components, …)

CLR-transformed matrix.

See also

clr_inv

Examples

>>> import numpy as np
>>> from skbio.stats.composition import clr
>>> x = np.array([.1, .3, .4, .2])
>>> clr(x)
array([-0.79451346,  0.30409883,  0.5917809 , -0.10136628])