Merge pull request #244 from GispoCoding/218-coda-transforms

218 coda transforms

Author: nmaarnio

docs/transformations/coda/alr.md

@@ -0,0 +1,3 @@
+# Additive logratio transform
+
+::: eis_toolkit.transformations.coda.alr

docs/transformations/coda/clr.md

@@ -0,0 +1,3 @@
+# Centered logratio transform
+
+::: eis_toolkit.transformations.coda.clr

docs/transformations/coda/ilr.md

@@ -0,0 +1,3 @@
+# Isometric logratio transform
+
+::: eis_toolkit.transformations.coda.ilr

docs/transformations/coda/pairwise.md

@@ -0,0 +1,3 @@
+# Pairwise logratio transform
+
+::: eis_toolkit.transformations.coda.pairwise

docs/transformations/coda/plr.md

@@ -0,0 +1,3 @@
+# Pivot logratio transform
+
+::: eis_toolkit.transformations.coda.plr

eis_toolkit/exceptions.py

@@ -88,3 +88,11 @@ class InvalidModelException(Exception):
 
 class InvalidDatasetException(Exception):
     """Exception error class when the dataset is null."""
+
+
+class NonNumericDataException(Exception):
+    """Exception error class for when the given data includes non-numeric values."""
+
+
+class InvalidCompositionException(Exception):
+    """Exception error class for when the data is not in suitable form for compositional data transforms."""

eis_toolkit/transformations/coda/__init__.py

@@ -0,0 +1,86 @@
+from numbers import Number
+
+import numpy as np
+import pandas as pd
+from beartype import beartype
+from beartype.typing import Sequence
+
+from eis_toolkit.exceptions import InvalidColumnException, NumericValueSignException
+from eis_toolkit.utilities.aitchison_geometry import _closure
+from eis_toolkit.utilities.checks.compositional import check_in_simplex_sample_space
+from eis_toolkit.utilities.miscellaneous import rename_columns_by_pattern
+
+
+@beartype
+def _alr_transform(df: pd.DataFrame, columns: Sequence[str], denominator_column: str) -> pd.DataFrame:
+
+    ratios = df[columns].div(df[denominator_column], axis=0)
+    return np.log(ratios)
+
+
+@beartype
+def alr_transform(df: pd.DataFrame, column: 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))
+
+
+@beartype
+def _inverse_alr(df: pd.DataFrame, denominator_column: str, scale: Number = 1.0) -> pd.DataFrame:
+    dfc = df.copy()
+
+    if denominator_column not in dfc.columns.values:
+        # Add the denominator column
+        dfc[denominator_column] = 0.0
+
+    return _closure(np.exp(dfc), scale)
+
+
+@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)

eis_toolkit/transformations/coda/alr.py

