expdpy 0.2.0__py3-none-any.whl

expdpy/__init__.py

@@ -0,0 +1,147 @@
+"""expdpy — Explore your panel data interactively.
+
+A Python port of the ExPanDaR R package (Joachim Gassen, TRR 266). Provides a set
+of analytical functions for exploratory analysis of panel and cross-sectional data
+(descriptive tables, correlations, time trends, scatter plots, regression tables)
+returning interactive Plotly figures and Great Tables / pyfixest output, plus the
+``ExPdPy`` interactive app (Shiny for Python).
+"""
+
+from __future__ import annotations
+
+from expdpy._types import (
+    BarChartResult,
+    ByGroupBarGraphResult,
+    ByGroupTrendGraphResult,
+    CoefficientPlotResult,
+    CorrelationGraphResult,
+    CorrelationTableResult,
+    DescriptiveTableResult,
+    EstimationResult,
+    EventStudyResult,
+    ExtObsTableResult,
+    FixefPlotResult,
+    FWLPlotResult,
+    HausmanTestResult,
+    HistogramResult,
+    JointTestResult,
+    PanelViewResult,
+    PredictionResult,
+    QuantileTrendGraphResult,
+    RegressionTableResult,
+    RobustInferenceResult,
+    SandboxResult,
+    TrendGraphResult,
+)
+from expdpy.by_group import (
+    prepare_by_group_bar_graph,
+    prepare_by_group_trend_graph,
+    prepare_by_group_violin_graph,
+)
+from expdpy.coefplot import prepare_coefficient_plot
+from expdpy.correlation import prepare_correlation_graph
+from expdpy.did import prepare_event_study, prepare_panel_view
+from expdpy.distributions import prepare_bar_chart, prepare_histogram
+from expdpy.estimation import prepare_estimation
+from expdpy.fwl import prepare_fwl_plot
+from expdpy.inference import prepare_robust_inference
+from expdpy.missing import prepare_missing_values_graph
+from expdpy.outliers import treat_outliers
+from expdpy.panel_models import prepare_hausman_test, prepare_panel_table
+from expdpy.pedagogy import Explainer, explain, list_topics
+from expdpy.postestimation import (
+    prepare_fixef_plot,
+    prepare_joint_test,
+    prepare_predictions,
+)
+from expdpy.regression import prepare_regression_table
+from expdpy.sandbox import (
+    sandbox_clustering_se,
+    sandbox_omitted_variable_bias,
+    sandbox_pooled_vs_fixed_effects,
+)
+from expdpy.scatter import prepare_scatter_plot
+from expdpy.tables import (
+    prepare_correlation_table,
+    prepare_descriptive_table,
+    prepare_ext_obs_table,
+)
+from expdpy.trends import prepare_quantile_trend_graph, prepare_trend_graph
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # outliers
+    "treat_outliers",
+    # tables
+    "prepare_descriptive_table",
+    "prepare_correlation_table",
+    "prepare_ext_obs_table",
+    # correlation graph
+    "prepare_correlation_graph",
+    # trends
+    "prepare_trend_graph",
+    "prepare_quantile_trend_graph",
+    # by group
+    "prepare_by_group_bar_graph",
+    "prepare_by_group_trend_graph",
+    "prepare_by_group_violin_graph",
+    # distributions
+    "prepare_histogram",
+    "prepare_bar_chart",
+    # missing
+    "prepare_missing_values_graph",
+    # scatter
+    "prepare_scatter_plot",
+    # regression
+    "prepare_regression_table",
+    # estimation (IV / Poisson / GLM / model comparison)
+    "prepare_estimation",
+    # post-estimation
+    "prepare_fixef_plot",
+    "prepare_predictions",
+    "prepare_joint_test",
+    # robust inference
+    "prepare_robust_inference",
+    # fwl plot
+    "prepare_fwl_plot",
+    # coefficient plot
+    "prepare_coefficient_plot",
+    # event study / staggered DiD
+    "prepare_event_study",
+    "prepare_panel_view",
+    # concept sandboxes
+    "sandbox_omitted_variable_bias",
+    "sandbox_pooled_vs_fixed_effects",
+    "sandbox_clustering_se",
+    # panel models (linearmodels)
+    "prepare_panel_table",
+    "prepare_hausman_test",
+    # pedagogy
+    "explain",
+    "list_topics",
+    "Explainer",
+    # result types
+    "DescriptiveTableResult",
+    "CorrelationTableResult",
+    "CorrelationGraphResult",
+    "ExtObsTableResult",
+    "TrendGraphResult",
+    "QuantileTrendGraphResult",
+    "ByGroupBarGraphResult",
+    "ByGroupTrendGraphResult",
+    "HistogramResult",
+    "BarChartResult",
+    "RegressionTableResult",
+    "FWLPlotResult",
+    "CoefficientPlotResult",
+    "EstimationResult",
+    "FixefPlotResult",
+    "PredictionResult",
+    "JointTestResult",
+    "RobustInferenceResult",
+    "EventStudyResult",
+    "PanelViewResult",
+    "SandboxResult",
+    "HausmanTestResult",
+]

