asymcat — asymmetric categorical association analysis

Most measures of association are symmetric: they report a single number for a pair of variables, as if the relationship between X and Y were the same as between Y and X. Many real relationships are not. Knowing a country often tells you its capital, yet a capital tells you its country far more decisively; one symptom may predict a disease while the disease barely predicts that symptom. ASymCat quantifies association separately in each direction, across a dozen probabilistic, information-theoretic, and statistical measures, behind one consistent interface.

Installation

pip install asymcat

Example

import asymcat

data   = asymcat.read_sequences("data.tsv")
coocs  = asymcat.collect_cooccs(data)
scorer = asymcat.scorer.CatScorer(coocs)

scores = scorer.mle()
scores[("a", "x")]   # (0.83, 0.20)  — P(x|a) vs P(a|x): the association is directional

Every measure returns a mapping from category pairs to a (x→y, y→x) tuple. A symmetric summary would collapse those two numbers into one and hide exactly the structure ASymCat is built to reveal: which variable predicts which, and how strongly, in each direction.

The asymmetry

x→y (predicting y from x) y→x (predicting x from y)

Figure 1. For each category pair, association is scored in both directions. When the two bars differ, the relationship is asymmetric — one category predicts the other better than the reverse. A single symmetric score would report only the average and lose this.

Measures

Measure	Family	Reports
mle	probabilistic	P(y\|x), P(x\|y)
pmi, pmi_smoothed	information-theoretic	pointwise mutual information
theil_u	information-theoretic	uncertainty coefficient
cond_entropy	information-theoretic	conditional entropy
mutual_information	information-theoretic	(normalized) MI
chi2, cramers_v	statistical	χ² association
fisher	statistical	exact odds ratio
log_likelihood_ratio	statistical	G² statistic
goodman_kruskal_lambda	statistical	proportional error reduction
jaccard_index	set-based	directional overlap
tresoldi	specialized	smoothed measure for sequences

Statistical tests expose matching p-value scorers (chi2_pvalue, fisher_pvalue, log_likelihood_ratio_pvalue); a generic permutation_pvalue and bootstrap_ci provide significance and confidence intervals for any measure.

Across domains

Directional association between categories recurs wherever one kind of label helps predict another:

Linguistics. grapheme–phoneme correspondence and sound-change directionality.
Ecology. asymmetric species co-occurrence from presence–absence data.
Machine learning. feature screening by directional predictive strength.
Categorical analytics. dependency and information flow between discrete variables.

Documentation

User Guide → API Reference → The Tresoldi Measure → Changelog → Source (GitHub) → Package (PyPI) →

Citation

@software{tresoldi_asymcat,
  author  = {Tresoldi, Tiago},
  title   = {ASymCat: Asymmetric measures of association between
             categorical variables},
  url     = {https://github.com/tresoldi/asymcat}
}