prepare_fwl_plot

prepare_fwl_plot(
    df,
    dv,
    var,
    controls=None,
    feffects=None,
    clusters=None,
    *,
    n_sample=1000,
    alpha=0.5,
    seed=0,
)

Frisch-Waugh-Lovell scatter of dv against the focal regressor var.

Residualizes both dv and var on controls and feffects over a single complete-case sample, then plots the residuals with an OLS fit line and a 95% pointwise confidence band. Fixed effects are absorbed (group-demeaned) by pyfixest, so the plot shows the relationship between var and dv net of both the other regressors and the fixed effects. By the Frisch-Waugh-Lovell theorem the slope of this residual regression equals the coefficient on var in the full model; the annotation states this and reports the full model’s standard error (clustered when clusters is given, matching :func:expdpy.prepare_regression_table), the sample size, and the within-R².

Parameters

Name	Type	Description	Default
df	pd.DataFrame	Data frame containing the variables.	required
dv	str	Dependent (outcome) variable name.	required
var	str	Focal regressor whose partial relationship with dv is plotted.	required
controls	Sequence[str] | str | None	Additional regressors to residualize out (entered linearly). May be None.	None
feffects	Sequence[str] | str | None	Fixed-effects variable name(s) absorbed during residualization. May be None.	None
clusters	Sequence[str] | str | None	Cluster variable name(s) for the standard error reported in the annotation. Does not affect the point estimate or the plotted confidence band.	None
n_sample	int | None	Number of points drawn in the scatter (default 1000). The fit line and band are always computed on all complete-case rows. None plots every point.	1000
alpha	float	Marker opacity for the scatter points (default 0.5).	0.5
seed	int	Seed for the point-subsampling RNG (default 0), for reproducible figures.	0

Returns

Name	Type	Description
	FWLPlotResult	df (residual frame), fig (Plotly figure) and the scalar statistics slope, se, intercept, n_obs and r2_within.

Examples

Basic — partial relationship of the outcome and a single regressor:

import expdpy as ex
from expdpy.data import load_kuznets

df = load_kuznets()
ex.prepare_fwl_plot(df, dv="gini_regional", var="log_gdp_pc").fig

Advanced — residualize on the other cubic terms and two-way fixed effects, cluster the reported standard error by country, then read the FWL statistics back:

result = ex.prepare_fwl_plot(
    df,
    dv="gini_regional",
    var="log_gdp_pc",
    controls=["log_gdp_pc_sq", "log_gdp_pc_cu"],
    feffects=["country", "year"],
    clusters=["country"],
)
result.fig
result.slope, result.se, result.r2_within