expdpy/_assets/favicon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="expdpy">
+  <title>expdpy</title>
+  <!-- Solid blue tile so the mark reads at favicon sizes -->
+  <rect x="0" y="0" width="64" height="64" rx="14" fill="#1f77b4"/>
+  <!-- Same N-shaped Kuznets curve, white, fitted to the tile -->
+  <path d="M12 49 C17 36 22 16 27 13 C32 10 38 42 42 44 C46 46 51 21 56 12"
+        fill="none" stroke="#ffffff" stroke-width="5"
+        stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="27" cy="13" r="3" fill="#ffffff"/>
+  <circle cx="42" cy="44" r="3" fill="#ffffff"/>
+  <circle cx="56" cy="12" r="3" fill="#ffffff"/>
+</svg>

expdpy/_assets/logo-navbar.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="expdpy logo">
+  <title>expdpy</title>
+  <!-- Faint axis (baseline + left axis) — translucent white for chart context on a blue navbar -->
+  <path d="M12 8 V54 H56" fill="none" stroke="#ffffff" stroke-opacity="0.5" stroke-width="2.5"
+        stroke-linecap="round" stroke-linejoin="round"/>
+  <!-- N-shaped Kuznets curve: rise, fall, rise -->
+  <path d="M14 48 C19 36 23 18 27 15 C32 12 37 41 41 43 C45 45 50 22 54 13"
+        fill="none" stroke="#ffffff" stroke-width="4"
+        stroke-linecap="round" stroke-linejoin="round"/>
+  <!-- Data points on the turning peaks/trough -->
+  <circle cx="27" cy="15" r="2.6" fill="#ffffff"/>
+  <circle cx="41" cy="43" r="2.6" fill="#ffffff"/>
+  <circle cx="54" cy="13" r="2.6" fill="#ffffff"/>
+</svg>

expdpy/_assets/logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="expdpy logo">
+  <title>expdpy</title>
+  <!-- Faint axis (baseline + left axis) for chart context -->
+  <path d="M12 8 V54 H56" fill="none" stroke="#cfe0f1" stroke-width="2.5"
+        stroke-linecap="round" stroke-linejoin="round"/>
+  <!-- N-shaped Kuznets curve: rise, fall, rise -->
+  <path d="M14 48 C19 36 23 18 27 15 C32 12 37 41 41 43 C45 45 50 22 54 13"
+        fill="none" stroke="#1f77b4" stroke-width="4"
+        stroke-linecap="round" stroke-linejoin="round"/>
+  <!-- Data points on the turning peaks/trough -->
+  <circle cx="27" cy="15" r="2.6" fill="#1f77b4"/>
+  <circle cx="41" cy="43" r="2.6" fill="#1f77b4"/>
+  <circle cx="54" cy="13" r="2.6" fill="#1f77b4"/>
+</svg>

expdpy/_corr.py

