Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
Categorical data analysis is the set of methods for data whose values are categories (treatment arm, outcome present or absent, survey response option) rather than measured quantities: you summarise counts in a contingency table, test whether categories are associated, and estimate effect sizes such as the odds ratio. In R the base stats package covers the core tests with chisq.test and fisher.test, and the Python library statsmodels covers the same ground and more in its contingency-table module.
What categorical data analysis is used for in research
Researchers reach for these methods whenever the outcome or the exposure is a label. Typical questions are whether the distribution of one variable matches expected proportions, whether two categorical variables are associated, whether a before-and-after change in a yes/no outcome is more than chance, and whether an association holds across strata such as study sites. If you are still deciding which of your variables count as categorical, start with categorical variable examples and the quantitative vs categorical variables comparison. If the variable is a survey item, nominal survey questions explains how such items are built.
The same task is also called the analysis of categorical data. The tools below work on a table of counts: rows are the categories of one variable, columns the categories of another. Which function to call depends on the shape of that table and on how the observations were collected, which is why the decision table in the next section matters more than any single test.
Which test fits which data situation
The data table below maps six common situations to the R function and the statsmodels call documented for it. Every row comes from the official R manual pages and the statsmodels documentation listed under Sources.
How to install or access it
R is distributed by the R Project, and the functions used here (chisq.test and fisher.test) belong to the stats package, whose manual pages are published at stat.ethz.ch/R-manual. statsmodels is a Python package with its documentation at statsmodels.org; its contingency-table tools live in statsmodels.stats.contingency_tables. Both are downloaded from their own projects.
Use the documentation version that matches your installed version. The R pages cited here are from the R-devel manual and the statsmodels pages from the stable documentation, so check the function signature in your own installation (?chisq.test in R, help() in Python) before relying on a default.
Step by step: test an association in a contingency table
This worked example uses invented counts for illustration only; they are not real study data. Suppose 100 participants are classified by exposure (exposed, unexposed) and outcome (event, no event) in a 2 x 2 table.
Step 1: put the counts in a table
In R, build a matrix of counts. chisq.test(x) accepts a matrix of counts directly, and fisher.test(x) does too:
tab = matrix(c(30, 20, 10, 40), nrow = 2, byrow = TRUE,
dimnames = list(exposure = c("exposed", "unexposed"),
outcome = c("event", "no event")))
chisq.test(tab)
fisher.test(tab)
In Python, pass the same array to the statsmodels Table class, which the documentation describes as a general two-way table of counts:
import numpy as np
import statsmodels.api as sm
tab = np.array([[30, 20], [10, 40]])
t = sm.stats.Table(tab)
print(t.test_nominal_association())
Step 2: choose the right call for the table
For a single categorical variable compared with expected proportions, pass the vector of counts to chisq.test and supply the expected proportions in p. For two unordered variables, pass the matrix. For a 2 x 2 table with small counts, use fisher.test. When the same people are measured twice, the table is paired and an ordinary chi-squared test is the wrong tool: statsmodels provides mcnemar for paired categorical outcomes and cochrans_q for several related binomial proportions. When you have several 2 x 2 tables from different strata, statsmodels offers StratifiedTable for pooled estimates. When the categories are ordered, use test_ordinal_association(), which takes optional row and column scores.
Step 3: read the output
The next section explains what each part of the output means. In both languages the key habit is to look at the expected counts and residuals, not only at the p-value.
Output and how to read it
Expected counts
The R manual states that the chisq.test result holds expected, the expected counts under the null hypothesis. In statsmodels the same quantity is the fittedvalues attribute of a Table, described as the fitted (expected) counts under independence. Compare these with your observed table: cells where the observed count is far from expected are where the association lives.
Pearson and standardized residuals
The R result includes residuals, the Pearson residuals, defined as (O – E) / sqrt(E), and stdres, the standardized residuals. statsmodels exposes resid_pearson and standardized_resids, plus chi2_contribs (each cell’s contribution to the chi-squared statistic) and local_oddsratios. Reporting which cells drive a significant result is usually more informative than the overall statistic alone.
The continuity correction in 2 x 2 tables
The R argument correct = TRUE applies a continuity correction to 2 x 2 tables. According to the manual it subtracts 0.5 from all |O – E| differences, but never by more than the difference itself, and it is not applied when simulate.p.value = TRUE. State in your methods section whether the correction was on.
Odds ratios from Fisher’s exact test
fisher.test returns an object of class htest with p.value, conf.int (a confidence interval for the odds ratio, 2 x 2 only), estimate and null.value. The R manual notes that estimate is the conditional maximum likelihood estimate of the odds ratio, not the sample odds ratio, so it can differ from the cross-product you compute by hand. For a 2 x 2 table, independence is equivalent to an odds ratio of 1. The arguments alternative and conf.int apply only to 2 x 2 tables. For a single 2 x 2 table, statsmodels offers Table2x2, which provides odds ratios and risk ratios.
Troubleshooting
Sparse cells and small expected counts
The R documentation for chisq.test does not state a minimum expected-count rule. Its own example describes an expected count of 1.86 as “maybe doubtful, but is ok” and then shows simulate.p.value = TRUE as an alternative. That option computes a Monte Carlo p-value; with the default B = 2000 replicates the smallest attainable p-value is about 0.0005. For tables larger than 2 x 2, fisher.test also accepts simulate.p.value, and it requires strictly positive marginals. Check your own field’s reporting convention for when to switch tests, because the software documentation does not decide that for you.
Paired or repeated observations
If rows and columns are the same categories measured on the same units (for example, a diagnosis recorded by two raters, or an outcome before and after), the table is square and the independence test answers the wrong question. statsmodels provides SquareTable for symmetry and homogeneity, and mcnemar (with exact and correction arguments) for paired binary outcomes.
Zeros in the table
The Table and StratifiedTable classes in statsmodels accept a shift_zeros argument, which is how the library handles zero cells when it computes odds ratios and related quantities. Look at the parameter description in the documentation for your version before using it, and report any adjustment.
When one table is not enough
Contingency-table tests handle one or two categorical variables at a time. For a categorical outcome with several predictors, see logistic regression in statsmodels. To cross-tabulate raw records into a count table first, see pandas crosstab, and for the underlying test see the dictionary entry for the chi-square test.
Free alternatives
R and Python with statsmodels are both free to download. They overlap on the basic tests and differ in what the documentation highlights.
| Tool | Core contingency-table functions | Residuals and expected counts |
|---|---|---|
| R (base stats) | chisq.test, fisher.test | expected, residuals, stdres in the chisq.test result |
| Python statsmodels | Table, Table2x2, SquareTable, StratifiedTable, mcnemar, cochrans_q | fittedvalues, resid_pearson, standardized_resids, chi2_contribs |
Frequently asked questions
What is categorical data analysis?
It is the family of statistical methods for variables whose values are categories. The basic workflow is to tabulate counts, test association or agreement with a method suited to how the data were collected, and report an effect size and the cells that drive the result.
Which function tests two categorical variables in R?
Pass a matrix of counts, or two factor vectors, to chisq.test. For a 2 x 2 table with small counts, fisher.test is documented in the same package.
How do I analyse paired categorical data?
Use a method built for pairing. In statsmodels, mcnemar tests whether paired binary outcomes have the same marginal proportions, and cochrans_q extends that idea to several related binomial proportions.
What do I do with ordered categories?
statsmodels offers test_ordinal_association() on a Table, with optional row and column scores, as an alternative to the nominal association test.
Sources
- R Core Team, stats::chisq.test, R-devel manual: https://stat.ethz.ch/R-manual/R-devel/library/stats/html/chisq.test.html (checked 2026-11-14)
- R Core Team, stats::fisher.test, R-devel manual: https://stat.ethz.ch/R-manual/R-devel/library/stats/html/fisher.test.html (checked 2026-11-14)
- statsmodels, Contingency tables (stable documentation): https://www.statsmodels.org/stable/contingency_tables.html (checked 2026-11-14)
- statsmodels, Table class: https://www.statsmodels.org/stable/generated/statsmodels.stats.contingency_tables.Table.html (checked 2026-11-14)
Data: Categorical data situations mapped to R and statsmodels functions
Original decision table compiled from the R-devel manual pages for chisq.test and fisher.test and the statsmodels contingency-tables documentation: for six common data situations it lists the documented R function and the documented statsmodels call.
| Data situation | R function (base stats) | statsmodels call | Documented note |
|---|---|---|---|
| One variable against expected proportions | chisq.test(x, p = ...) | — | R: p gives the expected probabilities; rescale.p rescales them |
| Two unordered variables, count table | chisq.test(x) | Table(table).test_nominal_association() | R returns expected, residuals, stdres; statsmodels has fittedvalues, resid_pearson, standardized_resids |
| 2 x 2 table, small counts | fisher.test(x) | Table2x2 (odds ratios, risk ratios) | R estimate is the conditional MLE of the odds ratio, not the sample odds ratio |
| Table larger than 2 x 2, sparse | chisq.test or fisher.test with simulate.p.value = TRUE | — | R: B = 2000 by default; fisher.test needs strictly positive marginals |
| Paired binary outcomes | — | mcnemar(table, exact, correction) | Tests equal marginal proportions in paired data |
| Several 2 x 2 tables (strata) | — | StratifiedTable(tables, shift_zeros) | Pooled estimates across the 2 x 2 tables |
| Ordered categories | — | Table(table).test_ordinal_association() | Optional row and column scores |
Sources
- R stats::chisq.test (accessed 2026-11-14)
- R stats::fisher.test (accessed 2026-11-14)
- statsmodels contingency tables (accessed 2026-11-14)
- statsmodels Table class (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







