Claude Skill

alterlab-cosmic

Access the COSMIC catalogue of somatic mutations in cancer to query somatic mutations, the Cancer Gene Census, mutational signatures, and gene fusions (authentication required). Use when curating known cancer driver genes, looking up recurrent somatic mutations in a gene, or inte

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download AlterLab-IEU-AlterLab-Academic-Skills-skills_databases_alterlab-cosmic-3ab6d03.zip · 22 KB

Install

skills CLI npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/databases/alterlab-cosmic
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
Git git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

COSMIC Database

Overview

COSMIC (Catalogue of Somatic Mutations in Cancer) is the world's largest and most comprehensive database for exploring somatic mutations in human cancer. Its mutational signature matrices download without a login; its product files (Cancer Gene Census, mutation exports, resistance mutations, fusions) and gene pages need a COSMIC login. This skill answers the common questions keylessly — signatures from COSMIC itself, and cancer genes, recurrent mutations, mutation frequencies and resistance evidence from open sources, each labelled with its source — and uses the COSMIC downloads when the user has a login.

When to Use This Skill

This skill should be used when:

  • Downloading cancer mutation data from COSMIC
  • Accessing the Cancer Gene Census for curated cancer gene lists
  • Retrieving mutational signature profiles
  • Querying structural variants, copy number alterations, or gene fusions
  • Analyzing drug resistance mutations
  • Working with cancer cell line genomics data
  • Integrating cancer mutation data into bioinformatics pipelines
  • Researching specific genes or mutations in cancer contexts

Does NOT Trigger

Scenario Use Instead
Germline variant pathogenicity (ACMG/AMP, ClinVar stars) alterlab-clinvar
Mutation frequency / OncoPrint / survival in TCGA or MSK cohorts via a keyless API alterlab-cbioportal
CRISPR/RNAi gene dependency in cancer cell lines alterlab-depmap
Population allele frequencies in non-cancer cohorts alterlab-gnomad

Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-clinvar) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.

Keyless Path (default — verified live 2026-10-22)

scripts/cosmic_open.py, standard library only:

Question Command Source (say it in the answer)
COSMIC SBS/DBS/ID/CN/SV signature definitions python scripts/cosmic_open.py signatures --type SBS --genome GRCh38 -o COSMIC_v3.6_SBS_GRCh38.txt (--list for all 99 matrices) COSMIC Mutational Signatures, v3.6 — COSMIC's own data, no login
Is gene X a cancer gene; oncogene or TSG? python scripts/cosmic_open.py genes --gene TP53 · genes --cgc-only --csv (581 genes: 208 ONCOGENE, 173 TSG, 29 both) OncoKB Cancer Gene List; its COSMIC CGC (v99) column flags CGC membership — a snapshot, not the current CGC, and without COSMIC's tiers
Recurrent (hotspot) mutations in a gene python scripts/cosmic_open.py hotspots BRAF (V600: 897 tumours, V600E 833) Cancer Hotspots (MSK; Chang et al. 2016/2018)
How often is a gene mutated across cancers; top protein changes (COSMIC-style pan-cancer view; one named cohort, OncoPrints or survival → alterlab-cbioportal) python scripts/cosmic_open.py mutations TP53 (32 TCGA PanCancer Atlas studies: 3,839 of 10,443 samples, 36.8%; R175H 150, R273C 125, R248Q 121) · --studies msk cBioPortal public API — cohort counts, not COSMIC sample counts
Which variants confer drug resistance python scripts/cosmic_open.py resistance --gene EGFR (43 accepted items) · --profile "EGFR T790M" (erlotinib, level A, NSCLC) CIViC curated predictive evidence
Germline / clinical significance hand off to alterlab-clinvar ClinVar

Do not present these as COSMIC counts or the current CGC: name the source, and say that the COSMIC product file needs a login when the user asks for COSMIC's own numbers.

Optional: COSMIC Login for Product Files

Account Registration

COSMIC product downloads need a login:

Python Requirements

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

Quick Start

