見出し画像
Photo by coooooom7

解析研究の記録はどう残す？スクリプト管理で再現性を向上

Ozk

研究の記録は、研究者にとって欠かせないものです。実験研究では、研究ノートに日付・目的・プロトコール・結果などを記録するのが一般的ですが、解析研究（バイオインフォマティクス解析など）ではどのように記録を残せば良いのでしょうか？

実験研究が中心の科学者や学生が解析を始める際、多くの場合、書籍やウェブの記事を参考にしながら、コマンドを入力し、解析結果を得ることはできると思います。しかし、その過程や結果をどう記録すればよいのか という点で悩むことが少なくありません。

例えば、ある日、BLAST を使って相同性検索を行ったとします。

blastp -query data.fasta -evalue 1e-5 -db nr

このコマンドを実行したことは覚えていても、数週間後に「このとき evalue の設定はどうしていたっけ？」と振り返ろうとした際、手書きのノートに記録していただけでは、転記ミスがあって正確に再現できない… ということも。

解析研究では、単に結果を残すだけでなく「どのようにその結果を得たのか」を記録することが重要 です。そのために、手書きノートだけでなく、スクリプトを活用した管理 をおすすめします。

本記事では、解析研究の記録の方法として、
✅ なぜ手書きノートだけでは不十分なのか？
✅ スクリプトを使って解析の記録を残す方法
✅ データやスクリプトを整理するディレクトリ構造の例
✅ 手書きノートには何を記録すればよいか？
✅ 初心者が陥りがちなミスとその対策
などを解説します。

「解析研究の記録方法がよく分からない」という方は、ぜひ参考にしてみてください！


1. 手書きノートだけでは不十分な理由

解析研究の記録を残す方法として、手書きノートにコマンドや結果を書き込むことを考える人もいるかもしれません。確かに、実験研究では「手書きノートにすべて記録する」ことが基本 なので、その延長で解析の記録もノートに残そうとするのは自然な発想です。

しかし、解析研究において手書きノートだけに頼るのは非効率 です。その理由をいくつか挙げてみましょう。

① 転記ミスのリスクがある

例えば、BLAST で相同性検索を行った際のコマンドを手書きノートに記録するとします。

blastp -query data.fasta -evalue 1e-5 -db nr

しかし、手で書き写す際に -evalue の記載を -evalue 1e-6 と間違えてしまったり、-db の指定を書き忘れてしまったりする可能性があります。特に長いコマンドや複雑なパイプ処理を含む場合、転記ミスやスペルミスが起こりやすくなります。

手書きノートでは、こうしたミスに気づかず、「なぜ前回と同じ結果が得られないのか？」と悩むことにもなりかねません。

② コマンドのオプションを後から正確に思い出せない

解析が成功したときは問題ありませんが、数週間後、あるいは数か月後に再解析が必要になったときに「どのオプションをつけたのか？」を正確に思い出せるでしょうか？

例えば、以下のようなコマンドを実行したとします。

fastqc -t 4 -o output/ input.fastq.gz

手書きノートには「FastQC で品質チェックを実行」と書いたものの、

  • -t 4（スレッド数指定）は何のためにつけたのか？

  • -o output/ というフォルダはどこに作ったのか？

といった細かいオプションの設定が思い出せず、結局検索し直すはめになる ことも。

③ 解析手順を再現しにくい

手書きノートには「このファイルで解析をした」と書いてあっても、その解析をまったく同じ条件で再実行できる保証はありません。

例えば、以下のようなケースで困ることがあります。
✅ 以前の解析と比較したいのに、細かい設定が違うのか、結果が少し変わってしまう
✅ 共同研究者に解析手順を共有しようとしたら、「どのパラメータを使ったの？」と聞かれ、正確に答えられない
✅ 別のサンプルでも同じ解析をしたいのに、一からコマンドを打ち直すのが面倒

どの分野の研究でも、再現性はとても重要です。
そのため、単なる手書きノートだけでなく、スクリプトを活用して解析手順を正確に残すこと が重要になります。

2. コマンドはスクリプトとして保存しよう

手書きノートだけでは解析の再現性を確保しにくいことが分かりました。では、どうすればよいのでしょうか？

その解決策の一つが、解析で使用したコマンドをスクリプト（ファイル）として保存すること です。

スクリプトを保存するメリット

