Quickstart

Installation

Use PyPi to install the package.

pip install pypair

Confusion Matrix

A confusion matrix is typically used to judge binary classification performance. There are two variables, \(A\) and \(P\), where \(A\) is the actual value (ground truth) and \(P\) is the predicted value. The example below shows how to use the convenience method confusion() and the class ConfusionMatrix to get association measures derived from the confusion matrix.

from pypair.association import confusion
from pypair.contingency import ConfusionMatrix


def get_data():
    """
    Data taken from `here <https://www.dataschool.io/simple-guide-to-confusion-matrix-terminology/>`_.
    A pair of binary variables, `a` and `p`, are returned.

    :return: a, p
    """
    tn = [(0, 0) for _ in range(50)]
    fp = [(0, 1) for _ in range(10)]
    fn = [(1, 0) for _ in range(5)]
    tp = [(1, 1) for _ in range(100)]
    data = tn + fp + fn + tp
    a = [a for a, _ in data]
    p = [b for _, b in data]
    return a, p


a, p = get_data()

# if you need to quickly get just one association measure
r = confusion(a, p, measure='acc')
print(r)

print('-' * 15)

# you can also get a list of available association measures
# and loop over to call confusion(...)
# this is more convenient, but less fast
for m in ConfusionMatrix.measures():
    r = confusion(a, p, m)
    print(f'{r}: {m}')

print('-' * 15)

# if you need multiple association measures, then
# build the confusion matrix table
# this is less convenient, but much faster
matrix = ConfusionMatrix(a, p)
for m in matrix.measures():
    r = matrix.get(m)
    print(f'{r}: {m}')

Binary-Binary

Association measures for binary-binary variables are computed using binary_binary() or BinaryTable.

from pypair.association import binary_binary
from pypair.contingency import BinaryTable

get_data = lambda x, y, n: [(x, y) for _ in range(n)]
data = get_data(1, 1, 207) + get_data(1, 0, 282) + get_data(0, 1, 231) + get_data(0, 0, 242)
a = [a for a, _ in data]
b = [b for _, b in data]

for m in BinaryTable.measures():
    r = binary_binary(a, b, m)
    print(f'{r}: {m}')

print('-' * 15)

table = BinaryTable(a, b)
for m in table.measures():
    r = table.get(m)
    print(f'{r}: {m}')

Categorical-Categorical

Association measures for categorical-categorical variables are computed using categorical_categorical() or CategoricalTable.

from pypair.association import categorical_categorical
from pypair.contingency import CategoricalTable

get_data = lambda x, y, n: [(x, y) for _ in range(n)]
data = get_data(1, 1, 207) + get_data(1, 0, 282) + get_data(0, 1, 231) + get_data(0, 0, 242)
a = [a for a, _ in data]
b = [b for _, b in data]

for m in CategoricalTable.measures():
    r = categorical_categorical(a, b, m)
    print(f'{r}: {m}')

print('-' * 15)

table = CategoricalTable(a, b)
for m in table.measures():
    r = table.get(m)
    print(f'{r}: {m}')

Binary-Continuous

Association measures for binary-continuous variables are computed using binary_continuous() or Biserial.

from pypair.association import binary_continuous
from pypair.biserial import Biserial

get_data = lambda x, y, n: [(x, y) for _ in range(n)]
data = get_data(1, 1, 207) + get_data(1, 0, 282) + get_data(0, 1, 231) + get_data(0, 0, 242)
a = [a for a, _ in data]
b = [b for _, b in data]

for m in Biserial.measures():
    r = binary_continuous(a, b, m)
    print(f'{r}: {m}')

print('-' * 15)

biserial = Biserial(a, b)
for m in biserial.measures():
    r = biserial.get(m)
    print(f'{r}: {m}')

Ordinal-Ordinal, Concordance

Concordance measures are used for ordinal-ordinal or continuous-continuous variables using concordance() or Concordance().

from pypair.association import concordance
from pypair.continuous import Concordance

a = [1, 2, 3]
b = [3, 2, 1]

for m in Concordance.measures():
    r = concordance(a, b, m)
    print(f'{r}: {m}')

print('-' * 15)

con = Concordance(a, b)
for m in con.measures():
    r = con.get(m)
    print(f'{r}: {m}')

Categorical-Continuous

Categorical-continuous association measures are computed using categorical_continuous() or CorrelationRatio.

from pypair.association import categorical_continuous
from pypair.continuous import CorrelationRatio

data = [
    ('a', 45), ('a', 70), ('a', 29), ('a', 15), ('a', 21),
    ('g', 40), ('g', 20), ('g', 30), ('g', 42),
    ('s', 65), ('s', 95), ('s', 80), ('s', 70), ('s', 85), ('s', 73)
]
x = [x for x, _ in data]
y = [y for _, y in data]
for m in CorrelationRatio.measures():
    r = categorical_continuous(x, y, m)
    print(f'{r}: {m}')

