domains / research / cosmic-data-download / cosmic-database

cosmic-database

Skill card

combined

Both copies describe the same COSMIC download workflow, but the FreedomIntelligence copy adds material steps and constraints the aipoch copy lacks: command-line usage with --data-type and --assembly flags, an output_filename parameter, a list of available data types (fusions, copy number, resistance), genome assembly guidance (GRCh37 vs GRCh38), versioning notes, and pysam for VCF. The aipoch copy adds a py_compile validation step and a references/ pointer. Because each has steps the other lacks, crowning one would hide a real alternative.

Repositories

Other copies

Combined skill

---
name: cosmic-database
description: Access COSMIC to download mutation datasets, query Cancer Gene Census, and retrieve mutational signatures for genomic analysis. Requires authentication.
---

# COSMIC Database Skill

## When to Use
- Downloading COSMIC mutation exports (TSV/VCF) for cohort or sample-level variant analysis.
- Retrieving Cancer Gene Census (CGC) gene lists for oncogene/tumor suppressor annotation.
- Working with COSMIC mutational signatures (SBS/DBS/ID) for signature attribution.
- Accessing additional COSMIC datasets (copy number, fusions, expression, resistance mutations).
- Building reproducible pipelines that programmatically fetch COSMIC releases.

## Prerequisites
- A registered COSMIC account at https://cancer.sanger.ac.uk/cosmic (academic free; commercial license required).
- Python 3.9+ (3.10+ recommended).
- Install dependencies: `uv pip install requests pandas` (or `pip install requests pandas`).
- For VCF parsing, install `pysam` or use `bcftools`/`GATK`.

## Quick Start

### 1. Validate the Script
```bash
python -m py_compile scripts/download_cosmic.py
python scripts/download_cosmic.py --help
```

### 2. Basic File Download (Python API)
```python
from scripts.download_cosmic import download_cosmic_file

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

### 3. Command-Line Usage
```bash
# 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
```

## Available Data Types
- `mutations` - Complete coding mutations (TSV format).
- `mutations_vcf` - Coding mutations in VCF format.
- `sample_info` - Sample metadata and tumor information.
- `gene_census` - Cancer Gene Census (~700+ curated cancer genes).
- `structural_variants` - Structural breakpoints.
- `fusion_genes` - Gene fusion events.
- `copy_number` - Copy number gains/losses.
- `gene_expression` - Over/under-expression data.
- Resistance mutations - Drug resistance mutation data with clinical annotations.

## Working with Downloaded Data
```python
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')
```

## Genome Assemblies and Versioning
- **GRCh38** (recommended, current standard) and **GRCh37** (legacy).
- Use `latest` in file paths for the most recent release, or a specific version (e.g., `v102`) for reproducibility.
- COSMIC is updated quarterly.

## File Formats
- **TSV/CSV**: Tab/comma-separated, gzip compressed, read with pandas.
- **VCF**: Standard variant format, use with pysam, bcftools, or GATK.

## Conflicts
- aipoch/medical-research-skills specifies Python 3.10+ and no pinned third-party packages; FreedomIntelligence/OpenClaw-Medical-Skills specifies Python 3.9+ and `uv pip install requests pandas`.
- aipoch/medical-research-skills includes a `py_compile` validation step; FreedomIntelligence/OpenClaw-Medical-Skills does not.
- FreedomIntelligence/OpenClaw-Medical-Skills documents command-line flags and an `output_filename` parameter; aipoch/medical-research-skills only shows `--help` and a generic run plan.

## Reference
- See `references/cosmic_data_reference.md` for dataset field definitions and COSMIC file specifics.