Declare, simulate, diagnose

A small Python implementation of the DeclareDesign workflow

declaredesign makes the assumptions and operating characteristics of a research design executable before data collection. It combines four tasks that are often split across unrelated libraries:

  1. fabricate a finite population and its potential outcomes;
  2. draw a sample and treatment assignment from known designs;
  3. reveal measured outcomes and run design-appropriate estimators;
  4. repeat the complete design to diagnose bias, precision, power, and coverage.

The API is modeled on the R packages randomizr, fabricatr, estimatr, and DeclareDesign. The Python implementation uses NumPy/SciPy arrays and random generators, Polars data frames, and Altair charts. Regression formulas, fixed effects, instrumental variables, and covariance estimators are delegated to PyFixest and Formulaic.

A complete declaration

import declaredesign as dd

design = dd.declare_design(
    dd.declare_population(
        400,
        X=lambda data, rng: rng.normal(size=data.height),
        U=lambda data, rng: rng.normal(size=data.height),
    ),
    dd.declare_potential_outcomes(
        outcome="Y",
        assignment="Z",
        conditions=[0, 1],
        model=lambda data, z: data["X"].to_numpy() + data["U"].to_numpy() + z,
    ),
    dd.declare_inquiry(
        "ATE", lambda data: (data["Y_Z_1"] - data["Y_Z_0"]).mean()
    ),
    dd.declare_assignment(name="Z", m=200),
    dd.declare_measurement(outcome="Y", assignment="Z"),
    dd.declare_estimator("Y ~ Z", inquiry="ATE"),
)

diagnosis = dd.diagnose_design(design, sims=500, seed=2026)

Each step has one role, so a change to the population, assignment mechanism, measurement process, or estimator is visible in the declaration rather than buried in a simulation loop.

NoteCurrent scope

This is a tested prototype of the core workflow, not a drop-in replacement for every R feature. It covers common complete, simple, blocked, clustered, and blocked-clustered designs; sequential and hierarchical fabrication; potential outcomes and reveal; robust OLS, Lin adjustment, difference-in-means, Horvitz–Thompson, and IV; and simulation-based diagnosis. The R packages remain authoritative for features such as arbitrary quosure evaluation, estimatr’s CR2 covariance, full joint assignment matrices, fan-out designs, and bootstrap diagnosand uncertainty.