Skip to main content
`Ctrl`+`K`

# skbio.stats.composition.alr

skbio.stats.composition.alr(mat, ref_idx=0, axis=-1, validate=True)

  Perform additive log ratio (ALR) transformation.

  This function transforms compositions from a D-part Aitchison simplex to a non-isometric real space of D-1 dimensions. The argument `ref_idx` defines the index of the column used as the reference (a common denominator). The \(alr\) transformed data are amenable to multivariate analysis as long as statistics don’t involve distances.

  \[alr: S^D \rightarrow \mathbb{R}^{D-1}\]

  The alr transformation is defined as follows

  \[alr(x) = \left[ \ln \frac{x_1}{x_D}, \ldots, \ln \frac{x_{D-1}}{x_D} \right]\]

  where \(D\) is the index of the part used as the reference.

  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 proportions.

    ref_idx int, optional

      Index on the target axis which should be used as the reference composition (denominator). Default is 0 (the first position).

      Changed in version 0.7.0: Renamed from `denominator_idx`. The old name is kept as an alias.

    axis int, optional

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

      Added in version 0.7.0.

    validate: bool, default True

      Check whether the input is positive, whether the mat is 2D.

      Added in version 0.7.0.

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

      ALR-transformed data projected in a non-isometric real space of \(D - 1\) dimensions for a D-parts composition.

  See also

  `alr_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 alr
      >>> x = np.array([.1, .3, .4, .2])
      >>> alr(x)
      array([ 1.09861229,  1.38629436,  0.69314718])