@@ -0,0 +1,80 @@
+"""Pairwise correlation engine shared by the correlation table and graph.
+
+Faithful port of ExPanDaR's internal ``cor_mat()`` helper: for every pair of columns it
+computes the correlation, two-sided p-value and the number of *pairwise* complete
+observations (rows finite in both columns), placing Pearson or Spearman results depending
+on ``method``. p-values use the asymptotic approximation (R's ``cor.test(..., exact = FALSE)``).
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+__all__ = ["CorMat", "cor_mat"]
+
+
+@dataclass(frozen=True)
+class CorMat:
+    """Square correlation/p-value/observation-count matrices (aligned by column name)."""
+
+    r: pd.DataFrame
+    p: pd.DataFrame
+    n: pd.DataFrame
+
+
+def cor_mat(df: pd.DataFrame, method: str) -> CorMat:
+    """Compute a pairwise correlation matrix.
+
+    Parameters
+    ----------
+    df
+        Data frame of numeric/logical columns.
+    method
+        ``"pearson"`` or ``"spearman"``.
+
+    Returns
+    -------
+    CorMat
+        ``r`` (coefficients, diagonal 1.0), ``p`` (p-values, diagonal 0.0) and ``n``
+        (pairwise observation counts, diagonal = non-missing count per column).
+    """
+    if method not in ("pearson", "spearman"):
+        raise ValueError("method must be 'pearson' or 'spearman'")
+
+    cols = list(df.columns)
+    mat = df.to_numpy(dtype=float)
+    n_cols = mat.shape[1]
+
+    r = np.full((n_cols, n_cols), np.nan)
+    p = np.full((n_cols, n_cols), np.nan)
+    n = np.full((n_cols, n_cols), np.nan)
+
+    finite = np.isfinite(mat)
+    np.fill_diagonal(r, 1.0)
+    np.fill_diagonal(p, 0.0)
+    for k in range(n_cols):
+        n[k, k] = int(finite[:, k].sum())
+
+    corr_fn = stats.pearsonr if method == "pearson" else stats.spearmanr
+    for i in range(n_cols - 1):
+        for j in range(i + 1, n_cols):
+            mask = finite[:, i] & finite[:, j]
+            count = int(mask.sum())
+            n[i, j] = n[j, i] = count
+            if count > 2:
+                with warnings.catch_warnings():
+                    warnings.simplefilter("ignore")
+                    coef, pval = corr_fn(mat[mask, i], mat[mask, j])
+                r[i, j] = r[j, i] = float(coef)
+                p[i, j] = p[j, i] = float(pval)
+
+    return CorMat(
+        r=pd.DataFrame(r, index=cols, columns=cols),
+        p=pd.DataFrame(p, index=cols, columns=cols),
+        n=pd.DataFrame(n, index=cols, columns=cols).astype("Int64"),
+    )

expdpy/_estimation/__init__.py

@@ -0,0 +1,38 @@
+"""Shared estimation engine for expdpy's regression-style functions.
+
+This private package holds the building blocks that every estimator plugs into:
+
+* :mod:`._spec` — the normalized :class:`ModelSpec` / :class:`VCovSpec` dataclasses,
+* :mod:`._formula` — a pure pyfixest-formula builder,
+* :mod:`._vcov` — a pure ``(vcov, vcov_kwargs)`` builder,
+* :mod:`._fit` — dispatch to ``feols`` / ``fepois`` / ``feglm`` (+ the SSC default),
+* :mod:`._tidy` — the tidy-coefficient-frame helper,
+* :mod:`._capture` — a stdout-capture context manager.
+
+``expdpy.regression`` is a thin adapter over this engine; keeping the engine separate
+lets future estimators (IV, Poisson, GLM, model comparison) reuse one tested core.
+"""
+
+from __future__ import annotations
+
+from expdpy._estimation._capture import capture_stdout
+from expdpy._estimation._fit import SSC, fit_model
+from expdpy._estimation._formula import build_formula
+from expdpy._estimation._results import coerce_models, first_model
+from expdpy._estimation._spec import ModelSpec, VCovSpec, as_list
+from expdpy._estimation._tidy import tidy_model
+from expdpy._estimation._vcov import build_vcov
+
+__all__ = [
+    "SSC",
+    "ModelSpec",
+    "VCovSpec",
+    "as_list",
+    "build_formula",
+    "build_vcov",
+    "capture_stdout",
+    "coerce_models",
+    "first_model",
+    "fit_model",
+    "tidy_model",
+]

expdpy/_estimation/_capture.py

@@ -0,0 +1,26 @@
+"""A small stdout-capture context manager (several pyfixest helpers print to stdout)."""
+
+from __future__ import annotations
+
+import contextlib
+import io
+from collections.abc import Iterator
+
+__all__ = ["capture_stdout"]
+
+
+@contextlib.contextmanager
+def capture_stdout() -> Iterator[io.StringIO]:
+    """Redirect ``sys.stdout`` into a buffer for the duration of the ``with`` block.
+
+    Some pyfixest helpers (notably ``etable(type="md")``) print to stdout and return
+    ``None``; this captures that text so it can be returned as a string instead.
+
+    Yields
+    ------
+    io.StringIO
+        The buffer; read its contents with ``.getvalue()`` after the block.
+    """
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        yield buf

expdpy/_estimation/_fit.py

@@ -0,0 +1,56 @@
+"""Fit dispatcher: build the formula + vcov and call the right pyfixest entrypoint."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+import pyfixest as pf
+
+from expdpy._estimation._formula import build_formula
+from expdpy._estimation._spec import ModelSpec
+from expdpy._estimation._vcov import build_vcov
+
+__all__ = ["SSC", "fit_model"]
+
+# Stata 'reghdfe'-consistent small-sample correction (matches lfe::felm cmethod='reghdfe').
+SSC = pf.ssc(k_adj=True, G_adj=True)
+
+
+def fit_model(data: pd.DataFrame, spec: ModelSpec, *, ssc: Any = SSC) -> Any:
+    """Fit ``spec`` on ``data`` via the appropriate pyfixest estimator.
+
+    Dispatches OLS/IV to ``feols``, ``"poisson"`` to ``fepois`` and ``"logit"``/``"probit"``
+    to ``feglm``. The caller is responsible for column selection, NA handling and casting
+    fixed effects to ``category`` (so behavior matches the historical implementation).
+
+    Parameters
+    ----------
+    data
+        The (already cleaned) estimation frame.
+    spec
+        The normalized model specification.
+    ssc
+        The small-sample-correction object (defaults to the module-level :data:`SSC`).
+
+    Returns
+    -------
+    Any
+        A fitted pyfixest model (``Feols`` / ``Fepois`` / ``Feglm``), or a ``FixestMulti``
+        when ``spec`` requests stepwise or multiple outcomes.
+    """
+    fml = build_formula(spec)
+    vcov, vcov_kwargs = build_vcov(spec.vcov)
+    kwargs: dict[str, Any] = {"vcov": vcov, "ssc": ssc}
+    if vcov_kwargs is not None:
+        kwargs["vcov_kwargs"] = vcov_kwargs
+    if spec.weights:
+        kwargs["weights"] = spec.weights
+
+    if spec.model in ("ols", "iv"):
+        return pf.feols(fml, data=data, **kwargs)
+    if spec.model == "poisson":
+        return pf.fepois(fml, data=data, **kwargs)
+    if spec.model in ("logit", "probit"):
+        return pf.feglm(fml, data=data, family=spec.model, **kwargs)
+    raise ValueError(f"unknown model kind: {spec.model!r}")  # pragma: no cover

