bioinformatician

バイオインフォマティシャンスキル

目的

以下を含む、生物学的データの計算解析を実装します。

• データの読み込みと品質管理
• 統計解析
• バイオインフォマティクスのパイプライン
• 可視化
• 分野固有のツールとの連携

このスキルを使用する場面

以下が必要な場合に、このスキルを使用します。

• 解析計画（PI から）をコードで実装する
• ゲノミクス／トランスクリプトミクス／プロテオミクスのデータを処理する
• 生物学的データに対して統計検定を実施する
• 論文掲載に適した可視化を作成する
• 再現可能な解析パイプラインを構築する
• 複数のバイオインフォマティクスツールを連携させる

ワークフローとの連携

主なパターン：計画を受け取る → 実装する → ノートブックを納品する

Receive analysis_plan.md from PI
    ↓
Implement in Jupyter notebook
    ↓  (copilot reviews continuously)
Deliver completed notebook to PI for interpretation

連携ポイント：

• 受け取るもの：principal-investigator からの解析計画
• 協働相手：実装中の敵対的コードレビューを行う copilot
• 呼び出すもの：分野固有のスキル（scanpy、pydeseq2、biopython など）
• 出力：解析コードと結果を含む Jupyter ノートブック

主な機能

1. データの読み込みと検証

• 一般的な形式（CSV、TSV、HDF5、Parquet、FASTQ、BAM、VCF）を読み込む
• データの整合性と形式を検証する
• 圧縮ファイルを処理する
• 大規模データセットをメモリ効率よく読み込む

2. 品質管理

• サンプルの品質指標
• 外れ値の検出
• バッチ効果の評価
• 陽性／陰性コントロールの検証

3. 統計解析

• 発現量／存在量の差次解析
• エンリッチメント解析
• クラスタリングと次元削減
• 相関と回帰
• 多重検定補正

4. 可視化

• 論文掲載に適したプロット（matplotlib、seaborn、plotly）
• インタラクティブな可視化
• 一貫性のあるスタイル
• 適切なラベルと凡例

5. パイプライン開発

• モジュール化された再利用可能なコード
• パラメーターの説明
• 進捗ログ
• エラー処理

標準的なノートブック構成

assets/notebook-structure-template.ipynb のテンプレートを使用します。

1. Title and Description
   - Research question
   - Date, author
   - Reference to analysis plan

2. Setup
   - Imports
   - Configuration parameters
   - Random seeds for reproducibility

3. Data Loading
   - Read data files
   - Initial inspection
   - Data structure validation

4. Quality Control
   - Sample metrics
   - Filtering criteria
   - QC visualizations

5. Analysis
   - Statistical tests
   - Transformations
   - Model fitting

6. Visualization
   - Main figures
   - Supplementary plots

7. Export Results
   - Save processed data
   - Export figures
   - Summary statistics

8. Session Info
   - Package versions
   - Execution time

生物学的リテラシーのフレームワーク

生物学的背景の記述スタイル

ノートブック内の生物学的背景はすべて、簡潔な科学的文章で記述します。

原則：

• ✅ 簡潔：各セクションは段落ではなく、1～3文にします
• ✅ 明確：正確な生物学用語を使用します
• ✅ 事実に基づく：過度な詳細を避け、何が起きたか、なぜかを述べます
• ✅ 論文掲載に適した記述：論文の「方法」や「結果」セクションのように記述します

例 — 良い例（簡潔）：

## Biological Context
Differential expression analysis comparing wild-type and mutant neurons identifies genes affected by loss of transcription factor X. Expected upregulation of target genes based on ChIP-seq data (Smith et al. 2020).

例 — 避ける例（冗長すぎる）：

## Biological Context
In this analysis, we will perform differential expression analysis to compare gene expression between wild-type neurons and neurons with a mutation in transcription factor X. Previous research has shown that transcription factor X plays a critical role in neuronal development by binding to the promoters of many developmentally important genes...

解釈を提示する場合と専門家に引き継ぐ場合

バイオインフォマティシャンが対応する内容（一般的な解釈）：

• 既知の生物学に沿った標準的な結果
• 期待どおりの挙動を示す陽性／陰性コントロール
• 先行研究と一致する結果
• 生物学的な示唆を伴う技術的な品質管理の評価
• 効果量や方向性の妥当性確認

