alterlab-cosmic

COSMIC 数据库

概述

COSMIC（癌症体细胞突变目录）是全球规模最大、内容最全面的人类癌症体细胞突变探索数据库。可通过程序访问 COSMIC 丰富的癌症基因组数据，包括数百万个突变、数千种癌症类型、整理后的基因列表、突变特征和临床注释。

何时使用此技能

在以下情况下应使用此技能：

• 从 COSMIC 下载癌症突变数据
• 访问癌症基因普查，获取整理后的癌症基因列表
• 检索突变特征谱
• 查询结构变异、拷贝数改变或基因融合
• 分析耐药突变
• 使用癌症细胞系基因组数据
• 将癌症突变数据整合到生物信息学工作流中
• 研究癌症背景下的特定基因或突变

不适用的情况

场景	改用
生殖系变异致病性（ACMG/AMP、ClinVar 星级）	alterlab-clinvar
通过无需密钥的 API 查询 TCGA 或 MSK 队列中的突变频率 / OncoPrint / 生存情况	alterlab-cbioportal
癌症细胞系中的 CRISPR/RNAi 基因依赖性	alterlab-depmap
非癌症队列中的群体等位基因频率	alterlab-gnomad

前置条件

账户注册

COSMIC 下载数据需要身份验证：

• 学术用户：注册后可免费访问：https://cancer.sanger.ac.uk/cosmic/register
• 商业用户：商业研发、产品 / 服务以及患者服务或临床报告均需获得 COSMIC 商业许可——请参阅 https://www.cosmickb.org/licensing

Python 要求

uv pip install requests pandas
# pysam is only needed if you read the VCF-format downloads
uv pip install pysam

快速开始

COSMIC 当前的下载服务会将每种产品作为 .tar 归档文件提供（其中包含 gzip 压缩的 TSV 或 VCF 文件，以及描述每一列的 README），并使用明确的发布路径，例如 grch38/cosmic/v104/Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar。脚本化下载分两步进行：使用 HTTP Basic 身份验证（电子邮件:密码）向 https://cancer.sanger.ac.uk/api/mono/products/v1/downloads/scripted?path=<archive path>&bucket=downloads 发送 GET 请求，获取包含已签名 url 的 JSON，然后在无需身份验证的情况下从该 URL 下载。旧版 /cosmic/file_download/... 端点以及 CosmicMutantExport.tsv.gz 或 cancer_gene_census.csv 等旧版名称已无法用于脚本——旧端点现在会重定向到登录页面。

1. 基本文件下载

使用 scripts/download_cosmic.py 脚本下载 COSMIC 数据文件：

from scripts.download_cosmic import download_cosmic_file, get_common_file_path

# Cancer Gene Census, current release (v104), GRCh38
download_cosmic_file(
    email="[email protected]",
    password="your_password",
    filepath=get_common_file_path("gene_census"),
    # = "grch38/cosmic/v104/Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar"
)

2. 命令行用法

# Download using shorthand data type (prompts for the password)
python scripts/download_cosmic.py [email protected] --data-type mutations

# Download a specific archive path
python scripts/download_cosmic.py [email protected] \
    --filepath grch38/cosmic/v104/Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar

# GRCh37 and/or a pinned release
python scripts/download_cosmic.py [email protected] \
    --data-type gene_census --assembly GRCh37 --version v103

如果脚本化端点发生变化，请复制 https://cancer.sanger.ac.uk/cosmic/download/cosmic 上任意文件的 脚本化下载下显示的命令，并设置 COSMIC_SCRIPTED_URL。

3. 使用已下载的数据

tar -xf Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar   # -> gzipped TSV + README

import glob
import pandas as pd

# Column names differ from the legacy exports — check the README in each archive.
gene_census = pd.read_csv(glob.glob("Cosmic_CancerGeneCensus*GRCh38*.tsv.gz")[0], sep="\t")
print(gene_census.columns.tolist())

# VCF products (e.g. VCF/Cosmic_GenomeScreensMutant_Vcf_...) extract to .vcf.gz files
import pysam
vcf = pysam.VariantFile(glob.glob("Cosmic_GenomeScreensMutant*_GRCh38.vcf.gz")[0])

可用数据类型

每种数据类型都通过快速入门中所示的同一个 download_cosmic_file(...) 调用下载，只有 filepath 会变化。使用 --data-type 快捷方式（CLI）或 get_common_file_path(...)（Python）构建路径，也可以直接传入 filepath。字段的完整说明请参阅 references/cosmic_data_reference.md。