✅ 転記ミスを防げる → 手書きではなくデジタルファイルとして保存することで、コマンドやオプションの書き間違いがなくなる
✅ 後から解析手順を正確に再現できる → いつでも同じスクリプトを実行すれば、同じ解析ができる
✅ 再利用が簡単 → 新しいデータで解析するときに、スクリプトを修正するだけで済む

例えば、BLAST で相同性検索を行う場合、以下のようにスクリプトを作成しておくことで、解析を再現しやすくなります。

#!/bin/bash
# BLASTP 相同性検索スクリプト
# 実行日: 2025年2月21日

blastp \
  -query data.fasta \
  -evalue 1e-5 \
  -db nr

このスクリプトを blastp_sample-A_20250221.sh という名前で保存しておけば、後から「どのオプションをつけていたか？」と悩むことがなくなります。

また、スクリプトにコメント（# で始まる部分）を入れておくと、後で見返したときに何のための解析なのかが分かりやすくなるのでおすすめです。

スクリプトの書き方のポイント

スクリプトを作成する際は、以下の点を意識すると整理しやすくなります。

① コマンドは改行を使って読みやすくする

長いコマンドを1行に書くと可読性が下がるため、バックスラッシュ（\）を使って改行 しましょう。

✅ NG例（可読性が悪い）

blastp -query data.fasta -evalue 1e-5 -db nr -out results/output.txt

✅ OK例（可読性が良い）

blastp \
  -query data.fasta \
  -evalue 1e-5 \
  -db nr \
  -out results/output.txt

② スクリプトのファイル名に日付やサンプル名を入れる

スクリプトを管理しやすくするために、「解析の種類 + サンプル名 + 日付」 のようなルールでファイル名をつけると便利です。

📌 ファイル名の例:
✅ blastp_sample-A_20250221.sh（サンプルAのBLASTP解析を2025年2月21日に実施）
✅ qc_experiment1_20250220.sh（実験1の品質チェックを2025年2月20日に実施）

このように命名すると、どの解析をいつ実行したのかが一目で分かる ようになります。

スクリプトの実行方法

作成したスクリプトを実行するには、まずchmod（チェンジモード）コマンドを使ってファイルに実行権限を付与（+x）します。

chmod +x blastp_sample-A_20250221.sh

その後、以下のコマンドで実行できます。

./blastp_sample-A_20250221.sh

スクリプト管理をさらに便利にするには？

解析の数が増えてくると、スクリプトが増えて管理が大変になります。そこで、
📌 Git などのバージョン管理システムを使う方法もある ことを軽く紹介しておきます。

git init  # 新しいリポジトリを作成
git add blastp_sample-A_20250221.sh  # スクリプトを追加
git commit -m "BLASTP解析スクリプトを追加"

ただし、Git の詳しい使い方は別の記事で解説するので、初心者の方はまずはスクリプトの保存に慣れることを優先 してください。

3. データと結果のディレクトリ構造を整える

解析研究では、コマンドやスクリプトを保存するだけでなく、データや解析結果を整理するディレクトリ構造を整えることも重要 です。適切なフォルダ構成を作っておくことで、ファイルの管理がしやすくなり、「どこに何があるのか分からない…」という状況を防ぐことができます。

ディレクトリ構造の基本例

解析研究に関連する各ファイルは、以下のようなディレクトリ（フォルダ）構成に保管することを推奨します。

/project_name/         # 解析の内容がわかる名前
├── raw_data/          # 生データ（取得したままのデータ）
├── scripts/           # 解析スクリプト
├── results/           # 解析結果（出力ファイル）
├── logs/              # 実行ログ（エラーメッセージや実行記録）
└── README.md          # プロジェクト概要とメモ

各ディレクトリ（フォルダ）の役割

📌 raw_data/（生データ）

  • 解析の元となる生データ（例: FASTQ ファイル、FASTA ファイル）を保存

  • 重要：生データは編集せず、そのままの状態で保存すること！

📌 scripts/（スクリプト）

  • 解析に使用するスクリプト（bash や zsh の .sh ファイルなど）を保存

  • スクリプトには日付やサンプル名を含め、管理しやすくする

📌 results/（解析結果）

  • 解析の出力データ（例: BLAST 結果、品質チェックレポート）を保存

  • どのスクリプトで作成したデータか分かるように、フォルダを分けると良い 

