Basic Usage#

Source: examples/basic_usage.py

Introduction#

Construct the smallest useful Study using only top-level drex exports.

Technical Implementation#

  1. Define one manipulated factor with two levels.

  2. Register one primary outcome plus one hypothesis and analysis plan.

  3. Print study.to_dict() so the serialized schema is visible in one place.

  4. Show that a study with no execution yet has no durable run-evidence records.

 1from __future__ import annotations
 2
 3import design_research_experiments as drex
 4
 5
 6def main() -> None:
 7    """Construct and print a tiny study definition."""
 8    study = drex.Study(
 9        study_id="example-study",
10        title="Example Study",
11        description="Minimal study object for notebook/script usage.",
12        factors=(
13            drex.Factor(
14                name="prompt_frame",
15                description="Prompt framing",
16                kind=drex.FactorKind.MANIPULATED,
17                levels=(
18                    drex.Level(name="neutral", value="neutral"),
19                    drex.Level(name="challenge", value="challenge"),
20                ),
21            ),
22        ),
23        outcomes=(
24            drex.OutcomeSpec(
25                name="primary_outcome",
26                source_table="runs",
27                column="primary_outcome",
28                aggregation="mean",
29                primary=True,
30            ),
31        ),
32        hypotheses=(
33            drex.Hypothesis(
34                hypothesis_id="h1",
35                label="Prompt framing effect",
36                statement="Prompt frame influences the primary outcome.",
37                independent_vars=("prompt_frame",),
38                dependent_vars=("primary_outcome",),
39            ),
40        ),
41        analysis_plans=(
42            drex.AnalysisPlan(analysis_plan_id="ap1", hypothesis_ids=("h1",), tests=("ttest",)),
43        ),
44        design_spec=drex.DesignSpec(kind=drex.DesignKind.FULL_FACTORIAL),
45        problem_ids=("problem-1",),
46    )
47
48    print(study.to_dict())
49    print(drex.load_run_evidence_records(study.output_dir or "artifacts/example-study"))
50
51
52if __name__ == "__main__":
53    main()

Expected Results#

Run Command

PYTHONPATH=src python examples/basic_usage.py

The script prints the study dictionary followed by an empty evidence-record mapping. Executed studies populate that mapping under artifacts/runs/.