broadinstitute/depmap_omics 完整教學指南
一句話定位：depmap_omics 是 Broad Institute 維護的官方 DepMap 季度資料生產 pipeline。每季把 CCLE 細胞株的 WGS/WES/RNAseq raw data，透過 Terra cloud workflows 處理成 DepMap portal 對外發佈的標準矩陣（CN、Mutation、Expression、Fusion、Dependency）。
對 Apotek 專利的角色：Module 2 用到的
CRISPRGeneEffect.csv、Model.csv、OmicsSomaticMutationsMatrixDamaging.csv等檔案即由此 pipeline 產出；本文件作為 Module 2 §112 enablement 的「上游資料品質與來源 reference」。
1. 專案定位與核心概念
什麼是 depmap_omics？
depmap_omics 是 Broad Institute Cancer Dependency Map (DepMap) 團隊的內部資料生產工具，公開於 GitHub 但實際執行需 Broad 的 Terra workspace 與 Google Cloud 權限。其產出即 https://depmap.org/portal/ 上的對外 quarterly data release。
外部使用者的價值：
- 理解 DepMap 對外公開檔案如何產出（資料來源、處理參數、過濾條件）
- 引用為 §112 enablement reference（資料是「可被 ordinary skill 重現」的）
- 重現特定步驟（如
expressions.py內的 ssGSEA、copynumbers.py內的 log2 轉換）
核心特點
- 季度週期：21Q1 → 25Q2（含 8+ 個 release，每季 1 次大更新）
- 5 條主 pipeline：CN、Mutation、Expression、Fusion、Fingerprint
- Terra-native：WDL workflows + Dalmatian Python client
- 內外分離：外部使用者可跑後處理（
postProcess()）；上傳 taiga 等步驟僅內部使用 - 無 LICENSE：repo 本身無 license；資料使用需遵守 DepMap 條款
適合對象
- 想理解 DepMap 對外公開資料如何產出的研究人員
- 想重現特定 omics 後處理步驟的計算生物學家
2. 安裝指南
系統需求
- Python 3.9+（建議 3.9–3.11）
- R（用於 ssGSEA / GSVA / DESeq2）
- Google Cloud SDK（需
gcloud auth application-default login） - Docker（可選；某些 task 用容器執行）
- Terra workspace 存取權（外部使用者跑 Terra 端會失敗）
快速安裝（外部使用者—只跑後處理）
1git clone https://github.com/broadinstitute/depmap_omics.git
2cd depmap_omics
3
4# 用 poetry（建議）
5poetry install
6
7# 或 pip
8pip install -e .
9pip install -r requirements.txt
R 依賴（ssGSEA 必要）
1R -e 'if(!requireNamespace("BiocManager", quietly=TRUE)){install.packages("BiocManager")}; BiocManager::install(c("GSEABase","erccdashboard","GSVA","DESeq2"))'
額外注意
- 需要
genepylibrary（Broad 另一個 repo: https://github.com/broadinstitute/genepy） depmap_omics_upload是內部 fork（25q3-mut-upload 分支），外部 user 跳過
3. 核心架構解析
整體採「3 階段管線」設計：Upload → Terra workflows → Postprocess（+ QC + Upload）。第 1、4 階段內部限定；第 2、3 階段公開。
flowchart TD
A[Sequencing raw data
WGS / WES / RNAseq] --> B[Step 1: Upload
internal only]
B --> C[Step 2: Terra Pipelines
WDL workflows]
C -->|outputs| D[Step 3: Postprocess
depmapomics/*.py]
D --> E[Step 4: QC + Group + Upload to portal
internal only]
E --> F[DepMap Portal Release
e.g. 24Q4, 25Q2]
D --> D1[copynumbers.py
CN postProcess]
D --> D2[mutations.py
SNV/INDEL/SV postProcess]
D --> D3[expressions.py
RNA-seq RSEM + ssGSEA]
D --> D4[fusions.py
gene fusion filter]
D --> D5[fingerprinting.py
sample fingerprint check]
style B fill:#fce8b2
style E fill:#fce8b2
style F fill:#c9e6a9
5 條後處理 pipeline 的功能對照
| Module | 核心檔案 | 入口函式 | 對應 DepMap portal 輸出 |
|---|---|---|---|
| Copy Number | depmapomics/copynumbers.py | postProcess() | gene-level CN（rel + abs）、segment table |
| Mutation | depmapomics/mutations.py | postProcess() | MAF、hotspot + damaging matrix、binary guide matrix、SV |
| Expression | depmapomics/expressions.py | postProcess() | transcript / gene / protein-coding gene 矩陣 + 可選 ssGSEA |
| Fusion | depmapomics/fusions.py | postProcess() | filtered gene fusion table |
| Fingerprint | depmapomics/fingerprinting.py | compareFingerprint() | 樣本身分驗證 |
與 DepMap CRISPR Gene Effect 的關係
CRISPRGeneEffect.csv（celltype-agent loaders.py:load_crispr() 載入的檔案）不在本 repo 的 5 條主 pipeline。它由 DepMap 的 Avana / Achilles CRISPR pipeline 另外產出（屬於 Achilles 子專案，非 omics）。
但 Model.csv（cell line 元資料）與 OmicsSomaticMutationsMatrixDamaging.csv 由本 repo 的 mutation pipeline 產出。
主要過濾條件（Mutation 範例）
1remove if:
2 AF < 0.1
3 OR coverage < 4
4 OR alt_cov == 1
5 OR not in coding region
6 OR in ExAC AF > 0.005%
7 EXCEPT if (in TCGA > 3 OR in COSMIC > 10) AND in known_cancer_regions
8 OR present in > 5% CCLE samples
9 EXCEPT if in TCGA > 5
4. Helper Scripts 詳細用法
repo 沒有專門的 helper script 資料夾；操作介面以 jupyter notebooks 為主：
| Notebook | 角色 |
|---|---|
RNA_CCLE.ipynb | Expression + Fusion pipeline 操作介面 |
WGS_CCLE.ipynb | CN + Mutation pipeline 操作介面 |
release_notebooks/21Q2/*.ipynb | 某季 release 的操作快照 |
pyproject.toml 註冊一個 CLI entry：
1depmapomics --help # poetry script: depmapomics.__main__:main
實際後處理流程從 notebook 內部呼叫各 *.py 的 postProcess() 函式。例如：
1# Expression 後處理（簡化）
2from depmapomics.expressions import postProcess
3postProcess(
4 samples_df,
5 rsem_gene_path,
6 rsem_transcript_path,
7 rsem_isoforms_path,
8 do_ssGSEA=True, # 可選：算 ssGSEA score
9 ...
10)
5. 應用場景
5.1 對 Apotek 專利（Module 2 reference）
flowchart LR
A[depmap_omics
Broad Institute] -->|quarterly release| B[DepMap Portal
CRISPRGeneEffect.csv
Model.csv
etc.]
B --> C[celltype-agent
loaders.py:load_crispr]
C --> D[Apotek Module 2
median gene effect score per cancer]
D --> E[Target Rank Table 整合]
style A fill:#fce8b2
style D fill:#c9e6a9
- depmap_omics 為 Broad Institute 官方 pipeline，125 stars，9 個季度 release，廣泛被學界使用
- 資料處理參數（過濾條件、版本 BioMart may2021、log2 轉換）皆公開
- 對 §112 enablement：說明 Module 2 所依賴的資料來源是「ordinary skill 可重現」的
5.2 重現 ssGSEA scoring（可選步驟）
depmap_omics 的 expressions.py:postProcess(do_ssGSEA=True) 內含 ssGSEA 流程，對應 R 工具 mgenepy/ssGSEA.R。Apotek_v3 Module 1 的 ssGSEA (Step 1-2) 與此相通。
5.3 引用為 §102 prior art（謹慎使用）
depmap_omics 公開了「以 DepMap CRISPR data 計算 gene importance」的方法論，這在 §102 prior art search 時應納入比較。但：
- depmap_omics 本身做的是「資料生產」，不做「target prioritization」；
- Apotek Module 2 做的是「以 median per cancer-type 計算 target importance」，這層分析在 depmap_omics 本身沒做；
- 因此本 repo 並不直接威脅 Apotek claim 的 novelty。
6. 資安掃描報告
自動掃描結果（grep eval/exec/subprocess/shell=True/secrets）
| 等級 | 數量 | 內容 |
|---|---|---|
| 🔴 高（hardcoded secret / RCE） | 0 | 未發現 |
| 🟡 中（shell injection 可能） | ~6 處 | subprocess.run(shell=True)、os.system(“gsutil cp …")，皆在內部 CLI 包裝場景 |
| 🟢 低（已知安全模式） | — | 認證透過 gcloud auth application-default login（標準 GCP 流程，無 hardcoded key） |
詳細位置：
mgenepy/utils/helper.py:180, 185—subprocess.run(exe, shell=True)包裝外部 CLI（GATK / samtools）；輸入exe來自內部參數而非 user input → 使用情境下風險低mgenepy/rna.py:33—subprocess.run(cmd, shell=True)同上depmapomics/copynumbers.py:105—os.system("gsutil cp ..." + plot + ...)路徑 concatenation 若 plot 變數來自不可信來源則為風險，但實際是從已驗證的 Terra outputs 來depmapomics/copynumbers.py:463, 538—subprocess.call(..., shell=True)同上depmapomics/reconcile configs.ipynb:54—exec(content, globals, locals)動態執行設定檔（developer-only notebook，不在生產路徑）
整體評等
🟡 中等風險（內部使用環境下可接受）：
- 所有 shell=True 場景皆為「呼叫外部 bioinformatics CLI」(gsutil, GATK, samtools)，輸入來自內部已驗證資料；
- 若直接給 untrusted user input，存在 shell injection 風險；
- 作為 reference / data consumer 引用不受影響（Apotek 不會直接執行其內部 CLI）
安全引用建議
| 場景 | 建議 |
|---|---|
| 引用為 §112 reference | ✅ 安全（不執行任何程式碼，只引用方法論） |
在 Apotek 內部執行 postProcess() | ⚠️ 隔離環境執行，禁止 untrusted shell argument |
| Fork 修改自用 | ⚠️ 修改前需替換 shell=True 為 shlex.split() 模式 |
7. FAQ
Q1：外部使用者能跑完整 pipeline 嗎？
A：不行。Upload 與 final upload 步驟需 Broad 內部 Terra workspace + taiga 權限。但後處理（*Process() 函式）可獨立執行，前提是備好 Terra workflow 的 output 檔案。
Q2：本 repo 包含 DepMap CRISPR gene effect data 嗎？
A：不包含。CRISPR gene effect 由 DepMap Achilles/Avana CRISPR pipeline 另外產出（屬 viability/dependency 子專案）。本 repo 處理 expression / CN / mutation / fusion。CRISPRGeneEffect.csv 從 https://depmap.org/portal/download/ 取得。
Q3：Apotek Module 2 需 fork 本 repo 嗎？ A：不需要。Apotek Module 2 是 資料消費端，只透過 celltype-agent 載入 DepMap 對外公開檔案。本 repo 僅作為上游 reference，證明資料來源權威性。
Q4：BioMart 版本 may2021 會不會過時？
A：repo 內 expressions.py / copynumbers.py hardcode 此版本。實際生產時各季有可能更新（如 25Q2 升 may2024）。患者層級研究若要重現需 pin 同版本。
Q5：License 為何空白？ A：repo 本身未附 LICENSE 檔。Broad 政策是「程式碼可參考但需遵守 DepMap 資料使用條款」。對外引用務必註明：「程式碼來自 broadinstitute/depmap_omics，使用其產出資料受 DepMap Terms of Use 約束。」
8. 進階技巧
8.1 抽取單一 release 的設定快照
每季 release 在 data/<release>/（例如 data/24Q4/）保留 Terra workspace 設定快照。可作為「在 X 季使用 Y 版本參數」的歷史證據。
8.2 對照不同 release 的處理變動
release_reviews/ 內含發佈前審查紀錄，可看每季變動點。對 §103 non-obviousness 論證有用（顯示這套 pipeline 持續迭代而非靜態）。
8.3 重現 mutation filter 邏輯
depmapomics/mutations.py:postProcess() 完整實作了 §3 末尾列出的 mutation 過濾鏈。若 Apotek 想證明 Module 2 上游資料「過濾條件嚴格、可重現」，可逐步引用該函式。
9. 整合進其他工作流
9.1 與 celltype-agent 整合
1# celltype-agent 一行命令拉 DepMap 對外資料（無需用 depmap_omics 跑 pipeline）
2ct data pull depmap
3
4# 對應 celltype-agent loaders（已驗證可載入）
5src/ct/data/loaders.py
6 load_crispr() # → CRISPRGeneEffect.csv（Achilles 產，不在本 repo）
7 load_model_metadata() # → Model.csv（部分由本 repo mutation pipeline 產）
8 load_somatic_mutations()# → OmicsSomaticMutationsMatrixDamaging.csv（本 repo 產）
9.2 與 Apotek_v3 整合（Module 1 + Module 2 cross-reference）
Apotek_v3 Module 1 在 src/core/enrichment.R 跑 ssGSEA；depmap_omics 在 mgenepy/ssGSEA.R 也跑 ssGSEA。兩者可互為 §112 enablement 的「方法論一致性」證據。
9.3 與 gitnexus / graphify 整合
可選：
1# 為本地 clone 建索引
2gitnexus analyze "/config/workspace/.../projects/research-260519-depmap_omics"
3# 之後可 query：
4gitnexus query "ssGSEA"
5gitnexus impact postProcess
10. 重點摘要 Checklist
對 Apotek Module 2 §112 enablement 撰寫時，從本 repo 應引用的關鍵點：
- depmap_omics 為 Broad Institute 官方 pipeline，125 stars，9 季 release（21Q1–25Q2）
- 資料生產角色：產出
Model.csv等 → DepMap portal → celltype-agent 載入 → Apotek Module 2 消費 - 5 條主 pipeline：CN / Mutation / Expression / Fusion / Fingerprint
- CRISPR gene effect 不在此 repo（屬 Achilles 子專案），但載入流程一致
- 過濾參數透明（mutation AF / coverage / ExAC 等）→ 強化「可重現」論證
- License 為 N/A：引用時加註 DepMap 使用條款
- 資安：🟡 中等（shell=True 在內部 CLI 包裝），對 Apotek 不影響（僅引用方法論，不執行程式碼）
11. 進一步閱讀
- DepMap 官方 portal: https://depmap.org/portal/
- DepMap downloads: https://depmap.org/portal/download/
- depmap_omics 官方 README: https://github.com/broadinstitute/depmap_omics
- DepMap processing 細節:
documentation/DepMap_processing_pipeline.md（repo 內） - Terra 設定:
documentation/getting_started.md（repo 內） - 內部 fork（一般無權限）: https://github.com/broadinstitute/depmap_omics_upload
- 相關 Broad repo: https://github.com/broadinstitute/genepy（depmap_omics 依賴的工具庫）
- 對應 Achilles / CRISPR data: https://depmap.org/portal/achilles/
本教學由 gh-tutorial-qd skill 自動生成；末次更新 2026-05-19；對應 commit 80f54c2（2026-01-20）
Comments