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

pandas crosstab: pd.crosstab() Syntax, normalize and Examples

How pd.crosstab() builds contingency tables in pandas: arguments, normalize options, margins, missing categories and a hand-off to a chi-square test.

Written and maintained by CASRAI Editorial Board

Published

On this page

pandas.crosstab() builds a cross tabulation: a table that counts how often each combination of two (or more) categorical variables occurs. Pass one variable as index (rows) and one as columns, and pandas returns a DataFrame of frequencies; pass values together with aggfunc and it aggregates a third variable instead of counting. This guide covers the signature, the normalize and margins options, missing categories, the index-alignment trap and the hand-off to a chi-square test, with every output below produced by running the code under pandas 3.1.1.

What pd.crosstab is used for in research

The pandas reference describes pandas.crosstab as computing “a simple cross tabulation of two (or more) factors”, which by default is a frequency table unless an array of values and an aggregation function are passed. In research data work that is the contingency table behind a comparison of two categorical variables: treatment arm by outcome category, site by consent status, survey item by respondent group. It is the pandas equivalent of the crosstab procedures covered in crosstabs in R and crosstabs in Excel, and it is the usual first step before reading a contingency table or running a chi-square test.

The pandas user guide on reshaping lists crosstab() among its reshaping tools as the function that calculates “a cross-tabulation of multiple 1 dimensional factor arrays”. The reference page names DataFrame.pivot and pivot_table under See also; the difference in practice is that crosstab takes the variables themselves (columns or arrays), whereas pivot_table takes a DataFrame and column names. If you need that route, see pandas pivot and pivot_table.

Install or access

pandas is a free, open-source Python library. The pandas team states on its install page that it officially distributes pandas through conda-forge, PyPI and GitHub (source). The two standard commands from that page are:

pip install pandas
conda install -c conda-forge pandas

Then import it and call the function as pd.crosstab(...). The reference documents crosstab as a top-level pandas function, not a DataFrame method, so you call pd.crosstab(df['a'], df['b']) rather than df.crosstab(...). Searching for “crosstab pandas” and “pandas crosstab” leads to this same function.

Syntax and arguments

The signature in the current reference is:

pandas.crosstab(index, columns, values=None, rownames=None, colnames=None,
                aggfunc=None, margins=False, margins_name='All',
                dropna=True, normalize=False)
Argument What it does
index The values to group by in the rows: an array-like, a Series or a list of them.
columns The values to group by in the columns. Pass a list to get multi-level columns.
values Optional array of values to aggregate. It requires aggfunc, and aggfunc requires values.
rownames, colnames Labels for the row and column axes. If omitted, pandas uses the names of the Series you passed.
aggfunc Aggregation function (for example ‘sum’ or ‘mean’) applied to values within each cell. Without it you get counts.
margins If True, adds row and column totals (subtotals).
margins_name Label for the totals row and column. The default is ‘All’.
dropna Default True: drops columns whose entries are all NaN and categories that were never observed. False keeps every category of a Categorical input.
normalize False (default), True, ‘all’, ‘index’, ‘columns’, 0 or 1: converts counts to proportions. If margins is True, the margins are normalized too.

The function returns a DataFrame. Arguments given as Series are aligned on their index before counting; this has consequences covered under troubleshooting below.

Step-by-step: a worked example on research data

The example uses a small synthetic data set, an illustrative composite invented for this page and not data from any study: 16 participants at two sites (A and B), each with an outcome category and a numeric score. Site A has 6 participants and site B has 10.

import pandas as pd

df = pd.DataFrame({
    'site': ['A']*6 + ['B']*10,
    'outcome': ['improved','improved','improved','no change','no change','worsened',
                'improved','improved','no change','no change','no change','no change',
                'worsened','worsened','worsened','improved'],
    'score': [12,15,14,9,10,6,13,11,8,9,7,10,5,4,6,12],
})
  1. Count combinations. pd.crosstab(df['site'], df['outcome']) returns the frequency table. The first argument becomes the rows and the second the columns.
  2. Add totals. pd.crosstab(df['site'], df['outcome'], margins=True, margins_name='Total') appends a Total row and column.
  3. Convert to proportions. Add normalize='index', 'columns' or 'all', depending on the question (see the next section).
  4. Aggregate a third variable. pd.crosstab(df['site'], df['outcome'], values=df['score'], aggfunc='mean') gives the mean score in each cell instead of a count.
  5. Label the axes. rownames=['Site'], colnames=['Outcome'] replaces the Series names in the output.

Output and how to read it

Step 1 produces this table (count of participants):

outcome  improved  no change  worsened
site
A               3          2         1
B               3          4         3

With margins=True the totals are 6 for site A, 10 for site B, and 6, 6 and 4 down the outcome columns, with a grand total of 16 in the corner. The margins let you check that the table accounts for every row of the data frame before you interpret anything else.

normalize: index, columns or all

