Skip to content

Additive logratio transform

alr_transform(df, column=None, keep_denominator_column=False)

Perform an additive logratio transformation on the data.

Parameters:

Name Type Description Default
df DataFrame

A dataframe of compositional data.

 required
column Optional[str]

The name of the column to be used as the denominator column.

 None
keep_denominator_column bool

Whether to include the denominator column in the result. If True, the returned dataframe retains its original shape.

 False

Returns:

Type Description
DataFrame

A new dataframe containing the ALR transformed data.

Raises:

Type Description
InvalidColumnException

The input column isn't found in the dataframe.
InvalidCompositionException

Data is not normalized to the expected value.
NumericValueSignException

Data contains zeros or negative values.
Source code in eis_toolkit/transformations/coda/alr.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
@beartype
def alr_transform(
    df: pd.DataFrame, column: Optional[str] = None, keep_denominator_column: bool = False
) -> pd.DataFrame:
    """
    Perform an additive logratio transformation on the data.

    Args:
        df: A dataframe of compositional data.
        column: The name of the column to be used as the denominator column.
        keep_denominator_column: Whether to include the denominator column in the result. If True, the returned
            dataframe retains its original shape.

    Returns:
        A new dataframe containing the ALR transformed data.

    Raises:
        InvalidColumnException: The input column isn't found in the dataframe.
        InvalidCompositionException: Data is not normalized to the expected value.
        NumericValueSignException: Data contains zeros or negative values.
    """
    check_in_simplex_sample_space(df)

    if column is not None and column not in df.columns:
        raise InvalidColumnException(f"The column {column} was not found in the dataframe.")

    column = column if column is not None else df.columns[-1]

    columns = [col for col in df.columns]

    if not keep_denominator_column and column in columns:
        columns.remove(column)

    return rename_columns_by_pattern(_alr_transform(df, columns, column))

inverse_alr(df, denominator_column, scale=1.0)

Perform the inverse transformation for a set of ALR transformed data.

Parameters:

Name Type Description Default
df DataFrame

A dataframe of ALR transformed compositional data.

 required
denominator_column str

The name of the denominator column.

 required
scale Number

The value to which each composition should be normalized. Eg., if the composition is expressed as percentages, scale=100.

 1.0

Returns:

Type Description
DataFrame

A dataframe containing the inverse transformed data.

Raises:

Type Description
NumericValueSignException

The input scale value is zero or less.
Source code in eis_toolkit/transformations/coda/alr.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@beartype
def inverse_alr(df: pd.DataFrame, denominator_column: str, scale: Number = 1.0) -> pd.DataFrame:
    """
    Perform the inverse transformation for a set of ALR transformed data.

    Args:
        df: A dataframe of ALR transformed compositional data.
        denominator_column: The name of the denominator column.
        scale: The value to which each composition should be normalized. Eg., if the composition is expressed
            as percentages, scale=100.

    Returns:
        A dataframe containing the inverse transformed data.

    Raises:
        NumericValueSignException: The input scale value is zero or less.
    """
    if scale <= 0:
        raise NumericValueSignException("The scale value should be positive.")

    return _inverse_alr(df, denominator_column, scale)