数据类型	快捷方式	压缩包（grch38/cosmic/v104/…，于 2026-09 验证）
编码突变，全基因组筛查（WGS/WES）	mutations	Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar
编码突变，靶向筛查	targeted_mutations	Cosmic_CompleteTargetedScreensMutant_Tsv_v104_GRCh38.tar
编码突变（VCF）	mutations_vcf	VCF/Cosmic_GenomeScreensMutant_Vcf_v104_GRCh38.tar
非编码变异（VCF）	non_coding_vcf	VCF/Cosmic_NonCodingVariants_Vcf_v104_GRCh38.tar
CGC 基因中的突变	mutation_census	Cosmic_MutantCensus_Tsv_v104_GRCh38.tar
癌症基因普查	gene_census	Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar
耐药突变	resistance_mutations	Cosmic_ResistanceMutations_Tsv_v104_GRCh38.tar
结构变异 / 断点	structural_variants / breakpoints	Cosmic_StructuralVariants_Tsv_… / Cosmic_Breakpoints_Tsv_…
基因融合	fusion_genes	Cosmic_Fusion_Tsv_v104_GRCh38.tar
拷贝数	copy_number	Cosmic_CompleteCNA_Tsv_v104_GRCh38.tar
基因表达	gene_expression	Cosmic_CompleteGeneExpression_Tsv_v104_GRCh38.tar
样本 / 肿瘤分类	sample_info / classification	Cosmic_Sample_Tsv_… / Cosmic_Classification_Tsv_…
突变特征	signatures	独立网站 — https://cancer.sanger.ac.uk/signatures/downloads/

说明：

• 癌症基因普查是经专家整理的癌症基因列表；其中的癌症作用字段将癌基因与肿瘤抑制基因（TSG）区分开，Tier 1/2 表示证据等级。
• 旧版单一的“所有编码突变”导出文件现已拆分为全基因组筛查文件和靶向筛查文件；如需完整覆盖，请合并两者。
• 突变特征（SBS、DBS、ID、CN、SV；当前参考集为 v3.6，2026 年 5 月）需从突变特征网站下载，而非通过产品压缩包获取。
• 每个产品页面都列出 sha256/md5 校验和，请验证大型下载文件。

使用 COSMIC 数据

基因组组装版本

COSMIC 提供两个参考基因组的数据：

• GRCh38（推荐，当前标准）
• GRCh37（旧版，适用于较早的工作流）

在文件路径中指定组装版本（目录名小写，后缀大写）：

# GRCh38 (recommended)
filepath = "grch38/cosmic/v104/Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar"

# GRCh37 (legacy)
filepath = "grch37/cosmic/v104/Cosmic_GenomeScreensMutant_Tsv_v104_GRCh37.tar"

版本管理

• 压缩包路径包含明确的发布版本（v104 = 2026 年 5 月）；下载服务只列出带版本的路径，因此请固定一个版本 — get_common_file_path() 默认使用当前版本
• COSMIC 每年发布两个版本（5 月和 11 月：v101 2024-11、v102 2025-05、v103 2025-11、v104 2026-05）；在作出假设前请查阅发布说明
• 为确保研究结果可复现，请固定发布版本，并与结果一并记录

文件格式

• TSV/CSV：以制表符/逗号分隔，经 gzip 压缩，可使用 pandas 读取
• VCF：标准变异格式，可配合 pysam、bcftools 或 GATK 使用
• 所有文件都包含说明列内容的表头

常见分析模式

当前文件使用大写列名（例如 GENE_SYMBOL、SAMPLE_NAME），而肿瘤部位／组织学信息位于通过 COSMIC ID 关联的样本／分类表中。筛选前，请在各个存档的 README 中确认确切名称。对于一次性提取（单个基因、原发部位或样本），使用网页上的 筛选下载 选项即可，无需下载数 GB 的文件。

按基因筛选突变：

import glob
import pandas as pd

# Extracted from Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar (multi-GB)
tsv = glob.glob('Cosmic_GenomeScreensMutant*GRCh38*.tsv.gz')[0]
mutations = pd.read_csv(tsv, sep='\t', low_memory=False)
tp53_mutations = mutations[mutations['GENE_SYMBOL'] == 'TP53']

