Reproducibility and Quality

再現性と品質管理

環境を固定する

Python の通常実行は Docker + uv に統一します。依存を変更するときはコンテナ内で操作し、lockfile を更新します。

docker compose exec research-template uv add <package>
docker compose exec research-template uv remove <package>
docker compose exec research-template uv run pytest

pyproject.toml と uv.lock はセットでコミットします。ホストの Python や個人の .venv だけで動く状態を正解にしません。

入力を早く検証する

共有コードでは、必要な入力を暗黙の既定値で補わず明示的に失敗させます。

assert "subject_id" in data, f"Expected subject_id. Got: {list(data.keys())}"
assert data["subject_id"].is_unique, "subject_id must be unique"

列の存在だけでなく、型、単位、許容範囲、欠損率、時刻順序、ID の一意性も研究上の仮定として検証します。

乱数とパラメータを追跡する

• 共有シードは config.py、実験固有値は params.py に置く。
• 図中や README に手入力した数値を正典にしない。
• コマンドライン引数や環境変数を使う場合、実行時の値をログへ出す。
• 非決定的な GPU 演算など、完全再現できない要因を記録する。

テストの粒度

• src/utils/: 小さな純粋関数、パス、I/O の境界
• src/models/: パース、型、異常入力
• src/methods/: 既知の小さな例、数値許容誤差、統計的性質
• src/analysis/: 小さい fixture を使った統合テスト
• scripts/ / exp/: 最小入力での smoke test または実行確認

通常の確認:

docker compose exec research-template uv run pytest

結果を追跡可能にする

成果物ごとに、少なくとも次をたどれるようにします。

図・表 → 生成スクリプト／実験 → パラメータ → 入力データ版 → Git commit

論文用成果物を result/ に昇格するときは、このつながりを実験 README や研究ログに記載します。

マイルストーンでの再現確認

投稿、プレプリント、リリースの前には、クリーンな checkout または別マシンで次を確認します。

1. .env.example から環境を準備できる。
2. docker compose up -d と uv sync が成功する。
3. テストが通る。
4. raw から主要な processed data と図表を生成できる。
5. LuaLaTeX で原稿をコンパイルできる。
6. README のコマンドが現状と一致する。

再現確認に使った commit をタグまたは Release で固定すると、投稿版との対応が明確になります。