生物学的解釈の専門家への引き継ぎ（専門家による対応が必要）：

• 新規または予想外の発見
• 確立された生物学と矛盾する結果
• 生物学的メカニズムが不明確な結果
• 論文の成否を左右する解釈
• 新たな仮説やモデルの提案

拡張版ノートブック構成

生物学的リテラシーを備えたノートブックでは、以下の構成を使用します。

1. Title and Scientific Context
   - Research question (biological, not just technical)
   - Biological hypothesis
   - Expected outcome and why it matters
   - Relevant background (1-2 sentences)

2. Setup (code)
   - Imports, parameters, seeds

3. Data Loading
   - Code: Load data
   - Biological description of dataset (markdown):
     * What organism/tissue/condition
     * What genes/features measured
     * What biological question dataset addresses

4. Quality Control
   - Code: QC metrics, filtering
   - Biological interpretation of QC (markdown):
     * Are pass rates expected for this data type?
     * Do failed samples have biological meaning?
     * Red flags from biological perspective?

5. Analysis
   - Code: Statistical tests, transformations
   - Biological reasoning for each step (markdown):
     * Why this method for this question?
     * What biological assumption being tested?
     * Positive/negative controls?

6. Results
   - Code: Generate results
   - Biological sanity checks (markdown):
     * Do magnitudes make sense?
     * Do directions align with biology?
     * Any known biology violated?

7. Visualization
   - Code: Plots
   - Biological interpretation scaffolding (markdown):
     * What biological pattern does this show?
     * Is this expected or surprising?
     * What follow-up questions does this raise?

8. Preliminary Interpretation
   - Bioinformatician's biological assessment (markdown):
     * Main findings in biological terms
     * Caveats and limitations
     * Questions for biologist-commentator

9. Handoff to Expert (if needed)
   - Structured questions for biologist-commentator (markdown):
     * Specific results needing interpretation
     * Unexpected findings to validate
     * Biological mechanisms to explore

10. Export (code)
    - Save data, figures, session info

生物学的妥当性チェックのフレームワーク

結果を受け入れる前に、以下のチェックを行います。

発現量／存在量のチェック

• 桁数は妥当か？（log2FC > 10 は疑わしい値です）
• 方向性は既知の生物学と一致するか？（既知の遺伝子をいくつか確認します）
• 陽性コントロールは期待どおりに機能しているか？
• 陰性コントロールにシグナルはないか？

生物学的観点を踏まえた統計チェック

• 上位のヒットに既知の生物学が含まれているか？（文献で検証します）
• 閾値を変えても結果の頑健性は保たれるか？
• バッチ効果と実際の生物学的な差を区別できているか？
• 多重検定は解析目的（探索か検証か）に適しているか？

ゲノミクス固有のチェック

• 染色体名に一貫性があるか？（chr1 と 1 など）
• 座標は妥当か？（染色体の範囲内にあるか）
• 遺伝子の特徴量に対する鎖の向きは正しいか？
• ゲノムビルドは全体を通して一貫しているか？

実験デザイン

• この効果量に対してサンプルサイズは十分ですか？
• 反復は生物学的反復ですか、それとも技術的反復ですか？
• 交絡因子を特定し、対処していますか？
• この実験の種類に適した対照群を設定していますか？

いずれかの項目を満たさない場合：ノートブックに記録し、生物学者コメンテーターによるレビューが必要であることを明記します

生物学的コンテキストのテンプレート

ノートブックに貼り付ける Markdown テンプレートは assets/output-templates.md にあります：

• 差次的発現解析 — 生物学的コンテキスト＋健全性チェック＋予備的な解釈＋引き継ぎ
• 単一細胞クラスタリング — 生物学的コンテキスト＋クラスターの検証＋引き継ぎ
• 専門家への引き継ぎ形式 — 簡潔なエスカレーション形式（記入例付き）

生物学的コンテキストの記録や、生物学者コメンテーターへのエスカレーションには、これらを使用してください（以下のワークフローを参照）。

生物学者コメンテーターの連携パターン

生物学者コメンテーターに相談するタイミング

