Skip to main content
`Ctrl`+`K`

# skbio.stats.composition.clr

skbio.stats.composition.clr(mat, axis=-1, validate=True)

  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:
    mat array_like of shape (…, n_components, …)

      A matrix of positive proportions.

    axis int, 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.

    validate bool, 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`

  Notes

  Note

  This function supports the Python array API standard. Compatible array backends:

  Backend | CPU | GPU
  --- | --- | ---
  NumPy | ✓ | n/a
  CuPy | n/a | ✓
  PyTorch | ✓ | ✓
  JAX | ✓ | ✓
  Dask | ✓ | n/a

  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])