print('-' * 15)

cr = CorrelationRatio(x, y)
for m in cr.measures():
    r = cr.get(m)
    print(f'{r}: {m}')

Continuous-Continuous

Association measures for continuous-continuous variables are computed using continuous_continuous() or Continuous.

from pypair.association import continuous_continuous
from pypair.continuous import Continuous

x = [x for x in range(10)]
y = [y for y in range(10)]

for m in Continuous.measures():
    r = continuous_continuous(x, y, m)
    print(f'{r}: {m}')

print('-' * 15)

con = Continuous(x, y)
for m in con.measures():
    r = con.get(m)
    print(f'{r}: {m}')

Recipe

Here’s a recipe in using multiprocessing to compute pairwise association with binary data.

import pandas as pd
import numpy as np
import random
from random import randint
from pypair.association import binary_binary
from itertools import combinations
from multiprocessing import Pool

np.random.seed(37)
random.seed(37)

def get_data(n_rows=1000, n_cols=5):
    data = [tuple([randint(0, 1) for _ in range(n_cols)]) for _ in range(n_rows)]
    cols = [f'x{i}' for i in range(n_cols)]
    return pd.DataFrame(data, columns=cols)

def compute(a, b, df):
    x = df[a]
    y = df[b]
    return f'{a}_{b}', binary_binary(x, y, measure='jaccard')

if __name__ == '__main__':
    df = get_data()

    with Pool(10) as pool:
        pairs = ((a, b, df) for a, b in combinations(df.columns, 2))
        bc = pool.starmap(compute, pairs)
    
    bc = sorted(bc, key=lambda tup: tup[0])
    print(dict(bc))

Here’s a nifty utility method to create a correlation matrix. The input data frame must be all the same type and you must supply a function. Note that Pandas DataFrame.corr() no longer supports processing non-numeric data; fields that are not numeric will be simply skipped over. Why?

from random import randint

import pandas as pd

from pypair.association import binary_binary
from pypair.util import corr


def get_data(n_rows=1000, n_cols=5):
    data = [tuple([randint(0, 1) for _ in range(n_cols)]) for _ in range(n_rows)]
    cols = [f'x{i}' for i in range(n_cols)]
    return pd.DataFrame(data, columns=cols)


if __name__ == '__main__':
    jaccard = lambda a, b: binary_binary(a, b, measure='jaccard')
    tanimoto = lambda a, b: binary_binary(a, b, measure='tanimoto_i')

    df = get_data()
    jaccard_corr = corr(df, jaccard)
    tanimoto_corr = corr(df, tanimoto)

    print(jaccard_corr)
    print('-' * 15)
    print(tanimoto_corr)

Apache Spark

Spark is supported for some of the association measures. Active support is appreciated. Below are some code samples to get you started.

import json
from random import choice

import pandas as pd
from pyspark.sql import SparkSession

from pypair.spark import binary_binary, confusion, categorical_categorical, agreement, binary_continuous, concordance, \
    categorical_continuous, continuous_continuous


def _get_binary_binary_data(spark):
    """
    Gets dummy binary-binary data in a Spark dataframe.

    :return: Spark dataframe.
    """
    get_data = lambda x, y, n: [(x, y) * 2 for _ in range(n)]
    data = get_data(1, 1, 207) + get_data(1, 0, 282) + get_data(0, 1, 231) + get_data(0, 0, 242)
    pdf = pd.DataFrame(data, columns=['x1', 'x2', 'x3', 'x4'])
    sdf = spark.createDataFrame(pdf)
    return sdf


def _get_confusion_data(spark):
    """
    Gets dummy binary-binary data in Spark dataframe. For use with confusion matrix analysis.

    :return: Spark dataframe.
    """
    tn = [(0, 0) * 2 for _ in range(50)]
    fp = [(0, 1) * 2 for _ in range(10)]
    fn = [(1, 0) * 2 for _ in range(5)]
    tp = [(1, 1) * 2 for _ in range(100)]
    data = tn + fp + fn + tp
    pdf = pd.DataFrame(data, columns=['x1', 'x2', 'x3', 'x4'])
    sdf = spark.createDataFrame(pdf)
    return sdf


def _get_categorical_categorical_data(spark):
    """
    Gets dummy categorical-categorical data in Spark dataframe.

    :return: Spark dataframe.
    """
    x_domain = ['a', 'b', 'c']
    y_domain = ['a', 'b']

    get_x = lambda: choice(x_domain)
    get_y = lambda: choice(y_domain)
    get_data = lambda: {f'x{i}': v for i, v in enumerate((get_x(), get_y(), get_x(), get_y()))}

    pdf = pd.DataFrame([get_data() for _ in range(100)])
    sdf = spark.createDataFrame(pdf)
    return sdf