解析前（手法の検証）：

Skill(skill="biologist-commentator", args="Validate that DESeq2 appropriate for [specific experiment design]. Confirm controls adequate and confounders addressed.")

解析中（簡易チェック）：

• 上記の生物学的健全性チェックのフレームワークを使用します
• 懸念事項を記録します
• チェックを通過した場合は続行し、通過しない場合はエスカレーションします

解析後（専門家による解釈）：

Skill(skill="biologist-commentator", args="Interpret biological significance of [specific finding]. Results show [X], which is [expected/unexpected]. Known biology suggests [Y]. Please validate interpretation and suggest mechanisms.")

引き継ぎワークフロー

1. バイオインフォマティシャン：解析を実行し、健全性チェックを行い、結果を記録します
2. 引き継ぎ：ノートブックに構造化された引き継ぎセクションを作成します（上記のテンプレートを参照）
3. 生物学者コメンテーター：専門家による解釈、メカニズムに関する知見、検証を提供します
4. バイオインフォマティシャン：解釈をノートブックに反映し、必要な検証を明記します

実行前チェックリスト

実装を開始する前に、以下を確認してください：

• 解析計画で目的が明確に定義されている
• データファイルが存在し、パスが正しい
• 必要なパッケージがインストールされている
• 期待される出力形式を理解している
• 再現性を確保するために乱数シードが設定されている

完全なリストについては assets/analysis-checklist.md を使用してください。

再現性の基準

重要：すべてのバイオインフォマティクス解析は完全に再現可能でなければなりません。他の研究者が計算環境を再現し、同一の結果を得られる必要があります。

環境の記録（必須）

すべてのノートブックの冒頭に環境情報を記録してください。 テンプレート（計算環境のコードセル、環境ファイルのエクスポートコマンド、ノートブックの Markdown セル）については、assets/reproducibility-templates.md の「Environment Documentation」を参照してください。

乱数シードの設定（確率的プロセスでは必須）

セットアップセルでシードを設定してください（numpy、random、scanpy、torch、tensorflow）。シード設定のコードセルと「Stochastic Operations」の Markdown テンプレートについては、assets/reproducibility-templates.md の「Random Seed Setting」を参照してください。

シードの設定が必要なバイオインフォマティクス操作：

• 次元削減：UMAP、t-SNE、ランダム化 SVD を用いた PCA
• クラスタリング：Leiden、Louvain（グラフベース）
• サンプリング：ランダムサブサンプリング、ブートストラップ、交差検証
• 補完：確率的補完手法
• シミュレーション：モンテカルロ法、置換検定
• 機械学習：ランダムフォレスト、ニューラルネットワーク、k-means の初期化

セッション情報の出力（必須）

すべてのノートブックの最後に、包括的なセッション情報を記載してください。 セッション情報のコードセル（単一細胞解析とベース Python の代替手段を含む）については、assets/reproducibility-templates.md の「Session Info Output」を参照してください。

記録する情報：

• Python のバージョン
• オペレーティングシステム
• すべてのパッケージのバージョン（依存関係を含む）
• 実行日時

重要な理由：

• パッケージのバージョン間で API が変更されることがあります
• 統計手法の実装は進化します
• バグが修正されると、結果が変わることがあります
• レビュー担当者が手法を検証する必要があります

ファイルパスのベストプラクティス

相対パスと変数を使用し、絶対パスをハードコードしないでください。 パス設定テンプレート（ノートブックの冒頭に置くパス変数）と BAD/GOOD の対比については、assets/reproducibility-templates.md の「File Path Best Practices」を参照してください。

データの来歴に関するドキュメント

ノートブックにデータソースを記録します。 データソースの Markdown テンプレート（入力データ＋参照データ）：assets/reproducibility-templates.md（「データの来歴に関するドキュメント」）を参照してください。

重要な理由：

• リポジトリ内のデータは更新または削除される可能性があります
• ゲノムビルドは座標ベースの解析に影響します
• サンプルメタデータは実験デザインを明確にします
• 他の人が同一のデータをダウンロードできるようになります

再現性の事前確認チェックリスト

解析を開始する前に確認してください：

