geometrics 0.1.0__py3-none-any.whl

geometrics/__init__.py

@@ -0,0 +1,147 @@
+"""geometrics: regional growth, convergence, and inequality on the PySAL stack.
+
+geometrics wraps the standard analyses of the regional convergence literature —
+exploratory spatial data analysis, β/σ/club convergence, spatial econometric models,
+distribution dynamics, inequality decomposition, and local (GWR) models — into
+illustrative, easy-to-apply functions built on libpysal, esda, giddy, inequality,
+mapclassify, spreg, and mgwr.
+
+Three inputs drive everything: a geometry with only the entity ID (``read_gdf``),
+a long-form panel (``set_panel`` / ``set_labels``), and a data dictionary
+(``df_dict``, inferable with ``build_data_dict``). Every public function returns a
+frozen result dataclass with ``.df``, ``.fig`` and/or ``.gt``, plain-language
+``.interpret()``, and a concept ``.explain()``.
+"""
+
+from geometrics import data
+from geometrics._data_dict import build_data_dict
+from geometrics._geo import read_gdf
+from geometrics._labels import resolve_label, set_labels
+from geometrics._panel import resolve_panel, set_panel
+from geometrics._roles import set_roles
+from geometrics._theme import get_palette, set_palette
+from geometrics._types import (
+    BetaConvergenceResult,
+    ChoroplethMapResult,
+    ConnectivityMapResult,
+    ConvergenceClubsResult,
+    DistributionOverTimeResult,
+    GWRResult,
+    InequalityOverTimeResult,
+    LisaClusterMapResult,
+    MarkovTransitionsResult,
+    MGWRResult,
+    MoranOverTimeResult,
+    MoranPlotResult,
+    SigmaConvergenceResult,
+    SpacetimeHeatmapResult,
+    SpatialDiagnosticsResult,
+    SpatialMarkovResult,
+    SpatialModelResult,
+    TheilDecompositionResult,
+    WeightsRobustnessResult,
+)
+from geometrics.clubs import analyze_convergence_clubs
+from geometrics.convergence import (
+    analyze_beta_convergence,
+    analyze_sigma_convergence,
+    growth_cross_section,
+)
+from geometrics.dependence import (
+    explore_lisa_cluster_map,
+    explore_moran_over_time,
+    explore_moran_plot,
+)
+from geometrics.distribution_dynamics import (
+    analyze_markov_transitions,
+    analyze_spatial_markov,
+)
+from geometrics.gwr import analyze_gwr, analyze_mgwr
+from geometrics.maps import explore_choropleth_map
+from geometrics.pedagogy import Explainer, explain, list_topics
+from geometrics.regional_inequality import (
+    analyze_inequality_over_time,
+    analyze_theil_decomposition,
+)
+from geometrics.spacetime import (
+    explore_distribution_over_time,
+    explore_spacetime_heatmap,
+)
+from geometrics.spatial_models import (
+    analyze_spatial_diagnostics,
+    analyze_spatial_model,
+    analyze_spatial_model_by_weights,
+)
+from geometrics.weights import explore_connectivity_map, make_weights
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # ===== EXPLORE =====
+    # maps
+    "explore_choropleth_map",
+    # spatial weights
+    "explore_connectivity_map",
+    # spatial dependence (ESDA)
+    "explore_moran_plot",
+    "explore_lisa_cluster_map",
+    "explore_moran_over_time",
+    # space-time dynamics
+    "explore_distribution_over_time",
+    "explore_spacetime_heatmap",
+    # ===== ANALYZE =====
+    # convergence
+    "analyze_beta_convergence",
+    "analyze_sigma_convergence",
+    "analyze_convergence_clubs",
+    # spatial econometric models (spreg)
+    "analyze_spatial_model",
+    "analyze_spatial_diagnostics",
+    "analyze_spatial_model_by_weights",
+    # distribution dynamics (giddy)
+    "analyze_markov_transitions",
+    "analyze_spatial_markov",
+    # regional inequality (PySAL inequality)
+    "analyze_inequality_over_time",
+    "analyze_theil_decomposition",
+    # local models (mgwr)
+    "analyze_gwr",
+    "analyze_mgwr",
+    # ===== UTILITIES =====
+    "read_gdf",
+    "make_weights",
+    "growth_cross_section",
+    "set_panel",
+    "resolve_panel",
+    "set_labels",
+    "resolve_label",
+    "set_roles",
+    "build_data_dict",
+    "set_palette",
+    "get_palette",
+    "explain",
+    "list_topics",
+    "Explainer",
+    # ===== DATA =====
+    "data",
+    # ===== RESULT TYPES =====
+    "ChoroplethMapResult",
+    "ConnectivityMapResult",
+    "MoranPlotResult",
+    "LisaClusterMapResult",
+    "MoranOverTimeResult",
+    "DistributionOverTimeResult",
+    "SpacetimeHeatmapResult",
+    "BetaConvergenceResult",
+    "SigmaConvergenceResult",
+    "ConvergenceClubsResult",
+    "SpatialModelResult",
+    "SpatialDiagnosticsResult",
+    "WeightsRobustnessResult",
+    "MarkovTransitionsResult",
+    "SpatialMarkovResult",
+    "InequalityOverTimeResult",
+    "TheilDecompositionResult",
+    "GWRResult",
+    "MGWRResult",
+]

