Skip to content

Commit 7502676

Browse files
igerberclaude
andcommitted
Tighten README: frame BR/DR as experimental preview
Replace the "Stakeholder-ready report from any fit" subsection framing with "Experimental preview: BusinessReport and DiagnosticReport" and reword the introductory paragraph to emphasize that wording, verdict thresholds, and schema shape will change. Drop the expected-output comment from the example (the prose will evolve) and invite feedback. This matches the foundation-not-shipped-feature posture: the schema and narrative prototype are worth validating in isolation, but the library still lacks several items a methodologically-rigorous practitioner (covariate comparison, event-study plot embedding, 2x2 placebo battery, real-dataset validation, target-parameter clarity, tutorial integration) would expect. Keeping external framing conservative until those gaps close. No functional changes; only README prose. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 3212187 commit 7502676

1 file changed

Lines changed: 3 additions & 9 deletions

File tree

README.md

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -92,9 +92,9 @@ Measuring campaign lift? Evaluating a product launch? diff-diff handles the caus
9292
- **[Brand awareness survey tutorial](docs/tutorials/17_brand_awareness_survey.ipynb)** - Full example with complex survey design, brand funnel analysis, and staggered rollouts
9393
- **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))
9494

95-
### Stakeholder-ready report from any fit
95+
### Experimental preview: `BusinessReport` and `DiagnosticReport`
9696

97-
Wrap any fitted result in `BusinessReport` for a plain-English stakeholder summary; pair with `DiagnosticReport` for a validity check:
97+
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.
9898

9999
```python
100100
from diff_diff import CallawaySantAnna, BusinessReport
@@ -111,15 +111,9 @@ report = BusinessReport(
111111
treatment_label="the loyalty program",
112112
)
113113
print(report.summary())
114-
# "The loyalty program increased Revenue per store by $1.78 (95% CI: $1.56 to $2.00).
115-
# Statistically, the direction of the effect is strongly supported by the data.
116-
# Pre-treatment data do not reject parallel trends, but the test has limited
117-
# power — a non-rejection does not prove the assumption. See the sensitivity
118-
# analysis below for a more reliable signal.
119-
# Sample: 600 observations (70 treated, 30 control)."
120114
```
121115

122-
`BusinessReport` auto-constructs a `DiagnosticReport` by default so the summary mentions pre-trends, robustness, and design-effect findings in one call. `.to_dict()` returns the same content as a stable AI-legible schema (single source of truth; prose is rendered from the dict). See [docs/methodology/REPORTING.md](docs/methodology/REPORTING.md) for the phrasing rules, verdict thresholds, and schema stability policy. **Schema is experimental in this release.**
116+
`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.
123117

124118
Already know DiD? The [academic quickstart](docs/quickstart.rst) and [estimator guide](docs/choosing_estimator.rst) cover the full technical details.
125119

0 commit comments

Comments
 (0)