/results/
 ├── blastp_20250221/ # BLAST の結果
 ├── fastqc_20250220/ # FastQC の結果
 └── alignment_20250222/ # アラインメント結果

📌 logs/（実行ログ）

  • 解析スクリプトの出力メッセージやエラーメッセージを保存

  • 下記のように実行して記録しておくと、解析のトラブルシューティングがしやすくなる

script.sh > logs/script_20250221.log 2>&1

実行後だけでなく、解析の途中でもログファイルを確認することができる。

less script.sh > logs/script_20250221.log   # ページ送りしながら全体を見れる
 または
cat script.sh > logs/script_20250221.log    # 一気に最後の行が表示される

📌 README.md（プロジェクト概要）

  • 簡単なメモや注意点を記録（ファイルの保存場所、解析の目的など）

  • こまめにメモを残すと、作業の記録（ログ）になるので後々便利

  • 論文を書くときに参照できる

  • 共同研究者とデータを共有する場合にも便利

  • マークダウン形式で記入する前提にしているが、見出し等を工夫して読みやすくすれば、単縦なテキストファイルでも問題ない

ディレクトリを整理するメリット

✅ どこに何があるのか一目で分かる（スクリプト・データ・結果が混ざらない）
✅ 解析の再現性が向上する（解析をもう一度実行するときに迷わない）
✅ 共同研究者とスムーズにデータを共有できる（整理された構造なら説明しやすい）

ディレクトリ構造の作成方法（コマンド例）

手動でフォルダを作ることもできますが、以下のようなコマンドを使うと一括で作成できます。

mkdir -p project_name/{raw_data,scripts,results,logs}
touch project_name/README.md

このコマンドを実行すると、project_name/ の中に各フォルダと README ファイルが自動で作成されます。mkdir -p で再起的にディレクトリ（フォルダ）を作成、touchでからのファイルを作成します。

4. 手書きノートには何を記録するべきか？

スクリプトを活用することで解析の記録が正確に残せるようになりますが、手書きノートも依然として重要な役割を持ちます。解析研究では、「スクリプトで記録する情報」と「手書きノートで記録する情報」を適切に分けることがポイントです。

ここでは、手書きノートに記録すべき情報を整理します。

手書きノートに記録すべき情報リスト

✅ 1. 日付

  • いつ解析を行ったのか を明確にする

  • スクリプトのファイル名にも日付を含めることで対応できるが、ノートにも記録しておくと分かりやすい

✅ 2. 解析の目的

  • なぜこの解析を行うのか？ を簡潔に記録

  • 例:「サンプルAとサンプルBの遺伝子相同性を調べるために BLASTP を実施」

✅ 3. 使用したスクリプトやデータの保存場所

  • 解析に使用したスクリプトのファイル名やデータの場所を記録

  • 例:

    • 実行スクリプト: scripts/blastp_sample-A_20250221.sh

    • データ保存場所: raw_data/sample-A.fasta

    • 解析結果: results/blastp_20250221/output.txt

✅ 4. 解析時のメモ（工夫した点・変更した点）
解析を進めていくと、試行錯誤の過程で設定を変えたり、思わぬ問題に遭遇したりする ことがあります。こうしたポイントをノートに記録しておくと、後で役立ちます。

📌 記録しておくとよいポイント

  • 以前とは異なるオプションを試した場合（例: evalue を 1e-5 → 1e-10 に変更）

  • 特定のエラーが発生した場合（エラーメッセージの概要や対策をメモ）

  • 予想外の結果が出た場合の考察（「低品質データの影響かも？」など）

✅ 5. 解析の結果（概要）
スクリプトを実行した結果、期待した結果が得られたかどうか を簡潔にまとめる。

  • 成功した場合:「BLASTP の結果が得られた。予想通りの相同性が見られた。」

  • 失敗した場合:「エラー発生。データのフォーマットが正しくない可能性あり。」

  • 次に何をすべきか:「データのフォーマットを確認して再実行する。」

手書きノートの記録例（イメージ）

📖 手書きノート記録例（2025年2月21日）

【解析名】BLASTP 相同性検索  
【目的】サンプルAとサンプルBの遺伝子相同性を調べる  
【スクリプト】scripts/blastp_sample-A_20250221.sh  
【データ】raw_data/sample-A.fasta  
【結果】BLASTP のヒット数が予想より少ない  
【考察】E-value の設定を1e-5から1e-6に変更して再試行  
【次のアクション】再試行後、結果を比較する

