growth_cross_section

growth_cross_section(
    df,
    var,
    controls=None,
    *,
    entity=None,
    time=None,
    start=None,
    end=None,
    annualize=True,
)

Build the per-unit growth cross-section a convergence analysis starts from.

For each unit observed at both endpoints of a common window, the function records the initial and final level of var and the log growth between them: growth = (log(final) - log(initial)) / T when annualize (the average per-period log growth over the horizon T = end - start), or the raw log-difference otherwise. Controls are attached at their initial-period values.

Parameters

Name	Type	Description	Default
df	pd.DataFrame	Long panel data frame.	required
var	str	Numeric, strictly positive variable in levels (e.g. GDP per capita); the log is taken internally.	required
controls	Sequence[str] | str | None	Optional column name(s) whose initial-period values are carried into the cross-section (the conditional-convergence controls).	None
entity	str | None	Panel identifiers. Default to those declared via :func:geometrics.set_panel.	None
time	str | None	Panel identifiers. Default to those declared via :func:geometrics.set_panel.	None
start	float | None	First and last period of the growth window. Default to the earliest and latest period in the panel; only units observed at both endpoints are kept.	None
end	float | None	First and last period of the growth window. Default to the earliest and latest period in the panel; only units observed at both endpoints are kept.	None
annualize	bool	Divide the log-difference by the horizon T (default). False returns the total log growth over the window.	True

Returns

Name	Type	Description
	pandas.DataFrame	One row per unit with columns entity, initial, final, growth and one column per control, with the panel entity re-declared on df.attrs (:func:geometrics.set_panel).

Raises

Name	Type	Description
	KeyError	If var or a control is not a column of df.
	TypeError	If var or a control is not numeric.
	ValueError	If the window is empty or inverted, no unit spans it, or var has non-positive endpoint values (the log is undefined).

Examples

Two units over a 10-period window; the low-income unit grows faster:

import pandas as pd

from geometrics.convergence import growth_cross_section

df = pd.DataFrame(
    {
        "region": ["A", "A", "B", "B"],
        "year": [2000, 2010, 2000, 2010],
        "gdppc": [1000.0, 2000.0, 4000.0, 5000.0],
    }
)
cs = growth_cross_section(df, "gdppc", entity="region", time="year")
cs[["region", "initial", "final", "growth"]]