Get the FREE Ultimate OpenClaw Setup Guide →

cosmic-database

Scanned
npx machina-cli add skill Microck/ordinary-claude-skills/cosmic-database --openclaw
Files (1)
SKILL.md
9.7 KB

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. Access COSMIC's extensive collection of cancer genomics data, including millions of mutations across thousands of cancer types, curated gene lists, mutational signatures, and clinical annotations programmatically.

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

Prerequisites

Account Registration

COSMIC requires authentication for data downloads:

Python Requirements

uv pip install requests pandas

Quick Start

1. Basic File Download

Use the scripts/download_cosmic.py script to download COSMIC data files:

from scripts.download_cosmic import download_cosmic_file

# Download mutation data
download_cosmic_file(
    email="your_email@institution.edu",
    password="your_password",
    filepath="GRCh38/cosmic/latest/CosmicMutantExport.tsv.gz",
    output_filename="cosmic_mutations.tsv.gz"
)

2. Command-Line Usage

# Download using shorthand data type
python scripts/download_cosmic.py user@email.com --data-type mutations

# Download specific file
python scripts/download_cosmic.py user@email.com \
    --filepath GRCh38/cosmic/latest/cancer_gene_census.csv

# Download for specific genome assembly
python scripts/download_cosmic.py user@email.com \
    --data-type gene_census --assembly GRCh37 -o cancer_genes.csv

3. Working with Downloaded Data

import pandas as pd

# Read mutation data
mutations = pd.read_csv('cosmic_mutations.tsv.gz', sep='\t', compression='gzip')

# Read Cancer Gene Census
gene_census = pd.read_csv('cancer_gene_census.csv')

# Read VCF format
import pysam
vcf = pysam.VariantFile('CosmicCodingMuts.vcf.gz')

Available Data Types

Core Mutations

Download comprehensive mutation data including point mutations, indels, and genomic annotations.

Common data types:

  • mutations - Complete coding mutations (TSV format)
  • mutations_vcf - Coding mutations in VCF format
  • sample_info - Sample metadata and tumor information
# Download all coding mutations
download_cosmic_file(
    email="user@email.com",
    password="password",
    filepath="GRCh38/cosmic/latest/CosmicMutantExport.tsv.gz"
)

Cancer Gene Census

Access the expert-curated list of ~700+ cancer genes with substantial evidence of cancer involvement.

# Download Cancer Gene Census
download_cosmic_file(
    email="user@email.com",
    password="password",
    filepath="GRCh38/cosmic/latest/cancer_gene_census.csv"
)

Use cases:

  • Identifying known cancer genes
  • Filtering variants by cancer relevance
  • Understanding gene roles (oncogene vs tumor suppressor)
  • Target gene selection for research

Mutational Signatures

Download signature profiles for mutational signature analysis.

# Download signature definitions
download_cosmic_file(
    email="user@email.com",
    password="password",
    filepath="signatures/signatures.tsv"
)

Signature types:

  • Single Base Substitution (SBS) signatures
  • Doublet Base Substitution (DBS) signatures
  • Insertion/Deletion (ID) signatures

Structural Variants and Fusions

Access gene fusion data and structural rearrangements.

Available data types:

  • structural_variants - Structural breakpoints
  • fusion_genes - Gene fusion events
# Download gene fusions
download_cosmic_file(
    email="user@email.com",
    password="password",
    filepath="GRCh38/cosmic/latest/CosmicFusionExport.tsv.gz"
)

Copy Number and Expression

Retrieve copy number alterations and gene expression data.

Available data types:

  • copy_number - Copy number gains/losses
  • gene_expression - Over/under-expression data
# Download copy number data
download_cosmic_file(
    email="user@email.com",
    password="password",
    filepath="GRCh38/cosmic/latest/CosmicCompleteCNA.tsv.gz"
)

Resistance Mutations

Access drug resistance mutation data with clinical annotations.

# Download resistance mutations
download_cosmic_file(
    email="user@email.com",
    password="password",
    filepath="GRCh38/cosmic/latest/CosmicResistanceMutations.tsv.gz"
)

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:

# GRCh38 (recommended)
filepath="GRCh38/cosmic/latest/CosmicMutantExport.tsv.gz"

# GRCh37 (legacy)
filepath="GRCh37/cosmic/latest/CosmicMutantExport.tsv.gz"

