build_data_def

source

build_data_def(df, *, entity=None, time=None, factor_cutoff=10)

Infer a best-guess data dictionary (df_def) for df.

Produces one row per column with an inferred type and a humanized label, ready to pass to :func:~expdpy.set_labels. Column-name hints and dtypes drive the guess: a column is typed entity (name hints like country / iso / id, or — failing that — the column that uniquely keys the rows together with the time id), time (name hints like year / date, a datetime dtype, or an integer column in the calendar-year range), logical (boolean or two-valued), factor (categorical/object, or numeric with at most factor_cutoff distinct values), else numeric.

A best-guess role is also filled: a text column that is constant within the entity and ~1:1 with it (a readable label for the unit, e.g. a country name beside an ISO code) is tagged entity_name; all other rows are left blank. The analytical roles outcome / covariate are never guessed — mark them yourself (in the dictionary or via :func:~expdpy.set_roles).

Parameters

Name	Type	Description	Default
df	pd.DataFrame	The data frame to describe.	required
entity	str \| Sequence[str] \| None	Explicit entity (unit) identifier column name(s); when given, these win over detection (and are validated against `df`).	`None`
time	str \| None	Explicit time identifier column name; when given, it wins over detection.	`None`
factor_cutoff	int	Numeric columns with at most this many distinct values are typed `factor`.	`10`

Returns

Name	Type	Description
	pandas.DataFrame	A dictionary frame with columns `var_name`, `var_def`, `label`, `type`, `role` and `can_be_na` (one row per column of `df`, in column order).

Examples

Build a dictionary for any frame, then attach labels + declare the panel in one step:

import expdpy as ex
from expdpy.data import load_kuznets

ddef = ex.build_data_def(load_kuznets())
df = ex.set_labels(load_kuznets(), ddef, set_panel=True)
ddef.head()

	var_name	var_def	label	type	can_be_na
0	country	Country	Country	entity	False
1	iso	Iso	Iso	entity	False
2	year	Year	Year	time	False
3	continent	Continent	Continent	factor	True
4	gini_regional	Gini Regional	Gini Regional	numeric	True