diddesign 0.1.0__py3-none-any.whl

diddesign/__init__.py

@@ -0,0 +1,89 @@
+"""diddesign: Double Difference-in-Differences for Python.
+
+This package implements the multiple-pre-treatment DID estimator proposed by
+Egami and Yamauchi (2023, Political Analysis). It combines standard DID and
+sequential DID via efficient GMM weighting, extending to K-DID for panels
+with three or more pre-treatment periods and to staggered-adoption designs
+with lead-specific estimates.
+
+The public interface consists of two estimation functions—:func:`did` for
+treatment effect estimation and :func:`did_check` for pre-treatment
+diagnostics—together with immutable result objects (:class:`DidResult`,
+:class:`DidCheckResult`) whose frame accessors return pandas DataFrames
+for downstream analysis, plotting, and LaTeX export.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _package_version
+
+from .core.data_contracts import DataContractError, DidDataError
+from .diagnostics import DidCheckDiagnosticRow, DidCheckPatternRow, DidCheckResult, DidCheckTrendRow, did_check
+from .diagnostics_reporter import DiagnosticsReporter
+from .errors import (
+    DidError,
+    DidRuntimeError,
+    DidValueError,
+    DidWarning,
+    ErrorCode,
+    WarningCode,
+    did_warn,
+)
+from .estimators import did
+from .formula import DidFormulaSpec, did_formula
+from .plotting import check, fit
+from .results import (
+    DidBootstrapDraw,
+    DidBootstrapDrawK,
+    DidEstimateRow,
+    DidGmmAuditRow,
+    DidGmmRow,
+    DidResult,
+    DidWeightRow,
+    format_summary,
+    summary,
+)
+from .visualization import plot_diagnostics, plot_estimates, plot_pattern, plot_placebo, plot_trends
+
+DIDResult = DidResult
+
+try:
+    __version__ = _package_version("diddesign")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "DataContractError",
+    "DiagnosticsReporter",
+    "DidDataError",
+    "DidError",
+    "DidFormulaSpec",
+    "DidRuntimeError",
+    "DidValueError",
+    "DidWarning",
+    "ErrorCode",
+    "WarningCode",
+    "did_warn",
+    "DidBootstrapDraw",
+    "DidBootstrapDrawK",
+    "DidCheckDiagnosticRow",
+    "DidCheckPatternRow",
+    "DidCheckResult",
+    "DidCheckTrendRow",
+    "DidEstimateRow",
+    "DidGmmRow",
+    "DidResult",
+    "DIDResult",
+    "DidWeightRow",
+    "check",
+    "did",
+    "did_check",
+    "did_formula",
+    "fit",
+    "format_summary",
+    "plot_diagnostics",
+    "plot_estimates",
+    "plot_pattern",
+    "plot_placebo",
+    "plot_trends",
+    "summary",
+]

diddesign/core/__init__.py

@@ -0,0 +1,12 @@
+"""Core data validation helpers."""
+
+from .data_contracts import DataContractError, DidDataError, NormalizedDataContract, normalize_design_data
+from .validation import validate_sa_panel_preconditions
+
+__all__ = [
+    "DataContractError",
+    "DidDataError",
+    "NormalizedDataContract",
+    "normalize_design_data",
+    "validate_sa_panel_preconditions",
+]

diddesign/core/data_contracts.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ..errors import ErrorCode, DidValueError
+from .validation import (
+    DataContractError,
+    DidDataError,
+    materialize_rows,
+    require_binary_indicator,
+    require_column,
+    resolve_time_order_metadata,
+    validate_rcs_post_indicator,
+    validate_sa_panel_preconditions,
+    validate_design,
+    validate_sa_treatment_path,
+    validate_standard_did_panel_treatment_path,
+    validate_unique_panel_cells,
+)
+
+
+def _require_distinct_role_columns(**roles: str | None) -> None:
+    seen: dict[str, str] = {}
+    for role, column in roles.items():
+        if column is None:
+            continue
+        previous_role = seen.get(column)
+        if previous_role is not None:
+            raise DidValueError(
+                ErrorCode.E001,
+                f"{role} column must be distinct from {previous_role} column.",
+                context={"role": role, "previous_role": previous_role, "column": column},
+            )
+        seen[column] = role
+
+
+@dataclass(frozen=True)
+class NormalizedDataContract:
+    """Minimal normalized metadata for downstream diagnostics and estimators."""
+
+    design: str
+    data_type: str
+    branch: str
+    outcome: str
+    treatment: str
+    time: str
+    unit_id: str | None
+    post: str | None
+    time_order: tuple[Any, ...]
+    cluster_default: str | None
+    validation_trace: tuple[str, ...]
+
+    def as_metadata(self) -> dict[str, Any]:
+        return {
+            "design": self.design,
+            "data_type": self.data_type,
+            "branch": self.branch,
+            "outcome": self.outcome,
+            "treatment": self.treatment,
+            "time": self.time,
+            "unit_id": self.unit_id,
+            "post": self.post,
+            "time_order": self.time_order,
+            "cluster_default": self.cluster_default,
+            "validation_trace": self.validation_trace,
+        }
+
+
+def normalize_design_data(
+    rows,
+    *,
+    outcome: str,
+    treatment: str,
+    time: str,
+    unit_id: str | None = None,
+    post: str | None = None,
+    design: str = "did",
+    data_type: str = "panel",
+) -> NormalizedDataContract:
+    materialized = materialize_rows(rows)
+    validate_design(design, data_type)
+    require_column(materialized, outcome, allow_missing=True, field_name="outcome")
+    require_column(materialized, treatment, field_name="treatment")
+    require_column(materialized, time, field_name="time")
+    _require_distinct_role_columns(
+        outcome=outcome,
+        treatment=treatment,
+        time=time,
+        unit_id=unit_id if data_type == "panel" else None,
+        post=post if data_type == "rcs" else None,
+    )
+    require_binary_indicator(materialized, column=treatment, label="treatment")
+
+    validation_trace: list[str] = [
+        "required:outcome",
+        "required:treatment",
+        "required:time",
+        "binary:treatment",
+    ]
+    cluster_default: str | None = None
+    if data_type == "panel":
+        if unit_id is None:
+            raise DidValueError(
+                ErrorCode.E001,
+                "unit_id is required for panel data.",
+                context={"field_name": "unit_id", "data_type": data_type},
+            )
+        require_column(materialized, unit_id, field_name="unit_id")
+        cluster_default = unit_id
+        validation_trace.append("required:unit_id")
+        if design == "sa":
+            time_order = validate_sa_panel_preconditions(materialized, unit_id=unit_id, time=time)
+            validate_sa_treatment_path(
+                materialized,
+                unit_id=unit_id,
+                time=time,
+                treatment=treatment,
+                time_order=time_order,
+            )
+            _, time_label_kind = resolve_time_order_metadata(materialized, time=time)
+            validation_trace.extend(
+                ("balanced-panel", "unique:unit-time", f"time-order:{time_label_kind}", "absorbing:treatment")
+            )
+        else:
+            validate_unique_panel_cells(materialized, unit_id=unit_id, time=time)
+            time_order, time_label_kind = resolve_time_order_metadata(materialized, time=time)
+            validate_standard_did_panel_treatment_path(
+                materialized,
+                unit_id=unit_id,
+                time=time,
+                treatment=treatment,
+                time_order=time_order,
+            )
+            validation_trace.append("unique:unit-time")
+            validation_trace.append(f"time-order:{time_label_kind}")
+        branch = f"{design}-panel"
+    else:
+        if post is None:
+            raise DidValueError(
+                ErrorCode.E001,
+                "post is required for repeated cross-section data.",
+                context={"field_name": "post", "data_type": data_type},
+            )
+        require_column(materialized, post, field_name="post")
+        require_binary_indicator(materialized, column=post, label="post")
+        validation_trace.extend(("required:post", "binary:post"))
+        time_order, time_label_kind = resolve_time_order_metadata(materialized, time=time)
+        validate_rcs_post_indicator(materialized, time=time, post=post, time_order=time_order)
+        validation_trace.append(f"time-order:{time_label_kind}")
+        branch = "did-rcs"
+    return NormalizedDataContract(
+        design=design,
+        data_type=data_type,
+        branch=branch,
+        outcome=outcome,
+        treatment=treatment,
+        time=time,
+        unit_id=unit_id,
+        post=post,
+        time_order=time_order,
+        cluster_default=cluster_default,
+        validation_trace=tuple(validation_trace),
+    )
+
+
+__all__ = [
+    "DataContractError",
+    "DidDataError",
+    "NormalizedDataContract",
+    "normalize_design_data",
+]

diddesign/core/encoding.py

@@ -0,0 +1,105 @@
+"""Automatic string-to-integer encoding for DID structural variables.
+
+Mathematical justification:
+- time column: Correct temporal ordering is critical for sDID (ΔY_t = Y_t - Y_{t-1}).
+  Strings are encoded by lexicographic order (matching Stata's egen group() behavior).
+- unit_id column: Only grouping matters (ordering irrelevant for bootstrap clustering).
+- cluster column: Only grouping matters (ordering irrelevant for bootstrap blocking).
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import pandas as pd
+
+from ..errors import WarningCode, did_warn
+
+
+def auto_encode_string_columns(
+    df: pd.DataFrame,
+    *,
+    time: str | None = None,
+    unit_id: str | None = None,
+    id_cluster: str | None = None,
+) -> tuple[pd.DataFrame, dict[str, dict[Any, int]]]:
+    """Automatically encode string columns to integers for DID estimation.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Input data frame.
+    time : str
+        Time column name.
+    unit_id : str | None
+        Unit identifier column name.
+    id_cluster : str | None
+        Cluster variable column name.
+
+    Returns
+    -------
+    tuple[pd.DataFrame, dict[str, dict[Any, int]]]
+        Encoded DataFrame and encoding maps {column_name: {original_value: encoded_int}}.
+
+    Notes
+    -----
+    Encoding strategy (matches Stata's ``egen group()`` behavior):
+    - time: Sorted lexicographically then assigned 0, 1, 2, ...
+    - unit_id: Sorted lexicographically then assigned 0, 1, 2, ...
+    - id_cluster: Sorted lexicographically then assigned 0, 1, 2, ...
+
+    All columns use sorted order to ensure deterministic, reproducible encoding
+    that matches ``pd.factorize(sort=True)`` and Stata ``egen group()``.
+
+    Issues W001 warning for each auto-encoded column.
+    Does NOT encode columns that are already numeric.
+    """
+    encoded_df = df.copy()
+    encoding_maps: dict[str, dict[Any, int]] = {}
+
+    columns_to_check = []
+    if time is not None:
+        columns_to_check.append((time, "time"))
+    if unit_id is not None:
+        columns_to_check.append((unit_id, "unit_id"))
+    if id_cluster is not None and id_cluster != unit_id:
+        columns_to_check.append((id_cluster, "id_cluster"))
+
+    for col_name, role in columns_to_check:
+        if col_name is None or col_name not in df.columns:
+            continue
+
+        # Check if column contains string values
+        col_values = df[col_name]
+        if not _is_string_column(col_values):
+            continue
+
+        # Build encoding map: always sorted (matches Stata's egen group() behavior)
+        unique_values = sorted(col_values.dropna().unique())
+
+        encoding_map = {val: idx for idx, val in enumerate(unique_values)}
+        encoding_maps[col_name] = encoding_map
+
+        # Apply encoding
+        encoded_df[col_name] = col_values.map(encoding_map)
+
+        # Emit warning
+        did_warn(
+            WarningCode.W001,
+            f"String column '{col_name}' ({role}) automatically encoded to integer.",
+            context={"column": col_name, "role": role, "n_levels": len(encoding_map)},
+            stacklevel=3,
+        )
+
+    return encoded_df, encoding_maps
+
+
+def _is_string_column(series: pd.Series) -> bool:
+    """Check if a pandas Series contains string (object/string) dtype."""
+    if series.dtype == object:
+        non_null = series.dropna()
+        if len(non_null) == 0:
+            return False
+        return all(isinstance(v, str) for v in non_null.head(100))
+    return pd.api.types.is_string_dtype(series)