Skip to content

Isometric logratio transform

single_ilr_transform(df, subcomposition_1, subcomposition_2)

Perform a single isometric logratio transformation on the provided subcompositions.

Returns ILR balances. Column order matters.

Parameters:

Name Type Description Default
df DataFrame

A dataframe of shape [N, D] of compositional data.

 required
subcomposition_1 Sequence[str]

Names of the columns in the numerator part of the ratio.

 required
subcomposition_2 Sequence[str]

Names of the columns in the denominator part of the ratio.

 required

Returns:

Type Description
Series

A series of length N containing the transforms.

Raises:

Type Description
InvalidColumnException

One or more subcomposition columns are not found in the input dataframe.
InvalidCompositionException

Data is not normalized to the expected value or one or more columns are found in both subcompositions.
InvalidParameterValueException

At least one subcomposition provided was empty.
NumericValueSignException

Data contains zeros or negative values.
Source code in eis_toolkit/transformations/coda/ilr.py 
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@beartype
def single_ilr_transform(
    df: pd.DataFrame, subcomposition_1: Sequence[str], subcomposition_2: Sequence[str]
) -> pd.Series:
    """
    Perform a single isometric logratio transformation on the provided subcompositions.

    Returns ILR balances. Column order matters.

    Args:
        df: A dataframe of shape [N, D] of compositional data.
        subcomposition_1: Names of the columns in the numerator part of the ratio.
        subcomposition_2: Names of the columns in the denominator part of the ratio.

    Returns:
        A series of length N containing the transforms.

    Raises:
        InvalidColumnException: One or more subcomposition columns are not found in the input dataframe.
        InvalidCompositionException: Data is not normalized to the expected value or
            one or more columns are found in both subcompositions.
        InvalidParameterValueException: At least one subcomposition provided was empty.
        NumericValueSignException: Data contains zeros or negative values.
    """
    check_in_simplex_sample_space(df)

    if not (subcomposition_1 and subcomposition_2):
        raise InvalidParameterValueException("A subcomposition should contain at least one column.")

    if not (check_columns_valid(df, subcomposition_1) and check_columns_valid(df, subcomposition_2)):
        raise InvalidColumnException("Not all of the input columns were found in the input dataframe.")

    if check_lists_overlap(subcomposition_1, subcomposition_2):
        raise InvalidCompositionException("The subcompositions overlap.")

    return _single_ilr_transform(df, subcomposition_1, subcomposition_2)