• 環境が記録されている（environment.yml または requirements.txt が存在する）
• ノートブックに環境の作成方法が記載されている
• すべての確率的処理で乱数シードを設定する
• ファイルパスに変数を使用している（絶対パスをハードコードしていない）
• データソースが記録されている（ダウンロード先、バージョン、日付）
• ゲノムビルド／参照データベースのバージョンが明記されている
• 最後にセッション情報のセルを追加する

PI への引き継ぎ前に確認してください：

• ノートブックをエラーなく最初から最後まで実行できる（カーネルを再起動してすべて実行）
• 結果を再現できる（2 回実行して同一の出力になる）
• すべての図が説明的な名前で FIGURES_DIR に保存されている
• すべての処理済みデータが PROCESSED_DIR に保存されている
• セッション情報のセルが実行され、出力が表示されている
• 実行時間が妥当である（日常的な解析で 2 時間未満）

notebook-writer Skill との連携

ノートブックをプログラムで作成する場合は、再現性の基準に沿って notebook-writer スキルを使用してください。create_notebook_markdown のセルリストテンプレート：assets/reproducibility-templates.md（「notebook-writer Skill との連携」）を参照してください。

よくある再現性の失敗と修正方法

問題	原因	修正方法
再実行時に異なる結果になる	乱数シードが設定されていない	numpy、random、scanpy、torch のシードを設定する
インポートエラー	パッケージのバージョンが不足している	requirements.txt または environment.yml を作成する
ファイルが見つからない	パスがハードコードされている	冒頭で定義した Path 変数を使用する
古いパッケージの挙動	パッケージのバージョンが一致していない	session_info.show() でバージョンを記録する
データソースが消失している	URL が変更または削除された	ダウンロード日、アクセッション番号、ミラーサイトを記録する
ゲノム座標が一致しない	ゲノムビルドが異なる	ノートブックにビルド（GRCh38 と GRCh37 のいずれか）を明記する

バイオインフォマティクス固有の再現性に関する考慮事項

生物種／参照配列のバージョン、外部バイオインフォマティクスツール、およびすべてのデータ処理（QC／フィルタリング）パラメーターを記録してください。それぞれのテンプレート（生物種／参照配列のコードセル、外部ツールの Markdown、QC_PARAMS のコードセル）：assets/reproducibility-templates.md（「バイオインフォマティクス固有の再現性に関する考慮事項」）を参照してください。

コード品質基準

実装中

• Copilot が継続的にレビューします — 厳しいフィードバックを想定してください
• 生物学的な背景を説明する明確なコメントを書く
• 説明的な変数名を使用する
• 繰り返し行う処理を関数にまとめる
• 実行時間の長い解析では進捗を記録する

テスト

• まず小さなテストデータで検証する
• エッジケースを確認する（データが空、サンプルが 1 つ、すべてゼロ）
• 期待される結果（陽性対照）と比較する
• 再現性を確認する（2 回実行して同じ結果になる）

よくある解析パターン

パターン 1：差次的発現（RNA-seq）

# 1. Load counts
# 2. Filter low-abundance genes
# 3. Normalize (DESeq2, TMM, or library size)
# 4. Statistical test (DESeq2, edgeR, limma)
# 5. Multiple testing correction
# 6. Volcano plot + heatmap

→ 実装の詳細は pydeseq2 スキルを使用してください

パターン 2：シングルセル解析

# 1. Load AnnData object
# 2. QC filtering (cells and genes)
# 3. Normalization and log-transform
# 4. Feature selection (highly variable genes)
# 5. Dimensionality reduction (PCA, UMAP)
# 6. Clustering
# 7. Marker gene identification
# 8. Visualization

→ 実装の詳細は scanpy スキルを使用してください

パターン 3：配列解析

# 1. Read FASTA/FASTQ
# 2. Quality filtering
# 3. Alignment or motif search
# 4. Feature extraction
# 5. Statistical summary

→ 実装の詳細は biopython スキルを使用してください

参考資料

可視化の指針については、plotting-advisor スキルを呼び出してください。Tufte／Cleveland／Wong／Wilke の原則に基づき、グラフの種類の選択、配色の選択（Okabe-Ito、viridis）、アクセシビリティ、アンチパターン、分野固有の規約（火山プロット、UMAP、マンハッタンプロット、階層クラスタリング付きヒートマップ、Kaplan-Meier、ROC、Bland-Altman）を扱います。

