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],
})
- Count combinations.
pd.crosstab(df['site'], df['outcome'])returns the frequency table. The first argument becomes the rows and the second the columns. - Add totals.
pd.crosstab(df['site'], df['outcome'], margins=True, margins_name='Total')appends a Total row and column. - Convert to proportions. Add
normalize='index','columns'or'all', depending on the question (see the next section). - 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. - 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'(orTrue) 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
- pandas documentation: pandas.crosstab (pandas 3.1.1), https://pandas.pydata.org/docs/reference/api/pandas.crosstab.html, read 2026-11-14.
- pandas user guide: Reshaping and pivot tables, https://pandas.pydata.org/docs/user_guide/reshaping.html, read 2026-11-14.
- pandas documentation: Installation, https://pandas.pydata.org/docs/getting_started/install.html, read 2026-11-14.
- SciPy documentation: scipy.stats.contingency.crosstab (SciPy 1.18.0), https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.contingency.crosstab.html, read 2026-11-14.
- SciPy documentation: scipy.stats.chi2_contingency, https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.chi2_contingency.html, read 2026-11-14.
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.
| normalize setting | Each cell is divided by | Site A, improved | Site B, improved |
|---|---|---|---|
| False (default) | Nothing (raw counts) | 3 | 3 |
| 'index' | Its row total | 0.5 | 0.3 |
| 'columns' | Its column total | 0.5 | 0.5 |
| 'all' or True | The grand total (16) | 0.1875 | 0.1875 |
Sources
- pandas documentation: pandas.crosstab (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







