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                linked_analysis_plan_id="ap1",
32            ),
33        ),
34        outcomes=(
35            drex.OutcomeSpec(
36                name="primary_outcome",
37                source_table="runs",
38                column="primary_outcome",
39                aggregation="mean",
40                primary=True,
41            ),
42        ),
43        analysis_plans=(drex.AnalysisPlan("ap1", ("h1",), ("ttest",)),),
44        output_dir=output_dir,
45        problem_ids=("problem-1",),
46        agent_specs=("agent-a",),
47        primary_outcomes=("primary_outcome",),
48    )
49
50
51def main() -> None:
52    """Validate and materialize the demo study."""
53    output_dir = Path("artifacts") / "demo-study"
54    study = build_demo_study(output_dir)
55
56    errors = drex.validate_study(study)
57    if errors:
58        raise RuntimeError("\n".join(errors))
59
60    conditions = drex.build_design(study)
61    print(f"build_design produced {len(conditions)} conditions")
62
63    direct_conditions = drex.materialize_conditions(study)
64    print(f"materialize_conditions produced {len(direct_conditions)} conditions")
65
66
67if __name__ == "__main__":
68    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.