COSMIC's current download service delivers each product as a .tar archive (the gzipped TSV or VCF plus a README describing every column) at an explicit release path, e.g. grch38/cosmic/v104/Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar. Scripted downloads are a two-step call: GET https://cancer.sanger.ac.uk/api/mono/products/v1/downloads/scripted?path=<archive path>&bucket=downloads with HTTP Basic auth (email:password) returns JSON with a signed url, which you then fetch without auth. The legacy /cosmic/file_download/... endpoint and legacy names such as CosmicMutantExport.tsv.gz or cancer_gene_census.csv no longer work for scripts — the old endpoint now redirects to the login page.

1. Basic File Download (login)

Use the scripts/download_cosmic.py script to download COSMIC data files. It reads COSMIC_EMAIL / COSMIC_PASSWORD (or the email argument and --password) and, without a login in a non-interactive shell, exits 2 naming those variables and the keyless script:

from scripts.download_cosmic import download_cosmic_file, get_common_file_path

# Cancer Gene Census, current release (v104), GRCh38
download_cosmic_file(
    email="your_email@institution.edu",
    password="your_password",
    filepath=get_common_file_path("gene_census"),
    # = "grch38/cosmic/v104/Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar"
)

2. Command-Line Usage

# Download using shorthand data type (prompts for the password on a terminal)
python scripts/download_cosmic.py user@email.com --data-type mutations
COSMIC_EMAIL=... COSMIC_PASSWORD=... python scripts/download_cosmic.py --data-type gene_census

# Download a specific archive path
python scripts/download_cosmic.py user@email.com \
    --filepath grch38/cosmic/v104/Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar

# GRCh37 and/or a pinned release
python scripts/download_cosmic.py user@email.com \
    --data-type gene_census --assembly GRCh37 --version v103

If the scripted endpoint changes, copy the command shown under Scripted download for any file on https://cancer.sanger.ac.uk/cosmic/download/cosmic and set COSMIC_SCRIPTED_URL.

3. Working with Downloaded Data

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])

Available Data Types

Every data type downloads through the same download_cosmic_file(...) call shown in Quick Start — only the filepath changes. Use the --data-type shortcut (CLI) or get_common_file_path(...) (Python) to build the path, or pass the filepath directly. See references/cosmic_data_reference.md for full field descriptions.

Data type Shortcut Archive (grch38/cosmic/v104/…, verified 2026-09)
Coding mutations, genome-wide screens (WGS/WES) mutations Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar
Coding mutations, targeted screens targeted_mutations Cosmic_CompleteTargetedScreensMutant_Tsv_v104_GRCh38.tar
Coding mutations (VCF) mutations_vcf VCF/Cosmic_GenomeScreensMutant_Vcf_v104_GRCh38.tar
Non-coding variants (VCF) non_coding_vcf VCF/Cosmic_NonCodingVariants_Vcf_v104_GRCh38.tar
Mutations in CGC genes mutation_census Cosmic_MutantCensus_Tsv_v104_GRCh38.tar
Cancer Gene Census gene_census Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar
Resistance mutations resistance_mutations Cosmic_ResistanceMutations_Tsv_v104_GRCh38.tar
Structural variants / breakpoints structural_variants / breakpoints Cosmic_StructuralVariants_Tsv_… / Cosmic_Breakpoints_Tsv_…
Gene fusions fusion_genes Cosmic_Fusion_Tsv_v104_GRCh38.tar
Copy number copy_number Cosmic_CompleteCNA_Tsv_v104_GRCh38.tar
Gene expression gene_expression Cosmic_CompleteGeneExpression_Tsv_v104_GRCh38.tar
Samples / tumour classification sample_info / classification Cosmic_Sample_Tsv_… / Cosmic_Classification_Tsv_…
Mutational signatures signatures separate site, no login — https://cancer.sanger.ac.uk/signatures/downloads/ (cosmic_open.py signatures)

Notes:

  • Cancer Gene Census is the expert-curated list of cancer genes; its role-in-cancer field splits oncogenes from tumor suppressors (TSG), and Tier 1/2 grades the evidence.
  • The old single "all coding mutations" export is now split into genome-wide and targeted-screen files; combine both for full coverage.
  • Mutational signatures (SBS, DBS, ID, CN, SV; current reference set v3.6, May 2026) are downloaded from the signatures site without a login, not through the product archives: cosmic_open.py signatures resolves the current file URL (e.g. .../signatures/documents/2173/COSMIC_v3.6_SBS_GRCh38.txt, 96 contexts × SBS columns).
  • Each product page lists sha256/md5 checksums — verify large downloads.