geometrics/_common.py

@@ -0,0 +1,193 @@
+"""Shared low-level helpers used across the analytical modules.
+
+These are pure, dependency-light utilities (numeric-aware level sorting, a sample-size
+default opacity, time-axis coercion, the standard error, and an x-axis layout builder) that
+several feature modules need. Centralizing them here keeps the feature modules from
+importing private helpers out of one another.
+
+This module imports only :mod:`numpy` / :mod:`pandas`, so it can be imported anywhere without
+risking a cycle.
+"""
+
+from __future__ import annotations
+
+import re
+from math import log
+
+import numpy as np
+import pandas as pd
+from pandas.api import types as pdt
+
+__all__ = [
+    "sorted_levels",
+    "argsort_levels",
+    "default_alpha",
+    "try_convert_ts_id",
+    "se",
+    "xaxis",
+    "entity_display_map",
+    "entity_display_series",
+    "lead_columns",
+]
+
+# Full date strings only (YYYY-MM-DD / YYYY/MM/DD) — bare-year strings like "2013" must fall
+# through to numeric (R's ``as.Date("2013")`` fails).
+_FULL_DATE = re.compile(r"^\d{4}[-/]\d{1,2}[-/]\d{1,2}")
+
+
+def sorted_levels(values: pd.Series) -> list[str]:
+    """Return the distinct levels of ``values`` sorted numerically when possible.
+
+    Group labels like ``"2"`` and ``"10"`` must order as 2 < 10, not lexically.
+    """
+    levels = list(dict.fromkeys(values.astype(str)))
+    num = pd.to_numeric(pd.Series(levels), errors="coerce")
+    if not num.isna().any():
+        return [lvl for _, lvl in sorted(zip(num, levels, strict=True))]
+    return sorted(levels)
+
+
+def argsort_levels(index: pd.Index) -> np.ndarray:
+    """Return a stable sort order (argsort indices) for ``index``, numeric-aware.
+
+    Numbers sort numerically (``2`` before ``10``); a non-numeric index sorts lexically.
+    """
+    idx = index.astype(str)
+    num = pd.to_numeric(pd.Series(idx), errors="coerce")
+    keys = num.to_numpy() if not num.isna().any() else idx.to_numpy()
+    return np.asarray(np.argsort(keys, kind="stable"))
+
+
+def default_alpha(n: int) -> float:
+    """Sample-size-based default opacity (ExPanDaR's formula)."""
+    if n <= 0:
+        return 1.0
+    return min(1.0, 1.0 / (1.0 + max(0.0, log(n) - log(100))))
+
+
+def try_convert_ts_id(s: pd.Series) -> tuple[pd.Series, bool]:
+    """Coerce a time identifier to a nicer type for axis ticks.
+
+    Cascade (mirrors ExPanDaR's ``try_convert_ts_id``): keep existing datetime/numeric
+    types, else try full-date parsing, else numeric, else an ordered categorical.
+
+    Returns
+    -------
+    tuple of (pandas.Series, bool)
+        The converted series and whether it is an ordered categorical (discrete axis).
+    """
+    if pdt.is_datetime64_any_dtype(s):
+        return s, False
+    if pdt.is_numeric_dtype(s) and not pdt.is_bool_dtype(s):
+        return s, False
+
+    # For factor/categorical/object indices, try the same cascade R applies to the
+    # character values: full-date -> numeric -> ordered categorical.
+    str_vals = s.astype(str)
+    if str_vals.str.match(_FULL_DATE).all():
+        try:
+            return pd.to_datetime(str_vals), False
+        except (ValueError, TypeError):
+            pass
+    num = pd.to_numeric(str_vals, errors="coerce")
+    if not num.isna().any():
+        return pd.Series(num.to_numpy(), index=s.index), False
+    cats = sorted(s.dropna().astype(str).unique(), key=str)
+    return s.astype(str).astype(pd.CategoricalDtype(cats, ordered=True)), True
+
+
+def se(s: pd.Series) -> float:
+    """Return the standard error of the mean: sd / sqrt(n_non_missing)."""
+    cnt = int(s.notna().sum())
+    if cnt == 0:
+        return np.nan
+    return float(s.std(ddof=1) / np.sqrt(cnt))
+
+
+def xaxis(
+    time: str, ordered: bool, ts_values: pd.Series, title: str | None = None
+) -> dict:
+    """Build x-axis layout kwargs, fixing category order when discrete.
+
+    ``title`` overrides the axis title (default: the bare ``time`` name).
+    """
+    axis: dict = {"title": title if title is not None else time}
+    if ordered:
+        cats = [str(c) for c in ts_values.cat.categories]
+        axis.update(type="category", categoryorder="array", categoryarray=cats)
+    return axis
+
+
+def _is_blank_name(value: object) -> bool:
+    """Return ``True`` for ``None`` / NaN / empty-or-whitespace strings."""
+    if value is None or value is pd.NA:
+        return True
+    if isinstance(value, float) and np.isnan(value):
+        return True
+    return not str(value).strip()
+
+
+def entity_display_map(
+    df: pd.DataFrame, entity: str, entity_name: str | None
+) -> dict[str, str]:
+    """Map each entity id (as ``str``) to a ``"Name (id)"`` display string.
+
+    Used by panel figures/tables so a unit shows a readable label (e.g. ``"Bolivia (BOL)"``)
+    instead of the bare id. The mapping is keyed by ``str(id)`` so a lookup is robust to the id
+    being re-typed along the way (e.g. an int id stringified by a cross-section reshape): look
+    up with ``disp.get(str(u), str(u))``.
+
+    Falls back to an identity map ``{str(id): str(id)}`` when ``entity_name`` is ``None``, not a
+    column of ``df``, or equal to ``entity`` (no ``"X (X)"``); per id, when the name is blank or
+    missing the display is the bare ``str(id)``.
+
+    Parameters
+    ----------
+    df
+        The frame holding the ``entity`` (and optionally ``entity_name``) columns.
+    entity
+        The entity (unit) id column.
+    entity_name
+        The human-readable name column constant within each entity, or ``None``.
+
+    Returns
+    -------
+    dict
+        ``{str(id): display_string}`` for every distinct id in ``df[entity]``.
+    """
+    ids = df[entity].dropna().unique()
+    if entity_name is None or entity_name == entity or entity_name not in df.columns:
+        return {str(uid): str(uid) for uid in ids}
+    pairs = df[[entity, entity_name]].drop_duplicates(subset=[entity])
+    names = dict(zip(pairs[entity], pairs[entity_name], strict=True))
+    out: dict[str, str] = {}
+    for uid in ids:
+        name = names.get(uid)
+        out[str(uid)] = str(uid) if _is_blank_name(name) else f"{name} ({uid})"
+    return out
+
+
+def entity_display_series(
+    df: pd.DataFrame, entity: str, entity_name: str | None
+) -> pd.Series:
+    """Return per-row ``"Name (id)"`` display labels aligned to ``df.index``.
+
+    A row-wise convenience over :func:`entity_display_map` (``str(id)`` fallback throughout).
+    """
+    disp = entity_display_map(df, entity, entity_name)
+    return df[entity].map(lambda uid: disp.get(str(uid), str(uid)))
+
+
+def lead_columns(names: list[str], lead: list[str | None]) -> list[str]:
+    """Reorder ``names`` so any of ``lead`` (in order, ignoring ``None``/absent) come first.
+
+    Stable for the remaining columns. Used to float the declared key variables (main outcome,
+    then covariates) to the front of a table or correlation matrix when roles are set; a no-op
+    when none of ``lead`` is present (so role-less data keeps its original column order).
+    """
+    present = set(names)
+    front = list(dict.fromkeys(c for c in lead if c is not None and c in present))
+    if not front:
+        return list(names)
+    front_set = set(front)
+    return [*front, *[n for n in names if n not in front_set]]