expdpy/_estimation/_formula.py

@@ -0,0 +1,50 @@
+"""Pure builder of the pyfixest formula string from a :class:`ModelSpec`."""
+
+from __future__ import annotations
+
+from expdpy._estimation._spec import ModelSpec
+
+__all__ = ["build_formula"]
+
+
+def build_formula(spec: ModelSpec) -> str:
+    """Return the pyfixest formula string for ``spec``.
+
+    Handles plain OLS/GLM (``"dv ~ x1 + x2"``), fixed effects (``"| f1 + f2"``), stepwise
+    sequences (``"csw(x1, x2, x3)"``), multiple outcomes (``"y1 + y2 ~ ..."``) and the
+    instrumental-variables third part (``"| endog ~ instr"``), which pyfixest expects after
+    the fixed-effect block.
+
+    Parameters
+    ----------
+    spec
+        The normalized model specification.
+
+    Returns
+    -------
+    str
+        A formula string accepted by ``pyfixest.feols`` / ``fepois`` / ``feglm``.
+
+    Examples
+    --------
+    >>> from expdpy._estimation import ModelSpec, build_formula
+    >>> build_formula(ModelSpec(dv=("y",), idvs=("x1", "x2"), feffects=("firm",)))
+    'y ~ x1 + x2 | firm'
+    """
+    lhs = " + ".join(spec.dv)
+    if spec.stepwise and spec.idvs:
+        rhs = f"{spec.stepwise}({', '.join(spec.idvs)})"
+    elif spec.idvs:
+        rhs = " + ".join(spec.idvs)
+    else:
+        rhs = "1"
+    fml = f"{lhs} ~ {rhs}"
+    if spec.feffects:
+        fml += " | " + " + ".join(spec.feffects)
+    if spec.model == "iv":
+        if not spec.endog or not spec.instruments:
+            raise ValueError(
+                "instrumental-variables models require both 'endog' and 'instruments'"
+            )
+        fml += f" | {' + '.join(spec.endog)} ~ {' + '.join(spec.instruments)}"
+    return fml