Versioning

  • Use latest in file paths to always get the most recent release
  • COSMIC is updated quarterly (current version: v102, May 2025)
  • Specific versions can be used for reproducibility: v102, v101, etc.

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

Filter mutations by gene:

import pandas as pd

mutations = pd.read_csv('cosmic_mutations.tsv.gz', sep='\t', compression='gzip')
tp53_mutations = mutations[mutations['Gene name'] == 'TP53']

Identify cancer genes by role:

gene_census = pd.read_csv('cancer_gene_census.csv')
oncogenes = gene_census[gene_census['Role in Cancer'].str.contains('oncogene', na=False)]
tumor_suppressors = gene_census[gene_census['Role in Cancer'].str.contains('TSG', na=False)]

Extract mutations by cancer type:

mutations = pd.read_csv('cosmic_mutations.tsv.gz', sep='\t', compression='gzip')
lung_mutations = mutations[mutations['Primary site'] == 'lung']

Work with VCF files:

import pysam

vcf = pysam.VariantFile('CosmicCodingMuts.vcf.gz')
for record in vcf.fetch('17', 7577000, 7579000):  # TP53 region
    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/latest/CosmicMutantExport.tsv.gz'

# Get path for gene census
path = get_common_file_path('gene_census')
# Returns: 'GRCh38/cosmic/latest/cancer_gene_census.csv'

Available shortcuts:

  • mutations - Core coding mutations
  • mutations_vcf - VCF format mutations
  • gene_census - Cancer Gene Census
  • resistance_mutations - Drug resistance data
  • structural_variants - Structural variants
  • gene_expression - Expression data
  • copy_number - Copy number alterations
  • fusion_genes - Gene fusions
  • signatures - Mutational signatures
  • sample_info - Sample metadata

Troubleshooting

Authentication Errors

  • 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

  • Verify the filepath is correct
  • Check that the requested version exists
  • Use latest for the most recent version
  • 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

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: Tate JG, Bamford S, Jubb HC, et al. COSMIC: the Catalogue Of Somatic Mutations In Cancer. Nucleic Acids Research. 2019;47(D1):D941-D947.

Source

git clone https://github.com/Microck/ordinary-claude-skills/blob/main/skills_all/claude-scientific-skills/scientific-skills/cosmic-database/SKILL.mdView on GitHub

Overview

COSMIC is the world’s largest database of somatic mutations in cancer. This skill enables programmatic access to COSMIC data—mutations, Cancer Gene Census, mutational signatures, and gene fusions—for cancer research and precision oncology, with required authentication.

How This Skill Works

Authenticate with COSMIC and use Python scripts or CLI commands to download data via download_cosmic_file. Data can be loaded into pandas or pysam for downstream analysis, including mutations TSV/VCF files, gene census, and signature definitions.

When to Use It

  • Downloading COSMIC mutation data for pipelines and analyses
  • Accessing the Cancer Gene Census for curated cancer genes
  • Retrieving mutational signature profiles for signature-based analyses
  • Querying gene fusions and structural variants in cancer studies
  • Analyzing drug resistance mutations in cancer cell line data

Quick Start

  1. Step 1: Create a COSMIC account (academic-free registration or commercial license) at the COSMIC registration page.
  2. Step 2: Install dependencies (e.g., pip install requests pandas) and run the download_cosmic.py script with your credentials to fetch data (mutations, gene census, or signatures).
  3. Step 3: Load the downloaded files into pandas or pysam (e.g., CosmicMutantExport.tsv.gz, cancer_gene_census.csv) and begin your analysis.

Best Practices

  • Ensure you have a COSMIC account (academic access or commercial license) before downloads.
  • Prefer core data types (mutations, cancer_gene_census, signatures) for reproducible workflows.
  • Cache downloaded files and verify integrity with checksums when available.
  • Parse TSV/VCF formats with appropriate libraries (pandas, pysam) and use the correct genome assembly.
  • Document data provenance and assembly (GRCh38 vs GRCh37) for reproducibility.

Example Use Cases

  • Pipeline that downloads CosmicMutantExport.tsv.gz and annotates variants with Cancer Gene Census.
  • Cross-reference mutations with cancer_gene_census to identify known cancer genes.
  • Compare mutational signature profiles across tumor types using signatures.tsv.
  • Fetch cancer_gene_census and related data to prioritize target genes for research.
  • Integrate COSMIC data into a workflow to analyze drug resistance mutations in cancer cell lines.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