なぜ手書きノートが必要なのか？

「スクリプトで記録できるなら、手書きノートはいらないのでは？」と思うかもしれません。しかし、手書きノートには次のようなメリットがあります。

✅ 試行錯誤の過程を記録できる（スクリプトでは変更点の詳細をすぐに見返せない）
✅ 解析の背景や考察を残せる（スクリプトだけでは「なぜこの解析をしたのか？」が分かりにくい）
✅ 実験ノートと統一して記録できる（解析と実験を組み合わせる研究では一元管理が便利）
✅ 解析記録のバックアップ（解析プロジェクトのディレクトリにREADMEとして記録を保存しても、そのストレージが壊れるなど消失した場合に全てを失う）

5. よくあるミスとその対策

解析研究を始めたばかりの人が陥りやすいミスには、いくつかの共通パターンがあります。ここでは、初心者が特にやりがちなミスとその対策 を紹介します。

❌ ミス①：スクリプトを保存したのに実行できない

🔹 原因: スクリプトに実行権限がない

例えば…

./blastp_sample-A_20250221.sh

を実行しようとして、

bash: ./blastp_sample-A_20250221.sh: Permission denied

というエラーが出る。

🔹 対策: 実行権限を付与する

chmod +x blastp_sample-A_20250221.sh
./blastp_sample-A_20250221.sh

chmod +x を実行すると、スクリプトが実行可能になります。

❌ ミス②：コマンドのオプションを後で見ても意味が分からない

🔹 原因: スクリプト内にコメントがない

例えば…

blastp -query data.fasta -evalue 1e-5 -db nr

このスクリプトを1か月後に見たとき、「なぜ evalue を 1e-5 にしたんだっけ？」と分からなくなる。

🔹 対策: スクリプト内にコメントを入れる

#!/bin/bash
# BLASTP 相同性検索スクリプト
# E-value を 1e-5 に設定（感度と精度のバランスを考慮）
blastp \
  -query data.fasta \
  -evalue 1e-5 \
  -db nr

こうすることで、自分や他の人が後で見ても理解しやすくなります。

❌ ミス③：ファイルの保存場所が分からなくなる

🔹 原因: フォルダ整理がされていない

例えば…

  • data.fasta がデスクトップやダウンロードフォルダに保存されていて、どこにあるか分からなくなる

  • 解析結果がバラバラに保存されていて、どのファイルがどの解析の結果なのか分からない

🔹 対策: 事前に適切なフォルダ構成を作成

/project_name/
├── raw_data/          # 生データ
├── scripts/           # 解析スクリプト
├── results/           # 解析結果
├── logs/              # 実行ログ
└── README.md          # プロジェクト概要

さらに、スクリプト内でも保存場所を明示しておくと良い。

blastp \
  -query raw_data/sampleA.fasta \
  -evalue 1e-5 \
  -db nr \
  -out results/blastp_sampleA_20250221.txt

こうすることで、「どのデータを解析し、どこに結果を保存したのか」がすぐに分かります。

❌ ミス④：解析の結果が再現できない

🔹 原因: 解析条件を正確に記録していない

例えば、「前回と同じ解析をしたはずなのに、結果が微妙に違う…」ということがあります。
その原因として、オプションやデータのバージョンが違う可能性 があります。

🔹 対策:
✅ スクリプトのバージョン管理をする（ファイル名に日付を入れる）
✅ 手書きノートに設定値や変更点を記録する
✅ 解析したデータのバージョンや取得日を記録する

❌ ミス⑤：解析の途中でエラーが出て止まってしまう

🔹 原因: コマンドの文法ミスや依存関係の問題

例えば…

blastp -query data.fasta -evalue 1e-5 -db nr -out output.txt

を実行したら、

blastp: command not found

というエラーが出る。

🔹 対策:
✅ コマンドが正しくインストールされているか確認する

which blastp

✅ エラーメッセージをログに記録する

blastp -query data.fasta -evalue 1e-5 -db nr -out output.txt > logs/blastp_20250221.log 2>&1

エラーメッセージをログに記録しておけば、後から原因を調べやすくなります。

6. スクリプト管理をもっと便利にするには？（発展編）

