Research Workflow

研究ワークフロー

このテンプレートでは、研究の進行を「問い → データ → 方法 → 実験 → 結果 → 原稿」の追跡可能な流れとして残します。

1. 問いと判断基準を先に固定する

解析を始める前に、少なくとも次を README.md または docs/ に書きます。

• 研究質問と仮説
• 主要アウトカム、説明変数、比較対象
• 採用／棄却を判断する指標
• 対象範囲と除外基準
• 想定する感度分析、null model、頑健性確認
• データ利用条件、倫理、公開可能範囲

途中で方針を変えた場合は、過去を消さず docs/templates/decision-record.md を使って理由を残します。

2. データを受け入れる

1. 入手元、取得日、版、ライセンス、チェックサムを記録する。
2. 元データを data/raw/ または Git 外の DATA_ROOT に置く。
3. 生データは編集せず、整形処理をスクリプト化する。
4. 入力列、単位、欠損、範囲、ID の一意性を早い段階で検証する。

人を対象とするデータ、位置情報、未公開共同研究データなどは、公開リポジトリの data/ に置いてはいけません。詳細は データ管理 を参照してください。

3. 探索から再利用コードへ移す

探索中の小さな試行は notebook でも構いません。方法が固まったら次のように整理します。

• 一般的な I/O、検証、乱数、描画: src/utils/
• データモデル、ローダ、パーサ: src/models/
• 統計手法、アルゴリズム、モデル: src/methods/
• 複数処理を組み合わせた解析: src/analysis/
• コマンドとしての実行入口: scripts/

同じ処理を 2 回目に使う時点を、src/ へ昇格する目安にします。

4. 番号付き実験を回す

実験ごとに仮説、条件、コード、結果の記録を自己完結させます。

cp -r exp/_template exp/001_baseline_fit
docker compose exec research-template uv run python exp/001_baseline_fit/run.py

出力は exp/001_baseline_fit/out/、知見は同ディレクトリの README.md に残します。条件変更は過去の実験を書き換えず、新しい番号で行います。

5. 結果を確定する

• 主要解析と感度分析を分ける
• 図表の元データと生成コードを特定できるようにする
• 乱数シード、パラメータ、使用データ版、実行コマンドを記録する
• 採用する図表をコードで result/figures/ と result/tables/ に生成する
• 想定外の結果や失敗も実験 README に残す

6. 原稿へ接続する

Methods は実際のコードとパラメータから、Results は確定した生成物から書きます。図を画像編集ソフトで手直しした場合は、その変更をコードへ戻すか、再現できない変更として明記します。

参考文献、補足資料、図表番号を確認し、最終的に別環境でもテスト、主要解析、原稿コンパイルが再実行できる状態を目指します。

日々の短いサイクル

1. 今日検証する問いを 1 つ決める。
2. 新しい実験番号と条件を作る。
3. 実行し、出力と失敗を確認する。
4. 実験 README に結果と次の判断を書く。
5. 再利用価値のある処理を src/ とテストへ移す。
6. 小さな単位でブランチにコミットし、PR で main へ統合する。