def _get_binary_continuous_data(spark):
    """
    Gets dummy `binary-continuous data <https://www.slideshare.net/MuhammadKhalil66/point-biserial-correlation-example>`_.

    :return: Spark dataframe.
    """
    data = [
        (1, 10), (1, 11), (1, 6), (1, 11), (0, 4),
        (0, 3), (1, 12), (0, 2), (0, 2), (0, 1)
    ]
    pdf = pd.DataFrame(data, columns=['gender', 'years'])
    sdf = spark.createDataFrame(pdf)
    return sdf


def _get_concordance_data(spark):
    """
    Gets dummy concordance data.

    :return: Spark dataframe.
    """
    a = [1, 2, 3]
    b = [3, 2, 1]
    pdf = pd.DataFrame({'a': a, 'b': b, 'c': a, 'd': b})
    sdf = spark.createDataFrame(pdf)
    return sdf


def _get_categorical_continuous_data(spark):
    data = [
        ('a', 45), ('a', 70), ('a', 29), ('a', 15), ('a', 21),
        ('g', 40), ('g', 20), ('g', 30), ('g', 42),
        ('s', 65), ('s', 95), ('s', 80), ('s', 70), ('s', 85), ('s', 73)
    ]
    data = [tup * 2 for tup in data]
    pdf = pd.DataFrame(data, columns=['x1', 'x2', 'x3', 'x4'])
    sdf = spark.createDataFrame(pdf)
    return sdf


def _get_continuous_continuous_data(spark):
    """
    Gets dummy continuous-continuous data.
    See `site <http://onlinestatbook.com/2/describing_bivariate_data/calculation.html>`_.

    :return: Spark dataframe.
    """
    data = [
        (12, 9),
        (10, 12),
        (9, 12),
        (14, 11),
        (10, 8),
        (11, 9),
        (10, 9),
        (10, 6),
        (14, 12),
        (9, 11),
        (11, 12),
        (10, 7),
        (11, 13),
        (15, 14),
        (8, 11),
        (11, 11),
        (9, 8),
        (9, 9),
        (10, 11),
        (12, 9),
        (11, 12),
        (10, 12),
        (9, 7),
        (7, 9),
        (12, 14)
    ]
    pdf = pd.DataFrame([item * 2 for item in data], columns=['x1', 'x2', 'x3', 'x4'])
    sdf = spark.createDataFrame(pdf)
    return sdf


spark = None

try:
    # create a spark session
    spark = (SparkSession.builder
             .master('local[4]')
             .appName('local-testing-pyspark')
             .getOrCreate())

    # create some spark dataframes
    bin_sdf = _get_binary_binary_data(spark)
    con_sdf = _get_confusion_data(spark)
    cat_sdf = _get_categorical_categorical_data(spark)
    bcn_sdf = _get_binary_continuous_data(spark)
    crd_sdf = _get_concordance_data(spark)
    ccn_sdf = _get_categorical_continuous_data(spark)
    cnt_sdf = _get_continuous_continuous_data(spark)

    # call these methods to get the association measures
    bin_results = binary_binary(bin_sdf).collect()
    con_results = confusion(con_sdf).collect()
    cat_results = categorical_categorical(cat_sdf).collect()
    agr_results = agreement(bin_sdf).collect()
    bcn_results = binary_continuous(bcn_sdf, binary=['gender'], continuous=['years']).collect()
    crd_results = concordance(crd_sdf).collect()
    ccn_results = categorical_continuous(ccn_sdf, ['x1', 'x3'], ['x2', 'x4']).collect()
    cnt_results = continuous_continuous(cnt_sdf).collect()

    # convert the lists to dictionaries
    bin_results = {tup[0]: tup[1] for tup in bin_results}
    con_results = {tup[0]: tup[1] for tup in con_results}
    cat_results = {tup[0]: tup[1] for tup in cat_results}
    agr_results = {tup[0]: tup[1] for tup in agr_results}
    bcn_results = {tup[0]: tup[1] for tup in bcn_results}
    crd_results = {tup[0]: tup[1] for tup in crd_results}
    ccn_results = {tup[0]: tup[1] for tup in ccn_results}
    cnt_results = {tup[0]: tup[1] for tup in cnt_results}

    # pretty print
    to_json = lambda r: json.dumps({f'{k[0]}_{k[1]}': v for k, v in r.items()}, indent=1)
    print(to_json(bin_results))
    print('-' * 10)
    print(to_json(con_results))
    print('*' * 10)
    print(to_json(cat_results))
    print('~' * 10)
    print(to_json(agr_results))
    print('-' * 10)
    print(to_json(bcn_results))
    print('=' * 10)
    print(to_json(crd_results))
    print('`' * 10)
    print(to_json(ccn_results))
    print('/' * 10)
    print(to_json(cnt_results))
except Exception as e:
    print(e)
finally:
    try:
        spark.stop()
        print('closed spark')
    except Exception as e:
        print(e)