Working with COSMIC Data

Genome Assemblies

COSMIC provides data for two reference genomes:

  • GRCh38 (recommended, current standard)
  • GRCh37 (legacy, for older pipelines)

Specify the assembly in file paths (lower-case directory, upper-case suffix):

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

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

Versioning

  • Archive paths carry an explicit release (v104 = May 2026); the download service lists only versioned paths, so pin one — get_common_file_path() defaults to the current release
  • COSMIC ships two releases a year (May and November: v101 2024-11, v102 2025-05, v103 2025-11, v104 2026-05); check the release notes before assuming
  • For reproducible research, pin the release and record it alongside your results

File Formats

  • TSV/CSV: Tab/comma-separated, gzip compressed, read with pandas
  • VCF: Standard variant format, use with pysam, bcftools, or GATK
  • All files include headers describing column contents

Common Analysis Patterns

Current files use upper-case column names (e.g. GENE_SYMBOL, SAMPLE_NAME), while tumour site/histology live in the sample/classification tables linked by COSMIC IDs. Confirm exact names in each archive's README before filtering. For a one-off slice (one gene, primary site, or sample) the web Filtered download option avoids pulling the multi-GB files at all.

Filter mutations by gene:

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']

Identify cancer genes by role (normalize headers, then look up the role column):

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')]

Work with VCF files (GRCh38 coordinates, bgzip + tabix index required for fetch):

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)

Data Reference

For comprehensive information about COSMIC data structure, available files, and field descriptions, see references/cosmic_data_reference.md. This reference includes:

  • Complete list of available data types and files
  • Detailed field descriptions for each file type
  • File format specifications
  • Common file paths and naming conventions
  • Data update schedule and versioning
  • Citation information

Use this reference when:

  • Exploring what data is available in COSMIC
  • Understanding specific field meanings
  • Determining the correct file path for a data type
  • Planning analysis workflows with COSMIC data

Helper Functions

The download script includes helper functions for common operations:

Get Common File Paths

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'

The accepted data_type shortcuts are the ones in the Available Data Types table above (signatures returns None — use the signatures download site).

Troubleshooting

Authentication Errors (login path)

  • HTTP 401 from the scripted-download endpoint means the login was rejected
  • Verify email and password are correct
  • Ensure account is registered at cancer.sanger.ac.uk/cosmic
  • Check if commercial license is required for your use case

File Not Found / HTTP 400

  • Verify the archive path against the download page (release, product name, assembly)
  • Check that the requested release exists (v101–v104 are listed as of 2026-09)
  • Legacy names (CosmicMutantExport.tsv.gz, cancer_gene_census.csv) and GRCh38/cosmic/latest/... paths from older tutorials are not in the current service
  • Confirm genome assembly (GRCh37 vs GRCh38) is correct

Large File Downloads

  • COSMIC files can be several GB in size
  • Ensure sufficient disk space
  • Download may take several minutes depending on connection
  • The script shows download progress for large files

Commercial Use

  • Commercial R&D, commercial products/services, and patient services or clinical reporting require a COSMIC commercial licence: https://www.cosmickb.org/licensing
  • Academic (not-for-profit) access is free but requires registration

Integration with Other Tools

COSMIC data integrates well with:

  • Variant annotation: VEP, ANNOVAR, SnpEff
  • Signature analysis: SigProfiler, deconstructSigs, MuSiCa
  • Cancer genomics: cBioPortal, OncoKB, CIViC
  • Bioinformatics: Bioconductor, TCGA analysis tools
  • Data science: pandas, scikit-learn, PyTorch

Additional Resources

Citation

When using COSMIC data, cite the current database paper: 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