スクリプトを使って解析の記録を残すことに慣れてきたら、より便利に管理する方法 も知っておくと役立ちます。ここでは、バージョン管理とスクリプトの整理術 について簡単に紹介します。

① バージョン管理を意識する

解析のたびにスクリプトを更新すると、「どのバージョンのスクリプトを使ったか？」が分からなくなることがあります。
そのため、ファイル名に日付やバージョン番号を入れる と管理がしやすくなります。

📌 スクリプトのバージョン管理の例

scripts/
├── blastp_sample-A_20250221_v1.sh     # 初回のスクリプト
├── blastp_sample-A_20250221_v2.sh     # 設定を一部変更
└── blastp_sample-A_20250221_final.sh  # 確定版

こうしておくと、どのスクリプトを使ったのかが後から一目で分かります。

② Git を使ったシンプルなスクリプト管理

スクリプトの数が増えてくると、手動でバージョン管理するのが面倒になります。そこで、Git を使うと、バージョン管理が簡単になります。

Git は初心者には少しハードルが高いかもしれませんが、「とりあえず変更履歴を記録する」だけなら簡単 です。

🔹 Git の基本的な使い方

まず、解析用のフォルダで Git を初期化します。

cd project_name
git init  # Git リポジトリを作成

次に、スクリプトを Git に登録します。

git add scripts/blastp_sample-A_20250221.sh
git commit -m "BLASTP 解析スクリプトを追加"

こうすることで、スクリプトの変更履歴を Git で管理できます。

📌 後から「どのスクリプトを使ったか」を確認する方法

git log --oneline

これで、過去の変更履歴がすぐに確認できる ようになります。

③ 解析環境の情報も記録しておく

スクリプトの管理だけでなく、「どの環境で解析を実行したか」も記録しておくと、再現性の確保 に役立ちます。

📌 解析環境の記録例（README.md に記載）

【解析環境】
OS: Ubuntu 24.10
ソフトウェア: BLAST 2.16.0
データベース: NCBI nr (2025/02/20 更新)

解析環境が違うと、同じスクリプトを実行しても結果が異なることがあるので、環境情報をメモしておくのは重要です。

7. まとめ

解析研究では、実験研究と異なり、コマンドラインを使ってデータ解析を行います。そのため、「どのように解析の記録を残すべきか？」 という問題に直面することが多くあります。

本記事では、手書きノートとスクリプトの両方を活用した記録方法 を紹介しました。

🔹 記事のポイントまとめ

✅ 手書きノートだけでは不十分

  • 転記ミスのリスクがある

  • コマンドのオプションを後から思い出せない

  • 解析の再現が難しくなる

✅ 解析の記録にはスクリプトを活用しよう

  • blastp_sample-A_20250221.sh のようにスクリプトを保存する

  • コメントを入れて、解析の目的や設定を明記する

  • ディレクトリ構造を整理して、スクリプト・データ・結果を管理

✅ 手書きノートには「解析の背景・考察」を記録する

  • 日付・目的・使用データ・変更点・結果などをメモ

  • 試行錯誤のプロセスや気づいたことを残しておく

✅ 初心者が陥りやすいミスと対策

  • 実行権限がない → chmod +x を忘れずに

  • 保存場所が分からなくなる → フォルダを整理

  • コマンドのオプションが思い出せない → スクリプト内にコメントを記入

  • 解析環境の違いで結果が変わる → OS・ソフトウェアバージョンを記録

✅ スクリプト管理をもっと便利にするには？

  • バージョン管理を意識し、ファイル名に日付を入れる

  • Git を活用すれば、変更履歴を管理しやすくなる

  • 解析環境の情報もメモして、再現性を高める

🔹 解析研究の記録は「手書きノート + スクリプト」のハイブリッド管理が最適！

手書きノートとスクリプトをうまく使い分けることで、解析の記録を整理し、再現性を確保することができます。

最初は手間に感じるかもしれませんが、記録をしっかり残しておくことで、「あのときの解析、どうやったんだっけ？」と悩む時間を大幅に削減できます。論文を書き始めたときに、やっておいてよかった！と実感するはずです。

ぜひ、自分なりに使いやすい管理方法を見つけてみてください！

いいなと思ったら応援しよう！

Ozk
この記事があなたのお役に立てましたら、ぜひ、チップで応援していただけると嬉しいです！ あなたの一押しが次の執筆の原動力になります。