acldpy

Summary

This Python 3 package assigns letters to indicate statistically significant differences between treatments following pairwise comparisons. It strives to be compatible with all major Python statistics libraries.

acldpy = agnostic compact letter display for Python

Users conduct their statistical test with the library of their choice. Then, they pass their result to acldpy. The package implements algorithms that were described by Piepho and coworkers [1,2].

Installation

Install from PyPI test server:

pip install acldpy

Basic usage

To calculate the cld, you need three arguments.

1. List of all first treatment names used in the pairwise comparisons.
2. List of all second treatment names used in the pairwise comparisons.
3. List of the p-values associated with each comparison.

Generally, one's input should follow this structure: i-th entry of p_values corresponds to the p-value for the comparison between the i-th entry in first_treatments and the i-th entry in second_treatments:

first_treatments = ["element 1", "element 1", "element 2"]
second_treatments = ["element 2", "element 3", "element 3"]
p_values = [0.9, 0.2, 0.01]

These three lists are passed to the run_cld function of the acldpy library. run_cld returns a dictionary where each key is a unique treatment and the value is its associated letters.

from acldpy import run_cld

cld = run_cld(first_treatments, second_treatments, p_values)
print (cld) # {'element 1': 'ab', 'element 2': 'b', 'element 3': 'a'}

Typically, these three required lists can be parsed from the returned object of a statistical test, as illustrated here with the Pingouin implementation of the Tukey-Kramer test.

import pingouin as pg
from acldpy import run_cld

penguins = pg.read_dataset("penguins") # Example dataset
tk_result = penguins.pairwise_tukey(dv='body_mass_g', between='species')
first_treatments, second_treatments, p_values = list(tk_result["A"]), list(tk_result["B"]), list(tk_result["p-tukey"])

cld = run_cld(first_treatments, second_treatments, p_values)
print (cld) # {'Adelie': 'b', 'Chinstrap': 'b', 'Gentoo': 'a'}

Besides these three lists, run_cld accepts two optional arguments:

1. alpha (float, default: 0.05): Significance level. Two treatments are considered significantly different if their p‑value is less ("<", not "=<"!) than alpha.
2. letter_order (None | list, default: None): If set, a list containing all treatments in the order of which they should be assigned letters to. Often, one would like to assign the letters in ascending order of the treatment mean values.

from acldpy import run_cld

first_treatments = ["element 1", "element 1", "element 1", "element 2", "element 2", "element 3"]
second_treatments = ["element 2", "element 3", "element 4", "element 3", "element 4", "element 4"]
p_values = [0.08, 0.02, 0.01, 0.2, 0.04, 0.08]
mean_values = {"element 1": 1.2, "element 2": 2.8, "element 3": 3.2, "element 4": 4.0}

cld = run_cld(first_treatments, second_treatments, p_values) # default values for alpha and letter_order
print(cld) # {'element 1': 'c', 'element 2': 'bc', 'element 3': 'ab', 'element 4': 'a'}

mean_values_sorted = dict(sorted(mean_values.items(), key=lambda item: item[1]))
cld = run_cld(first_treatments, second_treatments, p_values, alpha=0.1, letter_order=mean_values_sorted.keys())
print(cld) # {'element 1': 'a', 'element 2': 'b', 'element 3': 'b', 'element 4': 'c'}

Extra Functionality

find_cld_columns is a helper function that accepts the result objects of the most common statistical tests and returns the three required lists.

from acldpy import find_cld_columns

first_treatments, second_treatments, p_values = find_cld_columns(penguins_tk_result, "pg_tk")

Currently it works with the output of the following tests:

1. result_type="pg_tk": pingouin's Tukey-Kramer test
2. result_type="stm_tk": statsmodels' Tukey-Kramer test

Development and Distribution

This package is provided under the MIT license. I (NJung) am its sole developer. I encourage you to report issues, when you find them under https://github.com/anyusernameisokay/acldpy/issues. If you do so, please provide your input data, and the error you receive.

Currently, the package is still under development, and I expect that some inputs lead to unhandled exceptions. However, the package will never silently return a wrong cld!

Furthermore, the following improvements are planned:

• Different and custom alternatives to the classical small letters.
• Optimal utilization of NumPy under the hood.

References

[1] J. Gramm, J. Guo, F. Hüffner, R. Niedermeier, H.-P. Piepho, and R. Schmid, “Algorithms for compact letter displays: Comparison and evaluation,” Computational Statistics & Data Analysis, vol. 52, no. 2, pp. 725–736, Oct. 2006, doi: 10.1016/j.csda.2006.09.035.

[2] H.-P. Piepho, “An algorithm for a Letter-Based representation of All-Pairwise comparisons,” Journal of Computational and Graphical Statistics, vol. 13, no. 2, pp. 456–466, Jun. 2004, doi: 10.1198/1061860043515.

I am not affiliated with the authors of these studies.

Links

• PyPI: https://pypi.org/p/acldpy/
• Source: https://github.com/anyusernameisokay/acldpy