@@ -0,0 +1,79 @@
+from numbers import Number
+
+import numpy as np
+import pandas as pd
+from beartype import beartype
+from beartype.typing import Optional, Sequence
+from scipy.stats import gmean
+
+from eis_toolkit.exceptions import NumericValueSignException
+from eis_toolkit.utilities.aitchison_geometry import _closure
+from eis_toolkit.utilities.checks.compositional import check_in_simplex_sample_space
+from eis_toolkit.utilities.miscellaneous import rename_columns, rename_columns_by_pattern
+
+
+@beartype
+def _centered_ratio(row: pd.Series) -> pd.Series:
+
+    return row / gmean(row)
+
+
+@beartype
+def _clr_transform(df: pd.DataFrame) -> pd.DataFrame:
+
+    dfc = df.copy()
+    dfc = dfc.apply(_centered_ratio, axis=1)
+
+    return np.log(dfc)
+
+
+@beartype
+def clr_transform(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Perform a centered logratio transformation on the data.
+
+    Args:
+        df: A dataframe of compositional data.
+
+    Returns:
+        A new dataframe containing the CLR transformed data.
+
+    Raises:
+        InvalidCompositionException: Data is not normalized to the expected value.
+        NumericValueSignException: Data contains zeros or negative values.
+    """
+    check_in_simplex_sample_space(df)
+    return rename_columns_by_pattern(_clr_transform(df))
+
+
+@beartype
+def _inverse_clr(df: pd.DataFrame, colnames: Optional[Sequence[str]] = None, scale: Number = 1.0) -> pd.DataFrame:
+    inverse = _closure(np.exp(df), scale)
+
+    if colnames is not None:
+        return rename_columns(inverse, colnames)
+
+    return inverse
+
+
+@beartype
+def inverse_clr(df: pd.DataFrame, colnames: Optional[Sequence[str]] = None, scale: Number = 1.0) -> pd.DataFrame:
+    """
+    Perform the inverse transformation for a set of CLR transformed data.
+
+    Args:
+        df: A dataframe of CLR transformed compositional data.
+        colnames: List of column names to rename the columns to.
+        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_clr(df, colnames, scale)

eis_toolkit/transformations/coda/clr.py

@@ -0,0 +1,100 @@
+import numpy as np
+import pandas as pd
+from beartype import beartype
+from beartype.typing import Sequence
+from scipy.stats import gmean
+
+from eis_toolkit.exceptions import InvalidColumnException, InvalidCompositionException, InvalidParameterValueException
+from eis_toolkit.utilities.checks.compositional import check_in_simplex_sample_space
+from eis_toolkit.utilities.checks.dataframe import check_columns_valid
+from eis_toolkit.utilities.checks.parameter import check_lists_overlap, check_numeric_value_sign
+
+
+@beartype
+def _calculate_ilr_scaling_factor(c1: int, c2: int) -> np.float64:
+    """
+    Calculate the scaling factor for the ILR transform.
+
+    Args:
+        c1: The cardinality of the first subcomposition.
+        c2: The cardinality of the second subcomposition.
+
+    Returns:
+        The scaling factor.
+
+    Raises:
+        InvalidParameterValueException: One or both of the input values are zero or negative.
+    """
+    if not (check_numeric_value_sign(c1) and check_numeric_value_sign(c2)):
+        raise InvalidParameterValueException("Input values must both be positive integers.")
+
+    return np.sqrt((c1 * c2) / np.float64(c1 + c2))
+
+
+@beartype
+def _geometric_mean_logratio(
+    row: pd.Series, subcomposition_1: Sequence[str], subcomposition_2: Sequence[str]
+) -> np.float64:
+
+    numerator = gmean(row[subcomposition_1])
+    denominator = gmean(row[subcomposition_2])
+    return np.log(numerator / denominator)
+
+
+@beartype
+def _single_ilr_transform(
+    df: pd.DataFrame, subcomposition_1: Sequence[str], subcomposition_2: Sequence[str]
+) -> pd.Series:
+
+    dfc = df.copy()
+
+    c1 = len(subcomposition_1)
+    c2 = len(subcomposition_2)
+
+    # A Series to hold the transformed rows
+    ilr_values = pd.Series([0.0] * df.shape[0])
+
+    for idx, row in dfc.iterrows():
+        ilr_values[idx] = _geometric_mean_logratio(row, subcomposition_1, subcomposition_2)
+
+    ilr_values = _calculate_ilr_scaling_factor(c1, c2) * ilr_values
+
+    return ilr_values
+
+
+@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)

eis_toolkit/transformations/coda/ilr.py

@@ -0,0 +1,73 @@
+from numbers import Number
+
+import numpy as np
+import pandas as pd
+from beartype import beartype
+
+from eis_toolkit.exceptions import InvalidColumnException, InvalidParameterValueException
+from eis_toolkit.utilities.checks.dataframe import check_dataframe_contains_zeros
+
+
+@beartype
+def _single_pairwise_logratio(numerator: Number, denominator: Number) -> np.float64:
+
+    return np.log(numerator / float(denominator))
+
+
+@beartype
+def single_pairwise_logratio(numerator: Number, denominator: Number) -> np.float64:
+    """
+    Perform a pairwise logratio transformation on the given values.
+
+    Args:
+        numerator: The numerator in the ratio.
+        denominator: The denominator in the ratio.
+
+    Returns:
+        The transformed value.
+
+    Raises:
+        InvalidParameterValueException: One or both input values are zero.
+    """
+    if numerator == 0 or denominator == 0:
+        raise InvalidParameterValueException("Input values cannot be zero.")
+
+    return _single_pairwise_logratio(numerator, denominator)
+
+
+@beartype
+def _pairwise_logratio(df: pd.DataFrame, numerator_column: str, denominator_column: str) -> pd.Series:
+    dfc = df.copy()
+
+    result = pd.Series([0.0] * df.shape[0])
+
+    for idx, row in dfc.iterrows():
+        result[idx] = single_pairwise_logratio(row[numerator_column], row[denominator_column])
+
+    return result
+
+
+@beartype
+def pairwise_logratio(df: pd.DataFrame, numerator_column: str, denominator_column: str) -> pd.Series:
+    """
+    Perform a pairwise logratio transformation on the given columns.
+
+    Args:
+        df: The dataframe containing the columns to use in the transformation.
+        numerator_column: The name of the column to use as the numerator column.
+        denominator_column: The name of the column to use as the denominator.
+
+    Returns:
+        A series containing the transformed values.
+
+    Raises:
+        InvalidColumnException: One or both of the input columns are not found in the dataframe.
+        InvalidParameterValueException: The input columns contain at least one zero value.
+    """
+    if numerator_column not in df.columns or denominator_column not in df.columns:
+        raise InvalidColumnException("At least one input column is not found in the dataframe.")
+
+    if check_dataframe_contains_zeros(df[[numerator_column, denominator_column]]):
+        raise InvalidParameterValueException("The input columns contain at least one zero value.")
+
+    return _pairwise_logratio(df, numerator_column, denominator_column)