按角色识别癌症基因（先规范化表头，再查找角色列）：

cgc = pd.read_csv(glob.glob('Cosmic_CancerGeneCensus*GRCh38*.tsv.gz')[0], sep='\t')
cgc.columns = cgc.columns.str.upper().str.replace(' ', '_')
role = cgc['ROLE_IN_CANCER'].fillna('')
oncogenes = cgc[role.str.contains('oncogene')]
tumor_suppressors = cgc[role.str.contains('TSG')]

处理 VCF 文件（GRCh38 坐标；使用 fetch 需要 bgzip 压缩和 tabix 索引）：

import pysam

vcf = pysam.VariantFile(glob.glob('Cosmic_GenomeScreensMutant*GRCh38*.vcf.gz')[0])
for record in vcf.fetch('17', 7668400, 7687500):  # TP53 locus, GRCh38
    print(record.id, record.ref, record.alts, record.info)

数据参考

如需全面了解 COSMIC 数据结构、可用文件和字段说明，请参阅 references/cosmic_data_reference.md。该参考资料包括：

• 可用数据类型和文件的完整列表
• 各文件类型的详细字段说明
• 文件格式规范
• 常见文件路径和命名约定
• 数据更新计划和版本控制
• 引用信息

在以下情况下，请使用此参考资料：

• 探索 COSMIC 中有哪些可用数据
• 了解特定字段的含义
• 确定某种数据类型对应的正确文件路径
• 规划使用 COSMIC 数据的分析工作流

辅助函数

下载脚本包含用于常见操作的辅助函数：

获取常见文件路径

from scripts.download_cosmic import get_common_file_path

# Get path for mutations file
path = get_common_file_path('mutations', genome_assembly='GRCh38')
# Returns: 'grch38/cosmic/v104/Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar'

# Get path for gene census, pinned to an older release
path = get_common_file_path('gene_census', version='v103')
# Returns: 'grch38/cosmic/v103/Cosmic_CancerGeneCensus_Tsv_v103_GRCh38.tar'

可接受的 data_type 快捷项与上方“可用数据类型”表中的项目相同（signatures 返回 None——请使用 signatures 下载网站）。

故障排除

身份验证错误

• 确认电子邮件和密码正确
• 确保已在 cancer.sanger.ac.uk/cosmic 注册账户
• 检查你的使用场景是否需要商业许可

找不到文件／HTTP 400

• 根据下载页面核对存档路径（发布版本、产品名称、组装版本）
• 检查请求的发布版本是否存在（截至 2026-09，列出了 v101–v104）
• 旧教程中的旧名称（CosmicMutantExport.tsv.gz、cancer_gene_census.csv）和 GRCh38/cosmic/latest/... 路径不适用于当前服务
• 确认基因组组装版本（GRCh37 或 GRCh38）正确

大文件下载

• COSMIC 文件可能有数 GB 大小
• 确保磁盘空间充足
• 根据网络连接情况，下载可能需要几分钟
• 对于大文件，脚本会显示下载进度

商业用途

• 商业研发、商业产品／服务、患者服务或临床报告均需要 COSMIC 商业许可：https://www.cosmickb.org/licensing
• 学术（非营利）访问免费，但需要注册

与其他工具集成

COSMIC 数据可与以下工具很好地集成：

• 变异注释：VEP、ANNOVAR、SnpEff
• 特征分析：SigProfiler、deconstructSigs、MuSiCa
• 癌症基因组学：cBioPortal、OncoKB、CIViC
• 生物信息学：Bioconductor、TCGA 分析工具
• 数据科学：pandas、scikit-learn、PyTorch

更多资源

• COSMIC 网站：https://cancer.sanger.ac.uk/cosmic
• 文档：https://cancer.sanger.ac.uk/cosmic/help
• 发布说明：https://cancer.sanger.ac.uk/cosmic/release_notes
• 下载页面（产品、校验和、脚本下载帮助）：https://cancer.sanger.ac.uk/cosmic/download/cosmic
• 突变特征：https://cancer.sanger.ac.uk/signatures/downloads/
• 联系邮箱：[email protected]

引用

使用 COSMIC 数据时，请引用当前数据库论文： Sondka Z, Dhir NB, Carvalho-Silva D, et al. COSMIC: a curated database of somatic variants and clinical data for cancer. Nucleic Acids Research. 2024;52(D1):D1210-D1217. doi:10.1093/nar/gkad986