Public API Walkthrough#

Source: examples/public_api_walkthrough.py

Introduction#

Walk through the core study lifecycle: build, validate, and materialize conditions.

Technical Implementation#

  1. Build a compact Study object with one factor, hypothesis, and outcome.

  2. Validate via drex.validate_study.

  3. Materialize conditions through both drex.build_design and drex.materialize_conditions for parity checks.

 1from __future__ import annotations
 2
 3from pathlib import Path
 4
 5import design_research_experiments as drex
 6
 7
 8def build_demo_study(output_dir: Path) -> drex.Study:
 9    """Build a small study covering the core schema objects."""
10    return drex.Study(
11        study_id="demo-study",
12        title="Demo Study",
13        description="A tiny study used for local API walkthrough.",
14        factors=(
15            drex.Factor(
16                name="prompt_frame",
17                description="Prompt framing style",
18                levels=(
19                    drex.Level(name="neutral", value="neutral"),
20                    drex.Level(name="challenge", value="challenge"),
21                ),
22            ),
23        ),
24        hypotheses=(
25            drex.Hypothesis(
26                hypothesis_id="h1",
27                label="Prompt Effect",
28                statement="Prompt frame changes primary outcome.",
29                independent_vars=("prompt_frame",),
30                dependent_vars=("primary_outcome",),
31            ),
32        ),
33        outcomes=(
34            drex.OutcomeSpec(
35                name="primary_outcome",
36                source_table="runs",
37                column="primary_outcome",
38                aggregation="mean",
39                primary=True,
40            ),
41        ),
42        analysis_plans=(drex.AnalysisPlan("ap1", ("h1",), ("ttest",)),),
43        output_dir=output_dir,
44        problem_ids=("problem-1",),
45        agent_specs=("agent-a",),
46    )
47
48
49def main() -> None:
50    """Validate and materialize the demo study."""
51    print(f"design-research-experiments {drex.__version__}")
52    output_dir = Path("artifacts") / "demo-study"
53    study = build_demo_study(output_dir)
54    packet = drex.resolve_problem(
55        {
56            "problem_id": "problem-1",
57            "family": "walkthrough",
58            "brief": "A locally defined problem packet for the walkthrough.",
59        }
60    )
61    print(f"Resolved problem packet: {packet.problem_id}")
62
63    errors = drex.validate_study(study)
64    if errors:
65        raise RuntimeError("\n".join(errors))
66
67    conditions = drex.build_design(study)
68    print(f"build_design produced {len(conditions)} conditions")
69
70    direct_conditions = drex.materialize_conditions(study)
71    print(f"materialize_conditions produced {len(direct_conditions)} conditions")
72
73
74if __name__ == "__main__":
75    main()

Expected Results#

Run Command

PYTHONPATH=src python examples/public_api_walkthrough.py

The script prints condition counts for both materialization paths and raises an error only when validation fails.