Skip to main content
v2026.11,986 entries · CC-BY 4.0

Categorical Data Analysis: Tests, Software and How to Read Output

Choose and run categorical data tests in R and Python statsmodels, with a decision table and a guide to reading expected counts and residuals.

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.

Categorical data situations mapped to R and statsmodels functions
Data situationR function (base stats)statsmodels callDocumented note
One variable against expected proportionschisq.test(x, p = ...)—R: p gives the expected probabilities; rescale.p rescales them
Two unordered variables, count tablechisq.test(x)Table(table).test_nominal_association()R returns expected, residuals, stdres; statsmodels has fittedvalues, resid_pearson, standardized_resids
2 x 2 table, small countsfisher.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, sparsechisq.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

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about Categorical Data Analysis: Tests, Software and How to Read Output

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →