Paper Contributions#

Source: examples/paper_contributions.py

Introduction#

Wrap an existing analysis result in a portable record that distinguishes executed evidence from planned methods and produces restrained Methods and Results support.

Technical Implementation#

  1. Fit a deterministic ordinary least-squares regression.

  2. Record the hypothesis, included runs, documented exclusion, and diagnostic checks.

  3. Write and reload the result beneath the study artifact directory.

  4. Collect a JSON-compatible packet for downstream paper-draft assembly.

 1from __future__ import annotations
 2
 3from pathlib import Path
 4from tempfile import TemporaryDirectory
 5
 6import design_research_analysis as dran
 7
 8
 9def main() -> None:
10    """Build, persist, reload, and translate one analysis result."""
11    regression = dran.fit_regression(
12        [[0.0], [1.0], [2.0], [3.0]],
13        [1.0, 1.5, 2.0, 2.5],
14        feature_names=["iteration"],
15    )
16    record = dran.build_analysis_result(
17        regression,
18        analysis_id="h1-iteration-regression",
19        status=dran.AnalysisStatus.COMPLETE,
20        analysis_plan_ids=("plan-h1",),
21        hypothesis_ids=("H1",),
22        candidate_run_ids=("run-1", "run-2", "run-3", "run-4"),
23        included_run_ids=("run-1", "run-2", "run-3"),
24        exclusions=(
25            dran.AnalysisExclusion(
26                run_id="run-4",
27                reason="The prespecified evaluator output was missing.",
28            ),
29        ),
30        assumptions=(
31            dran.AnalysisCheck(
32                check_id="linearity",
33                status="passed",
34                detail="The deterministic fixture is exactly linear.",
35            ),
36        ),
37        evidence_refs=(
38            "artifacts/runs/run-1/run.json",
39            "artifacts/runs/run-2/run.json",
40            "artifacts/runs/run-3/run.json",
41        ),
42        source_api="fit_regression",
43    )
44
45    with TemporaryDirectory() as temporary_dir:
46        result_path = dran.write_analysis_result(
47            record,
48            output_dir=Path(temporary_dir),
49        )
50        reloaded = dran.load_analysis_result(result_path)
51        assert isinstance(reloaded, dran.AnalysisResultRecord)
52        packet = dran.collect_analysis_paper_contributions(reloaded)
53
54    assert reloaded.status is dran.AnalysisStatus.COMPLETE
55    assert reloaded.analysis_result_version == dran.ANALYSIS_RESULT_VERSION
56    assert packet["schema_version"] == dran.PAPER_CONTRIBUTION_VERSION
57    print("Analysis result contract:", dran.ANALYSIS_RESULT_VERSION)
58    print("Paper contribution contract:", dran.PAPER_CONTRIBUTION_VERSION)
59    print("Reloaded analysis:", reloaded.analysis_id)
60    print(
61        "Contributions:",
62        ", ".join(item["contribution_id"] for item in packet["contributions"]),
63    )
64    print(
65        "Reporting gaps:",
66        ", ".join(item["gap_id"] for item in packet["reporting_gaps"]),
67    )
68
69
70if __name__ == "__main__":
71    main()

Expected Results#

Run Command

PYTHONPATH=src python examples/paper_contributions.py

Prints the two contract versions, the reloaded analysis identity, and the generated contribution and reporting-gap identifiers. The gap makes the missing coefficient uncertainty visible instead of implying a significance test.

References#

  • docs/paper_contributions.rst