The normalize argument changes the denominator, so the same counts answer three different questions. The data table below the guide lists the denominators and the resulting value for the improved column. In words:

  • normalize='index' divides each cell by its row total. Read across: within site A, 50% improved, 33.3% had no change and 16.7% worsened; within site B the shares are 30%, 40% and 30%. Use this when rows are the groups you are comparing (arms, sites, cohorts).
  • normalize='columns' divides each cell by its column total. Read down: of everyone who improved, 50% were at site A and 50% at site B; of those who worsened, 25% were at A and 75% at B. This answers a different question (where do the improvers come from?), and it is easy to misreport as the first one.
  • normalize='all' (or True) divides by the grand total of 16. Site A improved is 3/16 = 0.1875, shown as 0.188 after rounding to three places.

With normalize='index', margins=True the extra All row gives the overall outcome distribution (37.5% improved, 37.5% no change, 25% worsened), which is the benchmark each site’s row is read against.

Aggregating a third variable

With values=df['score'] and aggfunc='mean' the mean score is 13.67, 9.5 and 6.0 for site A across improved, no change and worsened, and 12.0, 8.5 and 5.0 for site B. With aggfunc='sum' the same cells hold the totals 41, 19 and 6 for site A and 36, 34 and 15 for site B. The pandas reference’s own example uses aggfunc='sum' in the same way. A cell with no observations contains NaN rather than zero for these aggregations, so check the cell counts (step 1) before interpreting a mean built on one or two rows; in this example the site A worsened mean rests on a single participant.

Two or more column variables

Passing a list to columns, as in the reference example pd.crosstab(a, [b, c], rownames=['a'], colnames=['b', 'c']), produces two-level column headers. This is how you tabulate a third categorical variable without stacking separate tables, at the cost of a wider table that is harder to read and has many sparse cells.

From the table to a test

A crosstab is descriptive. To test whether the row and column variables are associated, pass the counts table (not the raw data) to SciPy’s scipy.stats.chi2_contingency, whose first parameter observed is the contingency table of observed frequencies:

from scipy.stats import chi2_contingency
ct = pd.crosstab(df['site'], df['outcome'])
res = chi2_contingency(ct)
print(res.statistic, res.pvalue, res.dof)
print(res.expected_freq)

On the example table this returns a statistic of about 0.711, p of about 0.70 and 2 degrees of freedom. The more useful output here is expected_freq: its values are 2.25, 2.25 and 1.5 for site A and 3.75, 3.75 and 2.5 for site B. The SciPy documentation notes a common rule of thumb that the test is valid only when observed and expected counts in each cell are at least 5, and that for small tables a permutation or Monte Carlo method with correction=False is suggested. Every expected count in this 16-row example is below 5, so the p-value is shown only to illustrate the mechanics; a real analysis of a table this small would use an exact or resampling approach. SciPy also notes that for 2×2 tables Yates’ continuity correction is applied by default (correction=True when degrees of freedom equal 1). For the association strength that goes with the test, see the contingency-table and chi-square pages linked in the first section.

Troubleshooting

Missing categories disappear from the table

With the default dropna=True, categories with no observed instances are dropped. If an outcome category exists in your codebook but nobody had it, it simply will not appear. Passing dropna=False on a Categorical input keeps all declared categories. In the example, declaring a fourth category ‘dropped out’ with pd.Categorical(df['outcome'], categories=['improved','no change','worsened','dropped out']) and calling pd.crosstab(df['site'], that_categorical, dropna=False) returns a fourth column of zeros; with the default it returns three columns. For reporting tables that must show every response option, declare the categories and set dropna=False.

An empty DataFrame comes back

The reference states that Series arguments are aligned on their index, rows with a missing value after alignment are dropped, and if the Series have no overlapping index the result is an empty DataFrame. This happens when one variable comes from a different DataFrame or a filtered or re-indexed copy. Run on the example with the outcome Series re-indexed to 100 to 115, the call returned Empty DataFrame, Columns: [], Index: []. Fix it by taking both variables from the same DataFrame, or by calling reset_index(drop=True) on both before the call.

values without aggfunc (or the reverse)

The reference says values requires aggfunc and vice versa. Supply both or neither.

Wrong denominator in percentages

Percentages from normalize depend entirely on the axis. If your row variable is the exposure or group, 'index' gives the within-group distribution; 'columns' gives the composition of each outcome. State the denominator in the table caption or note.

Free alternatives

Option What it gives you Where documented
pandas.pivot_table Aggregated tables from a DataFrame and column names; named under See also on the crosstab reference pandas reference (See also)
scipy.stats.contingency.crosstab Counts for each unique combination of NumPy arrays, with a sparse option; returns the unique elements and the count array (SciPy 1.18.0) SciPy reference
R table() and janitor tabyl() The R equivalent for researchers working outside Python janitor in R

Sources

Data: pandas.crosstab normalize settings: denominator and worked-example values

Compares the four normalize settings of pandas.crosstab (False, 'index', 'columns', 'all'): what each cell is divided by, per the pandas reference, and the resulting value for the 'improved' column in a 16-row synthetic example (site A n=6, site B n=10) computed by running the code under pandas 3.1.1.

pandas.crosstab normalize settings: denominator and worked-example values
normalize settingEach cell is divided bySite A, improvedSite B, improved
False (default)Nothing (raw counts)33
'index'Its row total0.50.3
'columns'Its column total0.50.5
'all' or TrueThe grand total (16)0.18750.1875

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 pandas crosstab: pd.crosstab() Syntax, normalize and Examples

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 →