mdr/utils/utils.py
def two_way_information_gain(X, Y, Z, base=2):
    """Calculates the two-way information gain between three variables, I(X;Y;Z), in the given base

    IG(X;Y;Z) indicates the information gained about variable Z by the joint variable X_Y, after removing
    the information that X and Y have about Z individually. Thus, two-way information gain measures the
    synergistic predictive value of variables X and Y about variable Z.

    Parameters
    ----------
    X: array-like (# samples)
        An array of values for which to compute the 2-way information gain
    Y: array-like (# samples)
        An array of values for which to compute the 2-way information gain
    Z: array-like (# samples)
        An array of outcome values for which to compute the 2-way information gain
    base: integer (default: 2)
        The base in which to calculate 2-way information

    Returns
    ----------
    mutual_information: float
        The information gain calculated according to the equation IG(X;Y;Z) = I(X,Y;Z) - I(X;Z) - I(Y;Z)

    """
    X_Y = ['{}{}'.format(x, y) for x, y in zip(X, Y)]
    return (mutual_information(X_Y, Z, base=base) -
            mutual_information(X, Z, base=base) -
            mutual_information(Y, Z, base=base))
def two_way_information_gain(X, Y, Z, base=2):
    """Calculates the two-way information gain between three variables, I(X;Y;Z), in the given base

    IG(X;Y;Z) indicates the information gained about variable Z by the joint variable X_Y, after removing
    the information that X and Y have about Z individually. Thus, two-way information gain measures the
    synergistic predictive value of variables X and Y about variable Z.

    Parameters
    ----------
    X: array-like (# samples)
        An array of values for which to compute the 2-way information gain
    Y: array-like (# samples)
        An array of values for which to compute the 2-way information gain
    Z: array-like (# samples)
        An array of outcome values for which to compute the 2-way information gain
    base: integer (default: 2)
        The base in which to calculate 2-way information

    Returns
    ----------
    mutual_information: float
        The information gain calculated according to the equation IG(X;Y;Z) = I(X,Y;Z) - I(X;Z) - I(Y;Z)

    """
    X_Y = ['{}{}'.format(x, y) for x, y in zip(X, Y)]
    return (mutual_information(X_Y, Z, base=base) -
            mutual_information(X, Z, base=base) -
            mutual_information(Y, Z, base=base))
Calculates the two-way information gain between three variables, I(X;Y;Z), in the given base

    IG(X;Y;Z) indicates the information gained about variable Z by the joint variable X_Y, after removing
    the information that X and Y have about Z individually. Thus, two-way information gain measures the
    synergistic predictive value of variables X and Y about variable Z.

    Parameters
    ----------
    X: array-like (# samples)
        An array of values for which to compute the 2-way information gain
    Y: array-like (# samples)
        An array of values for which to compute the 2-way information gain
    Z: array-like (# samples)
        An array of outcome values for which to compute the 2-way information gain
    base: integer (default: 2)
        The base in which to calculate 2-way information

    Returns
    ----------
    mutual_information: float
        The information gain calculated according to the equation IG(X;Y;Z) = I(X,Y;Z) - I(X;Z) - I(Y;Z)