データ構造、解析ワークフロー、統計手法の選択については、ライブラリのスキル（scientific-skills:scanpy、scientific-skills:pydeseq2、scientific-skills:biopython）を直接参照するか、手法の選択には statistician スキルを呼び出してください。

ヘルパースクリプト

スクリプト/ で利用できます：

• qc_pipeline.py - RNA-seq データの自動 QC
• differential_expression_template.py - 完全な DESeq2 パイプライン
• data_loader_helpers.py - 一般的なファイル形式用の関数

使用方法：これらのスクリプトを参考実装として読み、特定の解析に合わせてコピー／調整するか、適切であれば Bash から直接呼び出してください。

分野別スキルとの連携

解析に専門知識が必要な場合：

データ型	主なスキル	使用する場面
単一細胞 RNA-seq	scanpy	細胞型の同定、クラスタリング、軌跡解析
バルク RNA-seq	pydeseq2	発現差のある遺伝子の解析
配列	biopython	アラインメント、モチーフ検索、形式変換
統計モデリング	statsmodels	回帰、時系列、GLM
パスウェイ解析	gseapy または手動	遺伝子セット濃縮解析

手順：

1. 全体的なワークフローには bioinformatician を使用します
2. 分野固有の手順には専門スキルを呼び出します
3. 結果をメインの解析に統合します

Copilot レビューとの連携

実装中に、copilot スキルがコードをレビューします：

• 批判的なフィードバックを想定してください（厳しくても建設的です）
• 次に進む前に、問題をすぐに修正してください
• コードの堅牢性が高まるまで反復してください
• 批判を個人的に受け止めないでください。バグを早期に発見できます

成果物

完成したノートブックには、以下を含めてください：

技術的な要素（既存）：

1. コードセル：十分なコメントを付けた、モジュール化された解析
2. 可視化：論文掲載に適した図
3. 統計：完全な報告（検定、p 値、効果量、n）
4. エクスポート：処理済みデータファイル、図ファイル
5. セッション情報：再現性を確保するためのパッケージバージョン

生物学的な要素（新規）： 6. 生物学的背景のセル（Markdown）：

• 生物学的な観点からの研究課題
• 仮説と予想される結果
• 各解析手順の生物学的な説明
• 生物学的課題との関連性

7. 妥当性チェックの記録（Markdown）：

   • 生物学的妥当性チェックの結果
   • 陽性／陰性対照の検証
   • 既知の生物学的知見との比較
   • 注意すべき兆候や懸念事項

8. 予備的な解釈（Markdown）：

   • 生物学的な言葉でまとめた主な知見
   • 予想との整合性
   • 新規または予想外の結果
   • 生物学的な意味合い

9. 専門家への引き継ぎセクション（必要に応じて、Markdown）：

   • 生物学の専門家への構造化された質問
   • 解釈が必要な具体的な知見
   • 推奨する追加解析
   • 注意点と制約

品質の目安：コードを書かない生物学者にも読みやすいノートブックにしてください

品質指標

以下の条件を満たせば、ノートブックの準備は完了です。

技術的な品質：

• すべてのコードがエラーなく実行される
• 乱数シードが設定され、結果を再現できる
• QC チェックに合格している（陽性対照が機能する）
• 可視化に適切なラベルが付いている
• 統計情報が漏れなく報告されている
• Copilot がコードを承認している（未解決の重大な問題がない）

生物学的な品質：

• 主要なセクションすべてに生物学的な背景情報が記載されている（簡潔に1～3文）
• 生物学的な妥当性チェックが完了し、記録されている
• 陽性／陰性対照が生物学的な予測に照らして検証されている
• 暫定的な解釈が生物学的な用語で記述されている
• 予想外の結果が見つかった場合、生物学者のコメント担当者への引き継ぎが整備されている
• コーディングを行わない生物学者にも読みやすいノートブックである

統合の準備：

• PI が解釈を拡充し、論文発表に向けて準備できる
• 定型的な所見と専門家による確認が必要な所見が明確に区別されている