expdpy/_estimation/_results.py

@@ -0,0 +1,30 @@
+"""Helpers for accepting a fitted model, a list of them, or an expdpy result object."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["coerce_models", "first_model"]
+
+
+def coerce_models(obj: Any) -> list[Any]:
+    """Return a flat list of fitted models from a model, a list, or a result object.
+
+    Accepts a single fitted pyfixest model, a ``list``/``tuple`` of them, or any expdpy
+    result object that carries a ``.models`` list (e.g. ``RegressionTableResult`` /
+    ``EstimationResult``).
+    """
+    if hasattr(obj, "models"):
+        out = list(obj.models)
+    elif isinstance(obj, (list, tuple)):
+        out = list(obj)
+    else:
+        out = [obj]
+    if not out:
+        raise ValueError("no models found")
+    return out
+
+
+def first_model(obj: Any) -> Any:
+    """Return the first fitted model from a model, a list, or a result object."""
+    return coerce_models(obj)[0]

expdpy/_estimation/_spec.py

@@ -0,0 +1,112 @@
+"""Normalized model + variance-covariance specifications for the estimation engine.
+
+These small, frozen, hashable dataclasses sit between the friendly public function
+signatures and pyfixest. Keeping the spec normalized in one place means the formula
+builder, the vcov builder and the fit dispatcher never have to re-parse user input.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+__all__ = [
+    "ModelKind",
+    "ModelSpec",
+    "Stepwise",
+    "VCovKind",
+    "VCovSpec",
+    "as_list",
+]
+
+VCovKind = Literal["iid", "hetero", "HC1", "HC2", "HC3", "CRV1", "CRV3", "NW", "DK"]
+ModelKind = Literal["ols", "iv", "poisson", "logit", "probit"]
+Stepwise = Literal["sw", "sw0", "csw", "csw0"]
+
+
+def as_list(value: Any) -> list[str]:
+    """Normalize ``None`` / ``""`` / str / sequence into a flat list of non-empty strings.
+
+    Parameters
+    ----------
+    value
+        ``None``, an empty string, a single variable name, or a sequence of names.
+
+    Returns
+    -------
+    list of str
+        The non-empty names, in order.
+    """
+    if value is None or (isinstance(value, str) and value == ""):
+        return []
+    if isinstance(value, str):
+        return [value]
+    return [v for v in value if v]
+
+
+@dataclass(frozen=True)
+class VCovSpec:
+    """A normalized variance-covariance (standard-error) specification.
+
+    Parameters
+    ----------
+    kind
+        The estimator: ``"iid"``, ``"hetero"`` (alias of ``"HC1"``), ``"HC1"``/``"HC2"``/
+        ``"HC3"`` (HC2/HC3 are unavailable with fixed effects), ``"CRV1"``/``"CRV3"``
+        (cluster-robust) or ``"NW"``/``"DK"`` (Newey-West / Driscoll-Kraay).
+    cluster
+        Cluster variable name(s); required for ``"CRV1"``/``"CRV3"``.
+    time_id
+        Time identifier; required for ``"NW"``/``"DK"``.
+    panel_id
+        Panel (unit) identifier; required for ``"NW"``/``"DK"``.
+    lag
+        Lag truncation for ``"NW"``/``"DK"`` (pyfixest picks a default when ``None``).
+    """
+
+    kind: VCovKind = "iid"
+    cluster: tuple[str, ...] = ()
+    time_id: str | None = None
+    panel_id: str | None = None
+    lag: int | None = None
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    """A normalized specification of a single (or stepwise/multi-outcome) model.
+
+    Parameters
+    ----------
+    dv
+        Dependent-variable name(s). More than one name builds a multi-outcome formula.
+    idvs
+        Independent (exogenous) regressor names.
+    feffects
+        Fixed-effect variable names absorbed by pyfixest.
+    endog
+        Endogenous regressors (instrumental-variables models only).
+    instruments
+        Excluded instruments (instrumental-variables models only).
+    model
+        Estimator family: ``"ols"``, ``"iv"``, ``"poisson"``, ``"logit"`` or ``"probit"``.
+    stepwise
+        Optional stepwise wrapper (``"sw"``, ``"sw0"``, ``"csw"`` or ``"csw0"``) applied to
+        ``idvs`` to estimate a sequence of nested models in one call.
+    vcov
+        The variance-covariance specification.
+    weights
+        Optional weights column name.
+    offset
+        Optional offset column name (Poisson models).
+    """
+
+    dv: tuple[str, ...]
+    idvs: tuple[str, ...]
+    feffects: tuple[str, ...] = ()
+    endog: tuple[str, ...] = ()
+    instruments: tuple[str, ...] = ()
+    model: ModelKind = "ols"
+    stepwise: Stepwise | None = None
+    vcov: VCovSpec = VCovSpec()
+    weights: str | None = None
+    offset: str | None = None

