diff-diff 3.1.3__tar.gz → 3.3.0__tar.gz

{diff_diff-3.1.3 → diff_diff-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.1.3
+Version: 3.3.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -57,6 +57,7 @@ Project-URL: Repository, https://github.com/igerber/diff-diff
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Downloads](https://img.shields.io/pypi/dm/diff-diff.svg)](https://pypi.org/project/diff-diff/)
 [![Documentation](https://readthedocs.org/projects/diff-diff/badge/?version=stable)](https://diff-diff.readthedocs.io/en/stable/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19646175.svg)](https://doi.org/10.5281/zenodo.19646175)
 
 A Python library for Difference-in-Differences (DiD) causal inference analysis with an sklearn-like API and statsmodels-style outputs.
 
@@ -144,6 +145,38 @@ Measuring campaign lift? Evaluating a product launch? diff-diff handles the caus
 - **[Brand awareness survey tutorial](docs/tutorials/17_brand_awareness_survey.ipynb)** - Full example with complex survey design, brand funnel analysis, and staggered rollouts
 - **Have BRFSS/ACS/CPS individual records?** Use [`aggregate_survey()`](docs/api/prep.rst) to roll respondent-level microdata into a geographic-period panel with inverse-variance precision weights. The returned second-stage design uses analytic weights (`aweight`), so it works directly with `DifferenceInDifferences`, `TwoWayFixedEffects`, `MultiPeriodDiD`, `SunAbraham`, `ContinuousDiD`, and `EfficientDiD` (estimators marked **Full** in the [survey support matrix](docs/choosing_estimator.rst))
 
+### Experimental preview: `BusinessReport` and `DiagnosticReport`
+
+diff-diff ships two preview classes, `BusinessReport` and `DiagnosticReport`, that produce plain-English output and a structured `to_dict()` schema from any fitted result. **Both are experimental in this release** — wording, verdict thresholds, and schema shape will change as the library learns from real practitioner usage. Do not anchor downstream tooling on the schema yet; the experimental flag is noted in the CHANGELOG.
+
+```python
+from diff_diff import CallawaySantAnna, BusinessReport
+
+cs = CallawaySantAnna(base_period="universal").fit(
+    df, outcome="revenue", unit="store", time="month",
+    first_treat="first_treat", aggregate="event_study",
+)
+report = BusinessReport(
+    cs,
+    outcome_label="Revenue per store",
+    outcome_unit="$",
+    business_question="Did the loyalty program lift revenue?",
+    treatment_label="the loyalty program",
+    # Optional: pass the panel + column names so the auto-constructed
+    # DiagnosticReport can run data-dependent checks (2x2 pre-trends,
+    # Goodman-Bacon decomposition, EfficientDiD Hausman pretest).
+    # Without these the auto path still runs but skips those checks.
+    data=df,
+    outcome="revenue",
+    unit="store",
+    time="month",
+    first_treat="first_treat",
+)
+print(report.summary())
+```
+
+`BusinessReport` auto-constructs a `DiagnosticReport` so the summary mentions pre-trends, sensitivity, and design-effect findings in one call. Methodology (phrasing rules, verdict thresholds, schema stability) is documented in [docs/methodology/REPORTING.md](docs/methodology/REPORTING.md). Feedback on wording, applicability, and missing diagnostics is welcome — this is the part of the library most likely to evolve in the next few releases.
+
 Already know DiD? The [academic quickstart](docs/quickstart.rst) and [estimator guide](docs/choosing_estimator.rst) cover the full technical details.
 
 ## Features
@@ -3119,14 +3152,20 @@ If you use diff-diff in your research, please cite it:
 ```bibtex
 @software{diff_diff,
   title = {diff-diff: Difference-in-Differences Causal Inference for Python},
-  author = {{diff-diff contributors}},
+  author = {Gerber, Isaac},
+  year = {2026},
   url = {https://github.com/igerber/diff-diff},
+  doi = {10.5281/zenodo.19646175},
   license = {MIT},
 }
 ```
 
+The DOI above is the Zenodo concept DOI — it always resolves to the latest release. To cite a specific version, look up its versioned DOI on [the Zenodo project page](https://doi.org/10.5281/zenodo.19646175).
+
 See [`CITATION.cff`](CITATION.cff) for the full citation metadata.
 
+**Note on authorship**: academic citation (`CITATION.cff`, the BibTeX above) lists individual authors with ORCIDs per scholarly convention. Package metadata surfaces (`pyproject.toml`, Sphinx docs) list "diff-diff contributors" to acknowledge the collective — see [`CONTRIBUTORS.md`](CONTRIBUTORS.md) for the full list.
+
 ## License
 
 MIT License

{diff_diff-3.1.3 → diff_diff-3.3.0}/README.md

@@ -5,6 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Downloads](https://img.shields.io/pypi/dm/diff-diff.svg)](https://pypi.org/project/diff-diff/)
 [![Documentation](https://readthedocs.org/projects/diff-diff/badge/?version=stable)](https://diff-diff.readthedocs.io/en/stable/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19646175.svg)](https://doi.org/10.5281/zenodo.19646175)
 
 A Python library for Difference-in-Differences (DiD) causal inference analysis with an sklearn-like API and statsmodels-style outputs.
 
@@ -92,6 +93,38 @@ Measuring campaign lift? Evaluating a product launch? diff-diff handles the caus
 - **[Brand awareness survey tutorial](docs/tutorials/17_brand_awareness_survey.ipynb)** - Full example with complex survey design, brand funnel analysis, and staggered rollouts
 - **Have BRFSS/ACS/CPS individual records?** Use [`aggregate_survey()`](docs/api/prep.rst) to roll respondent-level microdata into a geographic-period panel with inverse-variance precision weights. The returned second-stage design uses analytic weights (`aweight`), so it works directly with `DifferenceInDifferences`, `TwoWayFixedEffects`, `MultiPeriodDiD`, `SunAbraham`, `ContinuousDiD`, and `EfficientDiD` (estimators marked **Full** in the [survey support matrix](docs/choosing_estimator.rst))
 
+### Experimental preview: `BusinessReport` and `DiagnosticReport`
+
+diff-diff ships two preview classes, `BusinessReport` and `DiagnosticReport`, that produce plain-English output and a structured `to_dict()` schema from any fitted result. **Both are experimental in this release** — wording, verdict thresholds, and schema shape will change as the library learns from real practitioner usage. Do not anchor downstream tooling on the schema yet; the experimental flag is noted in the CHANGELOG.
+
+```python
+from diff_diff import CallawaySantAnna, BusinessReport
+
+cs = CallawaySantAnna(base_period="universal").fit(
+    df, outcome="revenue", unit="store", time="month",
+    first_treat="first_treat", aggregate="event_study",
+)
+report = BusinessReport(
+    cs,
+    outcome_label="Revenue per store",
+    outcome_unit="$",
+    business_question="Did the loyalty program lift revenue?",
+    treatment_label="the loyalty program",
+    # Optional: pass the panel + column names so the auto-constructed
+    # DiagnosticReport can run data-dependent checks (2x2 pre-trends,
+    # Goodman-Bacon decomposition, EfficientDiD Hausman pretest).
+    # Without these the auto path still runs but skips those checks.
+    data=df,
+    outcome="revenue",
+    unit="store",
+    time="month",
+    first_treat="first_treat",
+)
+print(report.summary())
+```
+
+`BusinessReport` auto-constructs a `DiagnosticReport` so the summary mentions pre-trends, sensitivity, and design-effect findings in one call. Methodology (phrasing rules, verdict thresholds, schema stability) is documented in [docs/methodology/REPORTING.md](docs/methodology/REPORTING.md). Feedback on wording, applicability, and missing diagnostics is welcome — this is the part of the library most likely to evolve in the next few releases.
+
 Already know DiD? The [academic quickstart](docs/quickstart.rst) and [estimator guide](docs/choosing_estimator.rst) cover the full technical details.
 
 ## Features
@@ -3067,14 +3100,20 @@ If you use diff-diff in your research, please cite it:
 ```bibtex
 @software{diff_diff,
   title = {diff-diff: Difference-in-Differences Causal Inference for Python},
-  author = {{diff-diff contributors}},
+  author = {Gerber, Isaac},
+  year = {2026},
   url = {https://github.com/igerber/diff-diff},
+  doi = {10.5281/zenodo.19646175},
   license = {MIT},
 }
 ```
 
+The DOI above is the Zenodo concept DOI — it always resolves to the latest release. To cite a specific version, look up its versioned DOI on [the Zenodo project page](https://doi.org/10.5281/zenodo.19646175).
+
 See [`CITATION.cff`](CITATION.cff) for the full citation metadata.
 
+**Note on authorship**: academic citation (`CITATION.cff`, the BibTeX above) lists individual authors with ORCIDs per scholarly convention. Package metadata surfaces (`pyproject.toml`, Sphinx docs) list "diff-diff contributors" to acknowledge the collective — see [`CONTRIBUTORS.md`](CONTRIBUTORS.md) for the full list.
+
 ## License
 
 MIT License

{diff_diff-3.1.3 → diff_diff-3.3.0}/diff_diff/__init__.py

@@ -4,14 +4,20 @@ diff-diff: A library for Difference-in-Differences analysis.
 This library provides sklearn-like estimators for causal inference
 using the difference-in-differences methodology.
 
-For rigorous analysis, follow the 8-step practitioner workflow based
-on Baker et al. (2025). After estimation, call
-``practitioner_next_steps(results)`` for context-aware guidance on
-remaining diagnostic steps.
+For AI agents:
 
-AI agents: call ``diff_diff.get_llm_guide()`` for a complete API reference.
-Use ``get_llm_guide("practitioner")`` for the 8-step workflow or
-``get_llm_guide("full")`` for comprehensive documentation.
+    1. Describe your data:    ``diff_diff.profile_panel(df, unit=..., time=...,
+                              treatment=..., outcome=...)``
+    2. Consult the reference: ``diff_diff.get_llm_guide("autonomous")``
+                              (estimator-support matrix + reasoning)
+    3. Follow the workflow:   ``diff_diff.get_llm_guide("practitioner")``
+                              (Baker et al. (2025) 8-step recipe)
+    4. Report results:        ``diff_diff.BusinessReport(results)``
+                              (structured agent-legible output)
+
+For a comprehensive API reference call ``diff_diff.get_llm_guide("full")``;
+``practitioner_next_steps(results)`` returns context-aware guidance after
+any estimator's ``fit()``.
 """
 
 # Import backend detection from dedicated module (avoids circular imports)
@@ -21,7 +27,6 @@ from diff_diff._backend import (
     _rust_compute_robust_vcov,
     _rust_project_simplex,
     _rust_solve_ols,
-    _rust_synthetic_weights,
 )
 
 from diff_diff.bacon import (
@@ -43,6 +48,38 @@ from diff_diff.linalg import (
     InferenceResult,
     LinearRegression,
 )
+from diff_diff.local_linear import (
+    KERNELS,
+    BandwidthResult,
+    BiasCorrectedFit,
+    LocalLinearFit,
+    bias_corrected_local_linear,
+    epanechnikov_kernel,
+    kernel_moments,
+    local_linear_fit,
+    mse_optimal_bandwidth,
+    triangular_kernel,
+    uniform_kernel,
+)
+from diff_diff.had import (
+    HeterogeneousAdoptionDiD,
+    HeterogeneousAdoptionDiDEventStudyResults,
+    HeterogeneousAdoptionDiDResults,
+)
+from diff_diff.had_pretests import (
+    HADPretestReport,
+    QUGTestResults,
+    StuteJointResult,
+    StuteTestResults,
+    YatchewTestResults,
+    did_had_pretest_workflow,
+    joint_homogeneity_test,
+    joint_pretrends_test,
+    qug_test,
+    stute_joint_pretest,
+    stute_test,
+    yatchew_hr_test,
+)
 from diff_diff.estimators import (
     DifferenceInDifferences,
     MultiPeriodDiD,
@@ -202,7 +239,18 @@ from diff_diff.visualization import (
     plot_synth_weights,
 )
 from diff_diff.practitioner import practitioner_next_steps
+from diff_diff.business_report import (
+    BUSINESS_REPORT_SCHEMA_VERSION,
+    BusinessContext,
+    BusinessReport,
+)
+from diff_diff.diagnostic_report import (
+    DIAGNOSTIC_REPORT_SCHEMA_VERSION,
+    DiagnosticReport,
+    DiagnosticReportResults,
+)
 from diff_diff._guides_api import get_llm_guide
+from diff_diff.profile import Alert, PanelProfile, profile_panel
 from diff_diff.datasets import (
     clear_cache,
     list_datasets,
@@ -230,8 +278,9 @@ Bacon = BaconDecomposition
 EDiD = EfficientDiD
 ETWFE = WooldridgeDiD
 DCDH = ChaisemartinDHaultfoeuille
+HAD = HeterogeneousAdoptionDiD
 
-__version__ = "3.1.3"
+__version__ = "3.3.0"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -395,6 +444,40 @@ __all__ = [
     # Linear algebra helpers
     "LinearRegression",
     "InferenceResult",
+    # Local-linear regression infrastructure (Phase 1a for HeterogeneousAdoptionDiD)
+    "KERNELS",
+    "LocalLinearFit",
+    "epanechnikov_kernel",
+    "kernel_moments",
+    "local_linear_fit",
+    "triangular_kernel",
+    "uniform_kernel",
+    # MSE-optimal bandwidth selector (Phase 1b for HeterogeneousAdoptionDiD)
+    "BandwidthResult",
+    "mse_optimal_bandwidth",
+    # Bias-corrected local-linear (Phase 1c for HeterogeneousAdoptionDiD)
+    "BiasCorrectedFit",
+    "bias_corrected_local_linear",
+    # HeterogeneousAdoptionDiD (Phase 2a single-period, Phase 2b event study)
+    "HeterogeneousAdoptionDiD",
+    "HeterogeneousAdoptionDiDResults",
+    "HeterogeneousAdoptionDiDEventStudyResults",
+    "HAD",
+    # HeterogeneousAdoptionDiD pre-test diagnostics (Phase 3)
+    "qug_test",
+    "stute_test",
+    "yatchew_hr_test",
+    "did_had_pretest_workflow",
+    "QUGTestResults",
+    "StuteTestResults",
+    "YatchewTestResults",
+    "HADPretestReport",
+    # HAD joint pre-tests (Phase 3 follow-up) — multi-period event-study
+    # workflow dispatch via did_had_pretest_workflow(aggregate="event_study")
+    "stute_joint_pretest",
+    "joint_pretrends_test",
+    "joint_homogeneity_test",
+    "StuteJointResult",
     # Datasets
     "load_card_krueger",
     "load_castle_doctrine",
@@ -405,6 +488,16 @@ __all__ = [
     "clear_cache",
     # Practitioner guidance
     "practitioner_next_steps",
+    "BusinessReport",
+    "BusinessContext",
+    "BUSINESS_REPORT_SCHEMA_VERSION",
+    "DiagnosticReport",
+    "DiagnosticReportResults",
+    "DIAGNOSTIC_REPORT_SCHEMA_VERSION",
+    # Panel profiling (agent-facing pre-fit describe utility)
+    "profile_panel",
+    "PanelProfile",
+    "Alert",
     # LLM guide accessor
     "get_llm_guide",
 ]

{diff_diff-3.1.3 → diff_diff-3.3.0}/diff_diff/_backend.py

@@ -19,7 +19,6 @@ _backend_env = os.environ.get("DIFF_DIFF_BACKEND", "auto").lower()
 try:
     from diff_diff._rust_backend import (
         generate_bootstrap_weights_batch as _rust_bootstrap_weights,
-        compute_synthetic_weights as _rust_synthetic_weights,
         project_simplex as _rust_project_simplex,
         solve_ols as _rust_solve_ols,
         compute_robust_vcov as _rust_compute_robust_vcov,
@@ -35,6 +34,9 @@ try:
         compute_time_weights as _rust_compute_time_weights,
         compute_noise_level as _rust_compute_noise_level,
         sc_weight_fw as _rust_sc_weight_fw,
+        sc_weight_fw_with_convergence as _rust_sc_weight_fw_with_convergence,
+        sc_weight_fw_weighted as _rust_sc_weight_fw_weighted,
+        sc_weight_fw_weighted_with_convergence as _rust_sc_weight_fw_weighted_with_convergence,
         # Diagnostics
         rust_backend_info as _rust_backend_info,
     )
@@ -43,7 +45,6 @@ try:
 except ImportError:
     _rust_available = False
     _rust_bootstrap_weights = None
-    _rust_synthetic_weights = None
     _rust_project_simplex = None
     _rust_solve_ols = None
     _rust_compute_robust_vcov = None
@@ -59,6 +60,9 @@ except ImportError:
     _rust_compute_time_weights = None
     _rust_compute_noise_level = None
     _rust_sc_weight_fw = None
+    _rust_sc_weight_fw_with_convergence = None
+    _rust_sc_weight_fw_weighted = None
+    _rust_sc_weight_fw_weighted_with_convergence = None
     _rust_backend_info = None
 
 # Determine final backend based on environment variable and availability
@@ -66,7 +70,6 @@ if _backend_env == "python":
     # Force pure Python mode - disable Rust even if available
     HAS_RUST_BACKEND = False
     _rust_bootstrap_weights = None
-    _rust_synthetic_weights = None
     _rust_project_simplex = None
     _rust_solve_ols = None
     _rust_compute_robust_vcov = None
@@ -82,6 +85,9 @@ if _backend_env == "python":
     _rust_compute_time_weights = None
     _rust_compute_noise_level = None
     _rust_sc_weight_fw = None
+    _rust_sc_weight_fw_with_convergence = None
+    _rust_sc_weight_fw_weighted = None
+    _rust_sc_weight_fw_weighted_with_convergence = None
     _rust_backend_info = None
 elif _backend_env == "rust":
     # Force Rust mode - fail if not available
@@ -115,7 +121,6 @@ __all__ = [
     "HAS_RUST_BACKEND",
     "rust_backend_info",
     "_rust_bootstrap_weights",
-    "_rust_synthetic_weights",
     "_rust_project_simplex",
     "_rust_solve_ols",
     "_rust_compute_robust_vcov",
@@ -131,4 +136,7 @@ __all__ = [
     "_rust_compute_time_weights",
     "_rust_compute_noise_level",
     "_rust_sc_weight_fw",
+    "_rust_sc_weight_fw_with_convergence",
+    "_rust_sc_weight_fw_weighted",
+    "_rust_sc_weight_fw_weighted_with_convergence",
 ]

{diff_diff-3.1.3 → diff_diff-3.3.0}/diff_diff/_guides_api.py

@@ -1,4 +1,5 @@
 """Runtime accessor for bundled LLM guide files."""
+
 from __future__ import annotations
 
 from importlib.resources import files
@@ -7,6 +8,7 @@ _VARIANT_TO_FILE = {
     "concise": "llms.txt",
     "full": "llms-full.txt",
     "practitioner": "llms-practitioner.txt",
+    "autonomous": "llms-autonomous.txt",
 }
 
 
@@ -21,6 +23,10 @@ def get_llm_guide(variant: str = "concise") -> str:
         - ``"concise"`` -- compact API reference (llms.txt)
         - ``"full"`` -- complete API documentation (llms-full.txt)
         - ``"practitioner"`` -- 8-step practitioner workflow (llms-practitioner.txt)
+        - ``"autonomous"`` -- reference guide for AI-agent use: estimator-support
+          matrix, per-design-feature reasoning, post-fit validation index, and
+          BR/DR schema (llms-autonomous.txt). Pair with
+          :func:`diff_diff.profile_panel` for pre-fit data description.
 
     Returns
     -------
@@ -42,7 +48,5 @@ def get_llm_guide(variant: str = "concise") -> str:
         filename = _VARIANT_TO_FILE[variant]
     except (KeyError, TypeError):
         valid = ", ".join(repr(k) for k in _VARIANT_TO_FILE)
-        raise ValueError(
-            f"Unknown guide variant {variant!r}. Valid options: {valid}."
-        ) from None
+        raise ValueError(f"Unknown guide variant {variant!r}. Valid options: {valid}.") from None
     return files("diff_diff.guides").joinpath(filename).read_text(encoding="utf-8")