explore_descriptive_table

source

explore_descriptive_table(
    df,
    stats=_DEFAULT_STATS,
    *,
    digits=3,
    periods=None,
    entity=None,
    time=None,
    caption=None,
    title=None,
    subtitle=None,
)

Report descriptive statistics for the numeric/logical variables of df.

The table reflects the panel structure of the data. When a time column is known (declared via :func:expdpy.set_panel / :func:expdpy.set_labels, or passed explicitly), each statistic is shown by period — by default at the first and last period — under a spanning column header (e.g. Mean over 2015 and 2025). Without a time dimension the table falls back to a single column per statistic. Rows are labelled from the data dictionary when available, and the number of observations and any variable with missing data are reported in the notes beneath the table.

Parameters

Name	Type	Description	Default
df	pd.DataFrame	Data frame containing at least one numeric/logical variable and two observations.	required
stats	Sequence[str]	Statistics to display, in order, chosen from `N`, `Mean`, `Std. dev.`, `Min.`, `25 %`, `Median`, `75 %`, `Max.`. Defaults to `Mean`, `Std. dev.`, `Median`, `Min.`, `Max.`. (The returned `.df` always carries all eight statistics regardless of this selection.)	`_DEFAULT_STATS`
digits	int \| Mapping[str, int]	Number of decimals for the displayed statistics: a single `int` applied to all, or a `{statistic: decimals}` mapping for per-statistic overrides (`N` is always shown as an integer).	`3`
periods	Sequence[object] \| None	Periods to show as sub-columns in the by-period layout. `None` (default) shows the first and last period; otherwise the listed period values (those not present are dropped with a warning). Ignored when no time dimension is summarized.	`None`
entity	str \| None	Optional panel identifiers (defaulting to those declared via :func:`expdpy.set_panel`). A resolved `time` drives the by-period layout; when both resolve, a note also reports the panel dimensions. For the within/between split of each variable see :func:`expdpy.explore_xtsum_table`.	`None`
time	str \| None	Optional panel identifiers (defaulting to those declared via :func:`expdpy.set_panel`). A resolved `time` drives the by-period layout; when both resolve, a note also reports the panel dimensions. For the within/between split of each variable see :func:`expdpy.explore_xtsum_table`.	`None`
caption	str \| None	Table title used for the Great Tables header.	`None`

Returns

Name	Type	Description
	DescriptiveTableResult	`df` (the pooled eight-statistic summary), `gt` (a Great Tables object) and `by_period` (a tidy `variable`-by-`period` frame, or `None`).

Examples

Basic — declare the panel via the data dictionary, then summarize by period (first and last year) with labelled rows:

import expdpy as ex
from expdpy.data import load_kuznets, load_kuznets_data_def

df = ex.set_labels(load_kuznets(), load_kuznets_data_def(), set_panel=True)
ex.explore_descriptive_table(df).gt

	Mean		Std. dev.		Median		Min.		Max.
Descriptive Statistics
	2015	2025	2015	2025	2015	2025	2015	2025	2015	2025
Regional inequality (Gini)	0.257	0.279	0.087	0.106	0.256	0.263	0.086	0.020	0.455	0.532
Log GDP per capita	9.078	9.322	1.494	1.535	9.074	9.584	6.444	6.275	11.655	11.918
Log GDP per capita²	84.613	89.229	27.205	28.523	82.338	91.859	41.530	39.373	135.834	142.048
Log GDP per capita³	808.131	874.893	379.593	407.283	747.186	880.434	267.634	247.060	1,583.117	1,692.984
GDP per capita (USD)	22,269.506	29,530.530	28,843.529	40,520.322	8,738.576	14,547.014	629.149	531.027	115,241.626	150,000.000
Population	18,438,095.075	21,017,625.750	45,331,372.978	51,130,240.237	4,639,542.000	5,395,351.000	209,936.000	263,897.000	331,159,497.000	368,704,165.000
Resource rents (% of GDP)	15.201	14.605	8.485	9.232	14.134	12.235	1.953	0.350	40.644	44.025
Arable land (share)	0.246	0.246	0.122	0.122	0.218	0.224	0.033	0.029	0.550	0.558
Trade openness (trade/GDP)	0.613	0.612	0.243	0.233	0.554	0.563	0.239	0.288	1.404	1.293
FDI inflows (% of GDP)	0.023	0.025	0.054	0.059	0.027	0.016	−0.082	−0.149	0.119	0.137
Area (km²)	450,980.746	450,980.746	1,023,860.606	1,023,860.606	125,400.969	125,400.969	1,224.257	1,224.257	8,189,082.989	8,189,082.989
Gasoline price (USD/litre)	0.530	0.574	0.213	0.216	0.492	0.616	0.200	0.200	0.950	1.024
Official development aid (USD)	347,510,465.864	345,373,820.793	508,075,434.134	492,345,744.460	124,807,975.154	141,595,753.694	−7,457,636.633	−7,407,267.673	2,200,000,000.000	2,200,000,000.000
Secondary enrollment (% gross)	53.845	57.257	26.238	27.313	53.060	60.128	6.261	9.809	104.200	125.014
Light-based inequality (Gini)	0.255	0.308	0.140	0.132	0.264	0.319	0.010	0.010	0.532	0.587
Democracy score (Polity2)	0.210	1.000	4.691	4.848	1.000	1.500	−10.000	−8.000	8.000	10.000
Federal state	0.200	0.200	0.403	0.403	0.000	0.000	0.000	0.000	1.000	1.000
Observations: 880.
Variables with missing data: FDI inflows (% of GDP) (46), Gasoline price (USD/litre) (232), Official development aid (USD) (65), Secondary enrollment (% gross) (145), Light-based inequality (Gini) (133), Democracy score (Polity2) (92).
Panel: 80 units (Country) over 11 periods (Year); 11.0 observations per unit on average.
Columns show 2 of 11 periods (2015 to 2025).

Advanced — choose the statistics and decimals, pick specific periods, and read the tidy by-period frame back from .by_period:

import expdpy as ex
from expdpy.data import load_kuznets, load_kuznets_data_def

df = ex.set_labels(load_kuznets(), load_kuznets_data_def(), set_panel=True)
result = ex.explore_descriptive_table(
    df,
    stats=("Mean", "Median", "Std. dev."),
    digits=2,
    periods=[2015, 2020, 2025],
    caption="Kuznets panel",
)
result.gt
result.by_period.head()

	variable	period	Mean	Median	Std. dev.
0	gini_regional	2015	0.257126	0.256008	0.087473
1	log_gdp_pc	2015	9.077922	9.073866	1.493976
2	log_gdp_pc_sq	2015	84.612723	82.338315	27.204941
3	log_gdp_pc_cu	2015	808.131041	747.186255	379.593260
4	gdp_pc	2015	22269.505624	8738.575704	28843.528729