expdpy/_estimation/_tidy.py

@@ -0,0 +1,35 @@
+"""Tidy-coefficient-frame helper shared by the regression-style functions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+__all__ = ["tidy_model"]
+
+
+def tidy_model(model: Any, model_id: int, byvalue: str | None = None) -> pd.DataFrame:
+    """Return a tidy coefficient frame for one fitted model.
+
+    Parameters
+    ----------
+    model
+        A fitted pyfixest model exposing ``.tidy()``.
+    model_id
+        1-based identifier inserted as the ``model`` column (orders models in a table).
+    byvalue
+        Optional subgroup label inserted as a ``byvalue`` column (the ``byvar`` path).
+
+    Returns
+    -------
+    pandas.DataFrame
+        The model's ``tidy()`` frame with the coefficient index turned into a ``term``
+        column and a leading ``model`` column (plus ``byvalue`` when given).
+    """
+    out = model.tidy().reset_index()
+    out = out.rename(columns={out.columns[0]: "term"})
+    out.insert(0, "model", model_id)
+    if byvalue is not None:
+        out["byvalue"] = byvalue
+    return out

expdpy/_estimation/_vcov.py

@@ -0,0 +1,52 @@
+"""Pure builder of pyfixest's ``(vcov, vcov_kwargs)`` pair from a :class:`VCovSpec`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from expdpy._estimation._spec import VCovSpec
+
+__all__ = ["build_vcov"]
+
+
+def build_vcov(spec: VCovSpec) -> tuple[Any, dict[str, Any] | None]:
+    """Translate a :class:`VCovSpec` into pyfixest's ``vcov`` / ``vcov_kwargs`` arguments.
+
+    Parameters
+    ----------
+    spec
+        The normalized variance-covariance specification.
+
+    Returns
+    -------
+    tuple
+        ``(vcov, vcov_kwargs)``. ``vcov`` is a string (``"iid"``, ``"hetero"``, ``"HC1"``…)
+        or a ``{"CRV1"/"CRV3": "a + b"}`` dict; ``vcov_kwargs`` is ``None`` except for the
+        serial-correlation-robust estimators (``"NW"``/``"DK"``), which need ``time_id`` /
+        ``panel_id`` (and optionally ``lag``).
+
+    Examples
+    --------
+    >>> from expdpy._estimation import VCovSpec, build_vcov
+    >>> build_vcov(VCovSpec(kind="CRV1", cluster=("firm", "year")))
+    ({'CRV1': 'firm + year'}, None)
+    >>> build_vcov(VCovSpec(kind="iid"))
+    ('iid', None)
+    """
+    kind = spec.kind
+    if kind in ("CRV1", "CRV3"):
+        if not spec.cluster:
+            raise ValueError(
+                f"{kind} standard errors require at least one cluster variable"
+            )
+        return {kind: " + ".join(spec.cluster)}, None
+    if kind in ("NW", "DK"):
+        if spec.time_id is None or spec.panel_id is None:
+            raise ValueError(
+                f"{kind} standard errors require both 'time_id' and 'panel_id'"
+            )
+        kwargs: dict[str, Any] = {"time_id": spec.time_id, "panel_id": spec.panel_id}
+        if spec.lag is not None:
+            kwargs["lag"] = spec.lag
+        return kind, kwargs
+    return kind, None