Files (alterlab-academic-skills)
  • evals
    • evals.json 7.8 KB
      Loading…
  • references
    • cosmic_data_reference.md 8.7 KB
      Loading…
  • scripts
    • cosmic_open.py 13.4 KB
      Loading…
    • download_cosmic.py 11.6 KB
      Loading…
  • SKILL.md 17.4 KB
    ---
    name: alterlab-cosmic
    description: Work with COSMIC, the catalogue of somatic mutations in cancer — COSMIC mutational signature matrices (no login), keyless cancer-gene, hotspot, somatic-mutation-frequency and drug-resistance answers from open sources (OncoKB gene list with COSMIC CGC membership, Cancer Hotspots, cBioPortal, CIViC), and, with an optional COSMIC login, the Cancer Gene Census, mutation exports, fusions and resistance files. Use when curating known cancer driver genes, looking up recurrent somatic mutations in a gene, or interpreting mutational signatures for cancer research and precision oncology. Not for germline pathogenicity calls (use alterlab-clinvar) or interactive cohort visualization like OncoPrints and survival from study data (use alterlab-cbioportal). Part of the AlterLab Academic Skills suite.
    license: MIT
    allowed-tools: Read WebFetch Bash(curl:*) Bash(python:*)
    compatibility: No API key or login required for the keyless path — COSMIC signature matrices plus OncoKB, Cancer Hotspots, cBioPortal and CIViC public APIs via scripts/cosmic_open.py (standard library). COSMIC product files (CGC, mutation exports, resistance, fusions) are an optional extra with a COSMIC login (free for academic use; commercial/clinical terms at cosmickb.org/licensing).
    metadata:
        skill-author: AlterLab
        version: "1.2.0"
        last_updated: "2026-10-22"
        credentials: "optional: COSMIC_EMAIL, COSMIC_PASSWORD (a COSMIC login for the full product downloads — Cancer Gene Census, mutation exports, resistance mutations, fusions; everything else runs keyless)"
    ---
    
    # COSMIC Database
    
    ## Overview
    
    COSMIC (Catalogue of Somatic Mutations in Cancer) is the world's largest and most comprehensive database for exploring somatic mutations in human cancer. Its **mutational signature matrices download without a login**; its product files (Cancer Gene Census, mutation exports, resistance mutations, fusions) and gene pages need a COSMIC login. This skill answers the common questions **keylessly** — signatures from COSMIC itself, and cancer genes, recurrent mutations, mutation frequencies and resistance evidence from open sources, each labelled with its source — and uses the COSMIC downloads when the user has a login.
    
    ## When to Use This Skill
    
    This skill should be used when:
    - Downloading cancer mutation data from COSMIC
    - Accessing the Cancer Gene Census for curated cancer gene lists
    - Retrieving mutational signature profiles
    - Querying structural variants, copy number alterations, or gene fusions
    - Analyzing drug resistance mutations
    - Working with cancer cell line genomics data
    - Integrating cancer mutation data into bioinformatics pipelines
    - Researching specific genes or mutations in cancer contexts
    
    ### Does NOT Trigger
    
    | Scenario | Use Instead |
    |----------|-------------|
    | Germline variant pathogenicity (ACMG/AMP, ClinVar stars) | `alterlab-clinvar` |
    | Mutation frequency / OncoPrint / survival in TCGA or MSK cohorts via a keyless API | `alterlab-cbioportal` |
    | CRISPR/RNAi gene dependency in cancer cell lines | `alterlab-depmap` |
    | Population allele frequencies in non-cancer cohorts | `alterlab-gnomad` |
    
    **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-clinvar`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
    
    ## Keyless Path (default — verified live 2026-10-22)
    
    `scripts/cosmic_open.py`, standard library only:
    
    | Question | Command | Source (say it in the answer) |
    |----------|---------|-------------------------------|
    | COSMIC SBS/DBS/ID/CN/SV signature definitions | `python scripts/cosmic_open.py signatures --type SBS --genome GRCh38 -o COSMIC_v3.6_SBS_GRCh38.txt` (`--list` for all 99 matrices) | COSMIC Mutational Signatures, v3.6 — COSMIC's own data, no login |
    | Is gene X a cancer gene; oncogene or TSG? | `python scripts/cosmic_open.py genes --gene TP53` · `genes --cgc-only --csv` (581 genes: 208 ONCOGENE, 173 TSG, 29 both) | OncoKB Cancer Gene List; its `COSMIC CGC (v99)` column flags CGC membership — a snapshot, not the current CGC, and without COSMIC's tiers |
    | Recurrent (hotspot) mutations in a gene | `python scripts/cosmic_open.py hotspots BRAF` (V600: 897 tumours, V600E 833) | Cancer Hotspots (MSK; Chang et al. 2016/2018) |
    | How often is a gene mutated across cancers; top protein changes (COSMIC-style pan-cancer view; one named cohort, OncoPrints or survival → `alterlab-cbioportal`) | `python scripts/cosmic_open.py mutations TP53` (32 TCGA PanCancer Atlas studies: 3,839 of 10,443 samples, 36.8%; R175H 150, R273C 125, R248Q 121) · `--studies msk` | cBioPortal public API — cohort counts, not COSMIC sample counts |
    | Which variants confer drug resistance | `python scripts/cosmic_open.py resistance --gene EGFR` (43 accepted items) · `--profile "EGFR T790M"` (erlotinib, level A, NSCLC) | CIViC curated predictive evidence |
    | Germline / clinical significance | hand off to `alterlab-clinvar` | ClinVar |
    
    Do not present these as COSMIC counts or the current CGC: name the source, and say that the
    COSMIC product file needs a login when the user asks for COSMIC's own numbers.
    
    ## Optional: COSMIC Login for Product Files
    
    ### Account Registration
    COSMIC product downloads need a login:
    - **Academic users**: Free access with registration at https://cancer.sanger.ac.uk/cosmic/register
    - **Commercial users**: A COSMIC commercial licence is required for commercial R&D, products/services, and patient services or clinical reporting — see https://www.cosmickb.org/licensing
    
    ### Python Requirements
    ```bash
    uv pip install requests pandas
    # pysam is only needed if you read the VCF-format downloads
    uv pip install pysam
    ```
    
    ## Quick Start
    
    COSMIC's current download service delivers each product as a `.tar` archive (the
    gzipped TSV or VCF plus a README describing every column) at an explicit release path,
    e.g. `grch38/cosmic/v104/Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar`. Scripted
    downloads are a two-step call: `GET https://cancer.sanger.ac.uk/api/mono/products/v1/downloads/scripted?path=<archive path>&bucket=downloads`
    with HTTP Basic auth (email:password) returns JSON with a signed `url`, which you then
    fetch without auth. The legacy `/cosmic/file_download/...` endpoint and legacy names such
    as `CosmicMutantExport.tsv.gz` or `cancer_gene_census.csv` no longer work for scripts —
    the old endpoint now redirects to the login page.
    
    ### 1. Basic File Download (login)
    
    Use the `scripts/download_cosmic.py` script to download COSMIC data files. It reads
    `COSMIC_EMAIL` / `COSMIC_PASSWORD` (or the email argument and `--password`) and, without a
    login in a non-interactive shell, exits 2 naming those variables and the keyless script:
    
    ```python
    from scripts.download_cosmic import download_cosmic_file, get_common_file_path
    
    # Cancer Gene Census, current release (v104), GRCh38
    download_cosmic_file(
        email="your_email@institution.edu",
        password="your_password",
        filepath=get_common_file_path("gene_census"),
        # = "grch38/cosmic/v104/Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar"
    )
    ```
    
    ### 2. Command-Line Usage
    
    ```bash
    # Download using shorthand data type (prompts for the password on a terminal)
    python scripts/download_cosmic.py user@email.com --data-type mutations
    COSMIC_EMAIL=... COSMIC_PASSWORD=... python scripts/download_cosmic.py --data-type gene_census
    
    # Download a specific archive path
    python scripts/download_cosmic.py user@email.com \
        --filepath grch38/cosmic/v104/Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar
    
    # GRCh37 and/or a pinned release
    python scripts/download_cosmic.py user@email.com \
        --data-type gene_census --assembly GRCh37 --version v103
    ```
    
    If the scripted endpoint changes, copy the command shown under **Scripted download**
    for any file on https://cancer.sanger.ac.uk/cosmic/download/cosmic and set
    `COSMIC_SCRIPTED_URL`.
    
    ### 3. Working with Downloaded Data
    
    ```bash
    tar -xf Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar   # -> gzipped TSV + README
    ```
    
    ```python
    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])
    ```
    
    ## Available Data Types
    
    Every data type downloads through the same `download_cosmic_file(...)` call shown
    in Quick Start — only the `filepath` changes. Use the `--data-type` shortcut (CLI)
    or `get_common_file_path(...)` (Python) to build the path, or pass the filepath
    directly. See `references/cosmic_data_reference.md` for full field descriptions.
    
    | Data type                     | Shortcut               | Archive (`grch38/cosmic/v104/…`, verified 2026-09) |
    |-------------------------------|------------------------|---------------------------------------------------|
    | Coding mutations, genome-wide screens (WGS/WES) | `mutations` | `Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar` |
    | Coding mutations, targeted screens | `targeted_mutations` | `Cosmic_CompleteTargetedScreensMutant_Tsv_v104_GRCh38.tar` |
    | Coding mutations (VCF)        | `mutations_vcf`        | `VCF/Cosmic_GenomeScreensMutant_Vcf_v104_GRCh38.tar` |
    | Non-coding variants (VCF)     | `non_coding_vcf`       | `VCF/Cosmic_NonCodingVariants_Vcf_v104_GRCh38.tar` |
    | Mutations in CGC genes        | `mutation_census`      | `Cosmic_MutantCensus_Tsv_v104_GRCh38.tar`        |
    | Cancer Gene Census            | `gene_census`          | `Cosmic_CancerGeneCensus_Tsv_v104_GRCh38.tar`    |
    | Resistance mutations          | `resistance_mutations` | `Cosmic_ResistanceMutations_Tsv_v104_GRCh38.tar` |
    | Structural variants / breakpoints | `structural_variants` / `breakpoints` | `Cosmic_StructuralVariants_Tsv_…` / `Cosmic_Breakpoints_Tsv_…` |
    | Gene fusions                  | `fusion_genes`         | `Cosmic_Fusion_Tsv_v104_GRCh38.tar`              |
    | Copy number                   | `copy_number`          | `Cosmic_CompleteCNA_Tsv_v104_GRCh38.tar`         |
    | Gene expression               | `gene_expression`      | `Cosmic_CompleteGeneExpression_Tsv_v104_GRCh38.tar` |
    | Samples / tumour classification | `sample_info` / `classification` | `Cosmic_Sample_Tsv_…` / `Cosmic_Classification_Tsv_…` |
    | Mutational signatures         | `signatures`           | separate site, no login — https://cancer.sanger.ac.uk/signatures/downloads/ (`cosmic_open.py signatures`) |
    
    Notes:
    - **Cancer Gene Census** is the expert-curated list of cancer genes; its role-in-cancer
      field splits oncogenes from tumor suppressors (TSG), and Tier 1/2 grades the evidence.
    - The old single "all coding mutations" export is now split into genome-wide and
      targeted-screen files; combine both for full coverage.
    - **Mutational signatures** (SBS, DBS, ID, CN, SV; current reference set v3.6, May 2026)
      are downloaded from the signatures site without a login, not through the product
      archives: `cosmic_open.py signatures` resolves the current file URL (e.g.
      `.../signatures/documents/2173/COSMIC_v3.6_SBS_GRCh38.txt`, 96 contexts × SBS columns).
    - Each product page lists sha256/md5 checksums — verify large downloads.
    
    ## Working with COSMIC Data
    
    ### Genome Assemblies
    COSMIC provides data for two reference genomes:
    - **GRCh38** (recommended, current standard)
    - **GRCh37** (legacy, for older pipelines)
    
    Specify the assembly in file paths (lower-case directory, upper-case suffix):
    ```python
    # GRCh38 (recommended)
    filepath = "grch38/cosmic/v104/Cosmic_GenomeScreensMutant_Tsv_v104_GRCh38.tar"
    
    # GRCh37 (legacy)
    filepath = "grch37/cosmic/v104/Cosmic_GenomeScreensMutant_Tsv_v104_GRCh37.tar"
    ```
    
    ### Versioning
    - Archive paths carry an explicit release (`v104` = May 2026); the download service
      lists only versioned paths, so pin one — `get_common_file_path()` defaults to the
      current release
    - COSMIC ships two releases a year (May and November: v101 2024-11, v102 2025-05,
      v103 2025-11, v104 2026-05); check the
      [release notes](https://cancer.sanger.ac.uk/cosmic/release_notes) before assuming
    - For reproducible research, pin the release and record it alongside your results
    
    ### File Formats
    - **TSV/CSV**: Tab/comma-separated, gzip compressed, read with pandas
    - **VCF**: Standard variant format, use with pysam, bcftools, or GATK
    - All files include headers describing column contents
    
    ### Common Analysis Patterns
    
    Current files use upper-case column names (e.g. `GENE_SYMBOL`, `SAMPLE_NAME`), while
    tumour site/histology live in the sample/classification tables linked by COSMIC IDs.
    Confirm exact names in each archive's README before filtering. For a one-off slice (one
    gene, primary site, or sample) the web **Filtered download** option avoids pulling the
    multi-GB files at all.
    
    **Filter mutations by gene**:
    ```python
    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']
    ```
    
    **Identify cancer genes by role** (normalize headers, then look up the role column):
    ```python
    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')]
    ```
    
    **Work with VCF files** (GRCh38 coordinates, bgzip + tabix index required for `fetch`):
    ```python
    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)
    ```
    
    ## Data Reference
    
    For comprehensive information about COSMIC data structure, available files, and field descriptions, see `references/cosmic_data_reference.md`. This reference includes:
    
    - Complete list of available data types and files
    - Detailed field descriptions for each file type
    - File format specifications
    - Common file paths and naming conventions
    - Data update schedule and versioning
    - Citation information
    
    Use this reference when:
    - Exploring what data is available in COSMIC
    - Understanding specific field meanings
    - Determining the correct file path for a data type
    - Planning analysis workflows with COSMIC data
    
    ## Helper Functions
    
    The download script includes helper functions for common operations:
    
    ### Get Common File Paths
    ```python
    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'
    ```
    
    The accepted `data_type` shortcuts are the ones in the Available Data Types table above
    (`signatures` returns `None` — use the signatures download site).
    
    ## Troubleshooting
    
    ### Authentication Errors (login path)
    - HTTP 401 from the scripted-download endpoint means the login was rejected
    - Verify email and password are correct
    - Ensure account is registered at cancer.sanger.ac.uk/cosmic
    - Check if commercial license is required for your use case
    
    ### File Not Found / HTTP 400
    - Verify the archive path against the download page (release, product name, assembly)
    - Check that the requested release exists (v101–v104 are listed as of 2026-09)
    - Legacy names (`CosmicMutantExport.tsv.gz`, `cancer_gene_census.csv`) and
      `GRCh38/cosmic/latest/...` paths from older tutorials are not in the current service
    - Confirm genome assembly (GRCh37 vs GRCh38) is correct
    
    ### Large File Downloads
    - COSMIC files can be several GB in size
    - Ensure sufficient disk space
    - Download may take several minutes depending on connection
    - The script shows download progress for large files
    
    ### Commercial Use
    - Commercial R&D, commercial products/services, and patient services or clinical
      reporting require a COSMIC commercial licence: https://www.cosmickb.org/licensing
    - Academic (not-for-profit) access is free but requires registration
    
    ## Integration with Other Tools
    
    COSMIC data integrates well with:
    - **Variant annotation**: VEP, ANNOVAR, SnpEff
    - **Signature analysis**: SigProfiler, deconstructSigs, MuSiCa
    - **Cancer genomics**: cBioPortal, OncoKB, CIViC
    - **Bioinformatics**: Bioconductor, TCGA analysis tools
    - **Data science**: pandas, scikit-learn, PyTorch
    
    ## Additional Resources
    
    - **COSMIC Website**: https://cancer.sanger.ac.uk/cosmic
    - **Documentation**: https://cancer.sanger.ac.uk/cosmic/help
    - **Release Notes**: https://cancer.sanger.ac.uk/cosmic/release_notes
    - **Download page (products, checksums, scripted-download help)**: https://cancer.sanger.ac.uk/cosmic/download/cosmic
    - **Mutational signatures**: https://cancer.sanger.ac.uk/signatures/downloads/
    - **Contact**: cosmic@sanger.ac.uk
    
    ## Citation
    
    When using COSMIC data, cite the current database paper:
    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
    
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.