geometrics/_data_dict.py

@@ -0,0 +1,369 @@
+"""Infer a data dictionary (``df_dict``) from a raw DataFrame.
+
+The bundled datasets ship a *data dictionary* — a ``df_dict`` frame describing each column's
+human-readable label and its role in the panel (``entity`` / ``time`` / ``factor`` /
+``logical`` / ``numeric``). :func:`build_data_dict` produces a best-guess dictionary for *any*
+DataFrame, so a user who brings only a data file still gets labelled figures and panel-aware
+views — and, in the ``geometrics`` apps, an editable starting point.
+
+The result is a plain frame with the same columns the loaders return
+(``var_name`` / ``var_def`` / ``label`` / ``type`` / ``role`` / ``can_be_na``), consumable
+directly by :func:`~geometrics.set_labels`::
+
+    df = gm.set_labels(df, gm.build_data_dict(df), set_panel=True)
+
+The inference is deliberately conservative: column-name hints and dtypes pick the most likely
+roles, but it is only a *guess* — pass ``entity=`` / ``time=`` to pin the panel ids, or edit
+the returned frame.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+import pandas as pd
+from pandas.api import types as pdt
+
+from geometrics._validation import ensure_dataframe
+
+__all__ = ["build_data_dict"]
+
+#: The six columns of a data-dictionary frame, in order.
+_COLUMNS = ["var_name", "var_def", "label", "type", "role", "can_be_na"]
+
+#: Lower-cased name tokens that hint a column is a cross-sectional (unit) identifier.
+_ENTITY_HINTS = {
+    "id",
+    "ids",
+    "code",
+    "iso",
+    "iso2",
+    "iso3",
+    "country",
+    "countries",
+    "nation",
+    "firm",
+    "company",
+    "unit",
+    "entity",
+    "region",
+    "state",
+    "province",
+    "prov",
+    "municipality",
+    "muni",
+    "department",
+    "dept",
+    "district",
+    "ticker",
+    "gvkey",
+    "permno",
+    "cusip",
+    "individual",
+    "person",
+    "household",
+}
+
+#: Lower-cased name tokens that hint a column holds a human-readable *entity name* (a label
+#: for the unit, e.g. a country/province name), used to pick the entity-name column.
+_NAME_TOKENS = {
+    "name",
+    "names",
+    "country",
+    "countries",
+    "nation",
+    "province",
+    "prov",
+    "region",
+    "state",
+    "district",
+    "municipality",
+    "muni",
+    "department",
+    "dept",
+    "firm",
+    "company",
+    "person",
+    "household",
+    "individual",
+    "label",
+    "title",
+}
+
+#: Lower-cased name tokens that hint a column is a *code/id* (the opposite of a readable name).
+_CODE_TOKENS = {
+    "id",
+    "ids",
+    "code",
+    "iso",
+    "iso2",
+    "iso3",
+    "ticker",
+    "gvkey",
+    "permno",
+    "cusip",
+    "key",
+    "num",
+    "no",
+    "gid",
+}
+
+#: Lower-cased name tokens that hint a column is the time identifier.
+_TIME_HINTS = {
+    "year",
+    "yr",
+    "date",
+    "time",
+    "period",
+    "quarter",
+    "qtr",
+    "month",
+    "week",
+    "wave",
+    "fyear",
+    "datadate",
+}
+
+
+def _tokens(name: object) -> set[str]:
+    """Split a column name into lower-cased word tokens."""
+    return set(re.split(r"[\s_\-./]+", str(name).strip().lower())) - {""}
+
+
+def _name_matches(name: object, hints: set[str]) -> bool:
+    """Return ``True`` when any word token of ``name`` is one of ``hints``."""
+    return bool(_tokens(name) & hints)
+
+
+def _humanize(name: object) -> str:
+    """Turn a column name into a title-cased display label (``gdp_pc`` -> ``Gdp Pc``)."""
+    return re.sub(r"[\s_\-./]+", " ", str(name)).strip().title() or str(name)
+
+
+def _looks_like_year(s: pd.Series) -> bool:
+    """Return ``True`` for an integer-valued column whose values look like calendar years."""
+    vals = s.dropna()
+    if vals.empty or vals.nunique() < 2:
+        return False
+    integral = pdt.is_integer_dtype(s) or (
+        pdt.is_float_dtype(s) and bool((vals % 1 == 0).all())
+    )
+    if not integral:
+        return False
+    return bool((vals >= 1500).all() and (vals <= 2200).all())
+
+
+def _value_type(s: pd.Series, factor_cutoff: int) -> str:
+    """Classify a non-id column as ``logical`` / ``factor`` / ``numeric``."""
+    n = int(s.dropna().nunique())
+    if pdt.is_bool_dtype(s) or n == 2:
+        return "logical"
+    if isinstance(s.dtype, pd.CategoricalDtype) or pdt.is_object_dtype(s):
+        return "factor"
+    if pdt.is_numeric_dtype(s):
+        return "factor" if 1 < n <= factor_cutoff else "numeric"
+    return "factor"
+
+
+def _detect_time(df: pd.DataFrame, cols: list[str]) -> str | None:
+    """Detect the most likely time column, or ``None``."""
+    hinted = [c for c in cols if _name_matches(c, _TIME_HINTS)]
+    datetimes = [c for c in cols if pdt.is_datetime64_any_dtype(df[c])]
+    yearish = [c for c in cols if _looks_like_year(df[c])]
+    for group in (
+        [c for c in hinted if c in yearish or c in datetimes],
+        hinted,
+        datetimes,
+        yearish,
+    ):
+        if group:
+            return group[0]
+    return None
+
+
+def _detect_entities(
+    df: pd.DataFrame, cols: list[str], time_col: str | None
+) -> list[str]:
+    """Detect the cross-sectional identifier column(s), in column order, or ``[]``."""
+    candidates = [c for c in cols if c != time_col]
+    hinted = [
+        c
+        for c in candidates
+        if _name_matches(c, _ENTITY_HINTS) and not pdt.is_float_dtype(df[c])
+    ]
+    if hinted:
+        return hinted
+    if time_col is not None:  # fall back: a column that forms a key with the time id
+        for c in candidates:
+            keyable = (
+                pdt.is_object_dtype(df[c])
+                or isinstance(df[c].dtype, pd.CategoricalDtype)
+                or pdt.is_integer_dtype(df[c])
+            )
+            if (
+                keyable
+                and df[c].notna().all()
+                and not df.duplicated([c, time_col]).any()
+            ):
+                return [c]
+    return []
+
+
+def _avg_len(s: pd.Series) -> float:
+    """Average string length of a column's non-missing values (a name-likeness tiebreak)."""
+    vals = s.dropna().astype(str)
+    return float(vals.str.len().mean()) if len(vals) else 0.0
+
+
+def _name_likeness(name: object, s: pd.Series) -> int:
+    """Score how *name-like* (vs *code-like*) a column is — higher means more readable."""
+    toks = _tokens(name)
+    score = 2 * bool(toks & _NAME_TOKENS) - 2 * bool(toks & _CODE_TOKENS)
+    if pdt.is_integer_dtype(s):
+        score -= 1
+    return score
+
+
+def _detect_entity_name(
+    df: pd.DataFrame, entities: list[str], time_col: str | None
+) -> str | None:
+    """Detect a human-readable entity-name column, or ``None``.
+
+    A candidate is a text/categorical column that is **constant within** the primary entity id
+    and **~1:1** with it (one label per unit). The most name-like candidate wins, but only when
+    it is strictly more name-like than the entity id itself (so an id that is already a name —
+    e.g. ``country`` paired with ``iso`` — yields ``None`` rather than a backwards label).
+    """
+    if not entities:
+        return None
+    primary = entities[0]
+    n_ent = int(df[primary].dropna().nunique())
+    if n_ent == 0:
+        return None
+    candidates: list[str] = []
+    for c in df.columns:
+        if c in (primary, time_col):
+            continue
+        s = df[c]
+        if pdt.is_numeric_dtype(s) or pdt.is_bool_dtype(s):
+            continue
+        if not (
+            pdt.is_object_dtype(s)
+            or isinstance(s.dtype, pd.CategoricalDtype)
+            or pdt.is_string_dtype(s)
+        ):
+            continue
+        g = df[[primary, c]].dropna()
+        if g.empty or (g.groupby(primary)[c].nunique() > 1).any():
+            continue  # not constant within the entity
+        if g[c].nunique() < 0.95 * n_ent:
+            continue  # not ~1:1 with the entities
+        candidates.append(c)
+    if not candidates:
+        return None
+    key = lambda c: (_name_likeness(c, df[c]), _avg_len(df[c]))  # noqa: E731
+    best = max(candidates, key=key)
+    if key(best) <= (_name_likeness(primary, df[primary]), _avg_len(df[primary])):
+        return None
+    return best
+
+
+def build_data_dict(
+    df: pd.DataFrame,
+    *,
+    entity: str | Sequence[str] | None = None,
+    time: str | None = None,
+    factor_cutoff: int = 10,
+) -> pd.DataFrame:
+    """Infer a best-guess data dictionary (``df_dict``) for ``df``.
+
+    Produces one row per column with an inferred ``type`` and a humanized ``label``, ready to
+    pass to :func:`~geometrics.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:`~geometrics.set_roles`).
+
+    Parameters
+    ----------
+    df
+        The data frame to describe.
+    entity
+        Explicit entity (unit) identifier column name(s); when given, these win over
+        detection (and are validated against ``df``).
+    time
+        Explicit time identifier column name; when given, it wins over detection.
+    factor_cutoff
+        Numeric columns with at most this many distinct values are typed ``factor``.
+
+    Returns
+    -------
+    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:
+
+    ```python
+    import pandas as pd
+
+    import geometrics as gm
+
+    df = pd.DataFrame(
+        {
+            "region": ["A", "A", "B", "B"],
+            "year": [2000, 2001, 2000, 2001],
+            "gdp_pc": [1.0, 1.1, 2.0, 2.1],
+        }
+    )
+    ddict = gm.build_data_dict(df)
+    df = gm.set_labels(df, ddict, set_panel=True)
+    ddict.head()
+    ```
+    """
+    df = ensure_dataframe(df)
+    cols = list(df.columns)
+
+    explicit_entities = [entity] if isinstance(entity, str) else list(entity or [])
+    for col in (*explicit_entities, *([time] if time is not None else [])):
+        if col not in cols:
+            raise ValueError(f"column {col!r} is not in df")
+
+    time_col = time if time is not None else _detect_time(df, cols)
+    entities = explicit_entities or _detect_entities(df, cols, time_col)
+    entity_set = set(entities)
+    name_col = _detect_entity_name(df, entities, time_col)
+
+    rows = []
+    for col in cols:
+        if col in entity_set:
+            typ = "entity"
+        elif col == time_col:
+            typ = "time"
+        else:
+            typ = _value_type(df[col], factor_cutoff)
+        label = _humanize(col)
+        rows.append(
+            {
+                "var_name": col,
+                "var_def": label,
+                "label": label,
+                "type": typ,
+                "role": "entity_name" if col == name_col else "",
+                "can_be_na": typ not in ("entity", "time"),
+            }
+        )
+
+    out = pd.DataFrame(rows, columns=_COLUMNS)
+    out["can_be_na"] = out["can_be_na"].astype(bool)
+    return out