Introduction
Before comparing outcomes between groups, readers need to know whether those groups were actually comparable to begin with — same age distribution, same sex balance, same baseline severity. This is the role of "Table 1" in clinical and academic research: a standardized summary of baseline characteristics by group, with p-values flagging any imbalance that could confound the results. RenderTableOne builds this table automatically from continuous and categorical columns, in HTML, Markdown, LaTeX, or plain-text formats.
Teaching Note
Summary tables (Table 1) are essential for:
- Epidemiology: Summarizing demographic and clinical characteristics of a study cohort.
- Healthcare: Comparing baseline health metrics between treatment and control patient groups.
- Intelligence Analysis: Summarizing regional stability indicators across multiple geopolitical sectors.
- Data Science: Inspecting the distribution and balance of features before model training.
- Public Health: Monitoring the coverage of health services across different socioeconomic strata.
- Social Science: Summarizing survey respondents' demographic profiles by education level.
- Finance: Comparing asset performance metrics across different portfolio strategies.
- Operations: Summarizing equipment performance metrics across several manufacturing sites.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dataframerequired | pd.DataFrame | — | The pandas DataFrame containing the variables to be summarized. |
value_column_namerequired | str | — | The name of the outcome or primary variable of interest. |
grouping_column_namerequired | str | — | The categorical column name used to group the rows (e.g., 'TreatmentGroup'). |
list_of_row_variablesrequired | list of str | — | The names of the columns to be included as rows in the summary table. |
table_format | {'html', 'grid', 'simple', 'github', 'latex'} | 'html' | The output format for the table rendering. Defaults to 'html'. |
show_p_value | bool | True | Whether to calculate and display p-values for comparisons between groups. Defaults to True. |
return_table_object | bool | False | Whether to return the underlying tableone.TableOne object for further manipulation. Defaults to False. |
Returns
tableone.TableOne or None — returns the TableOne object if return_table_object is True; otherwise, returns None after displaying the table.
Example
python
from analysistoolbox.visualizations import RenderTableOne
import pandas as pd
# Epidemiology: summarizing cohort demographics by infection status
epi_df = pd.DataFrame({
'Infected': ['Yes', 'No'] * 50,
'Age': [45, 30, 60, 22] * 25,
'Gender': ['M', 'F', 'F', 'M'] * 25,
'BMI': [24.5, 28.1, 22.3, 31.5] * 25
})
RenderTableOne(
epi_df, 'Age', 'Infected',
list_of_row_variables=['Age', 'Gender', 'BMI'],
table_format='github'
)