PG Categorical
Use when both variables are categorical (nominal) and the question is association or change in proportions.
Load
Read:
../../references/supervision-gates.md../../references/pingouin-api-quickref.md../../references/apa-output-template.mdif writing results.
Decision Rules
- Association between two independent categorical variables (any R x C) ->
pg.chi2_independence(data, x, y). - Change in a binary outcome for the same participants (paired 2x2) ->
pg.chi2_mcnemar(data, x, y). - Just the 2x2 table from two binary columns ->
pg.dichotomous_crosstab(data, x, y). - Sample size / power for a chi-square test ->
pg.power_chi2(dof, w, n, power, alpha).
Required Inputs
- Two categorical columns (row and column variables).
- Whether observations are independent (chi-square) or paired within participants (McNemar).
- For McNemar/crosstab: columns must be dichotomous (0/1 or two levels).
- For power: effect size
w(Cohen), degrees of freedom, and the unknown to solve (set toNone).
Code Patterns
Chi-square test of independence (returns a 3-tuple):
expected, observed, stats = pg.chi2_independence(data=df, x="group", y="response")
pg.print_table(stats.round(3)) # read the "pearson" row
McNemar paired test (binary 0/1 columns; returns observed table + stats):
observed, stats = pg.chi2_mcnemar(data=df, x="before", y="after")
pg.print_table(stats.round(3))
2x2 crosstab:
ct = pg.dichotomous_crosstab(data=df, x="cond_a", y="cond_b")
print(ct)
Chi-square power / sample size:
power = pg.power_chi2(dof=1, w=0.3, n=100, alpha=0.05) # solve n via n=None, power=0.8
print({"power": round(float(power), 3)})
Output Checks
chi2_independence stats rows include pearson; columns are test, lambda, chi2, dof, pval, cramer (effect size), power. Report Cramér's V, not just chi-square. chi2_mcnemar stats give chi2, dof, p_approx, p_exact; prefer p_exact for small discordant counts.
Guardrails
- Chi-square needs adequate expected counts; if many cells < 5, note it and consider Fisher's exact (outside Pingouin).
- McNemar requires paired dichotomous data, not two independent groups.
- Report the contingency table and Cramér's V / effect size, not only the p-value.
- Chi-square shows association, not causation or direction.
- End result-bearing answers with one compact S0-S5 audit line.