cellme 1.0.0__py3-none-any.whl

cellme/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("cellme")

cellme/builds.py

@@ -0,0 +1,128 @@
+"""Human genome build definitions and their reference contig tables."""
+
+from enum import StrEnum
+
+
+class GenomeBuild(StrEnum):
+    """
+    A human reference genome build supported by cellme.
+
+    Only the two builds relevant to CCLE truth tracks are modeled: GRCh37, the
+    build that CCLE reports its coordinates against, and GRCh38, the current
+    human reference. The ``hg19`` and ``hg38`` aliases resolve to GRCh37 and
+    GRCh38 respectively when the enum is constructed from a string.
+    """
+
+    GRCh38 = "GRCh38"
+    GRCh37 = "GRCh37"
+
+    @classmethod
+    def _missing_(cls, value: object) -> "GenomeBuild | None":
+        """
+        Resolve the ``hg19`` and ``hg38`` aliases case-insensitively.
+
+        Args:
+            value: The value that did not match a canonical member name.
+
+        Returns:
+            The matching build for a known alias, otherwise None.
+        """
+        aliases = {"hg38": cls.GRCh38, "hg19": cls.GRCh37}
+        if isinstance(value, str):
+            return aliases.get(value.lower())
+        return None
+
+    @property
+    def ucsc_name(self) -> str:
+        """The UCSC-style assembly name used by liftover chain files."""
+        return {GenomeBuild.GRCh38: "hg38", GenomeBuild.GRCh37: "hg19"}[self]
+
+
+GRCH37_CONTIGS: tuple[tuple[str, int], ...] = (
+    ("1", 249250621),
+    ("2", 243199373),
+    ("3", 198022430),
+    ("4", 191154276),
+    ("5", 180915260),
+    ("6", 171115067),
+    ("7", 159138663),
+    ("8", 146364022),
+    ("9", 141213431),
+    ("10", 135534747),
+    ("11", 135006516),
+    ("12", 133851895),
+    ("13", 115169878),
+    ("14", 107349540),
+    ("15", 102531392),
+    ("16", 90354753),
+    ("17", 81195210),
+    ("18", 78077248),
+    ("19", 59128983),
+    ("20", 63025520),
+    ("21", 48129895),
+    ("22", 51304566),
+    ("X", 155270560),
+    ("Y", 59373566),
+    ("MT", 16569),
+)
+"""Primary-assembly contig names and lengths for GRCh37 (Ensembl naming)."""
+
+GRCH38_CONTIGS: tuple[tuple[str, int], ...] = (
+    ("1", 248956422),
+    ("2", 242193529),
+    ("3", 198295559),
+    ("4", 190214555),
+    ("5", 181538259),
+    ("6", 170805979),
+    ("7", 159345973),
+    ("8", 145138636),
+    ("9", 138394717),
+    ("10", 133797422),
+    ("11", 135086622),
+    ("12", 133275309),
+    ("13", 114364328),
+    ("14", 107043718),
+    ("15", 101991189),
+    ("16", 90338345),
+    ("17", 83257441),
+    ("18", 80373285),
+    ("19", 58617616),
+    ("20", 64444167),
+    ("21", 46709983),
+    ("22", 50818468),
+    ("X", 156040895),
+    ("Y", 57227415),
+    ("MT", 16569),
+)
+"""Primary-assembly contig names and lengths for GRCh38 (Ensembl naming)."""
+
+_CONTIGS_BY_BUILD: dict[GenomeBuild, tuple[tuple[str, int], ...]] = {
+    GenomeBuild.GRCh37: GRCH37_CONTIGS,
+    GenomeBuild.GRCh38: GRCH38_CONTIGS,
+}
+
+
+def contigs_for(build: GenomeBuild) -> tuple[tuple[str, int], ...]:
+    """
+    Return the ordered primary-assembly contigs for a build.
+
+    Args:
+        build: The genome build to look up.
+
+    Returns:
+        A tuple of (contig name, length) pairs in canonical karyotype order.
+    """
+    return _CONTIGS_BY_BUILD[build]
+
+
+def contig_order(build: GenomeBuild) -> dict[str, int]:
+    """
+    Return a mapping from contig name to its sort index for a build.
+
+    Args:
+        build: The genome build to look up.
+
+    Returns:
+        A mapping from contig name to a zero-based rank in karyotype order.
+    """
+    return {name: index for index, (name, _length) in enumerate(contigs_for(build))}

cellme/cbioportal.py

@@ -0,0 +1,331 @@
+"""Client for the cBioPortal REST API and its CCLE mutation study."""
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+from rapidfuzz import fuzz
+from rapidfuzz import process
+
+CBIOPORTAL_API: str = "https://www.cbioportal.org/api"
+"""Base URL of the public cBioPortal REST API."""
+
+DEFAULT_STUDY: str = "ccle_broad_2019"
+"""The Cancer Cell Line Encyclopedia study used as the mutation source."""
+
+_REQUEST_TIMEOUT: float = 60.0
+"""Seconds to wait on any single cBioPortal request before giving up."""
+
+_MISSING_VALUES: frozenset[str] = frozenset({"", ".", "NA", "N/A", "NULL"})
+"""String placeholders that cBioPortal uses to mean a value is absent."""
+
+_SUGGESTION_LIMIT: int = 5
+"""How many close cell-line names to offer when a query does not resolve."""
+
+_SUGGESTION_SCORE_CUTOFF: float = 70.0
+"""The minimum rapidfuzz similarity, out of 100, for a name to be suggested."""
+
+_CHROMOSOME_ALIASES: dict[str, str] = {"23": "X", "24": "Y", "25": "MT", "M": "MT"}
+"""CCLE numeric chromosome codes mapped to their standard contig names."""
+
+
+class CellLineError(ValueError):
+    """Base class for failures to resolve a cell line query to a sample."""
+
+
+class CellLineNotFoundError(CellLineError):
+    """Raised when a query matches no cell line in the study."""
+
+
+class AmbiguousCellLineError(CellLineError):
+    """Raised when a query matches more than one cell line in the study."""
+
+
+@dataclass(frozen=True)
+class Mutation:
+    """
+    A single somatic mutation call for one cell line in the CCLE study.
+
+    The fields mirror the subset of the cBioPortal mutation record needed to
+    build a VCF record. Insertions and deletions follow the MAF convention in
+    which the absent allele is encoded as a single dash.
+    """
+
+    gene: str
+    entrez_gene_id: int | None
+    chromosome: str
+    start_position: int
+    end_position: int
+    reference_allele: str
+    variant_allele: str
+    protein_change: str | None
+    variant_class: str
+    variant_type: str
+    ncbi_build: str
+    refseq_mrna_id: str | None
+    protein_pos_start: int | None
+    protein_pos_end: int | None
+
+
+def _clean(value: object) -> str | None:
+    """
+    Normalize a cBioPortal string field, mapping placeholders to None.
+
+    Args:
+        value: The raw field value from the API response.
+
+    Returns:
+        The stripped string, or None when the value is missing or a placeholder.
+    """
+    if value is None:
+        return None
+    text = str(value).strip()
+    if text.upper() in _MISSING_VALUES:
+        return None
+    return text
+
+
+def normalize_cell_line(name: str) -> str:
+    """
+    Reduce a cell line name to an uppercase alphanumeric matching key.
+
+    This lets a user pass ``MOLT-4``, ``MOLT4``, or ``molt 4`` and have them all
+    compare equal to the leading token of a CCLE sample identifier.
+
+    Args:
+        name: A cell line name or CCLE sample identifier token.
+
+    Returns:
+        The name uppercased with every non-alphanumeric character removed.
+    """
+    return re.sub(r"[^0-9A-Za-z]", "", name).upper()
+
+
+def cell_line_name(sample_id: str) -> str:
+    """
+    Return the leading cell line token of a CCLE sample identifier.
+
+    CCLE sample identifiers join a cell line name to its tissue of origin with
+    underscores, for example ``MOLT4_HAEMATOPOIETIC_AND_LYMPHOID_TISSUE``.
+
+    Args:
+        sample_id: A CCLE sample identifier.
+
+    Returns:
+        The substring before the first underscore.
+    """
+    return sample_id.split("_", 1)[0]
+
+
+def humanize_cell_line(token: str) -> str:
+    """
+    Render a CCLE cell-line token in its conventional hyphenated form.
+
+    A token of a letter prefix followed by a trailing digit run is split with a
+    hyphen, so ``MOLT4`` becomes ``MOLT-4``. This is a light heuristic for
+    readability; tokens that do not fit that simple shape are returned unchanged.
+
+    Args:
+        token: The leading cell line token of a CCLE sample identifier.
+
+    Returns:
+        The token with a hyphen inserted before a trailing digit run when one
+        applies, otherwise the token unchanged.
+    """
+    match = re.fullmatch(r"([A-Za-z]+)(\d+)", token)
+    if match is None:
+        return token
+    return f"{match.group(1)}-{match.group(2)}"
+
+
+def suggest_cell_lines(
+    query: str,
+    sample_ids: Iterable[str],
+    *,
+    limit: int = _SUGGESTION_LIMIT,
+    score_cutoff: float = _SUGGESTION_SCORE_CUTOFF,
+) -> list[str]:
+    """
+    Return the closest CCLE cell-line names to a query by fuzzy similarity.
+
+    The query is compared against the unique leading cell-line token of every
+    sample, on their normalized alphanumeric form, using a Levenshtein-based
+    similarity. Only names scoring at or above the cutoff are kept, so a query
+    with no near neighbors yields an empty list.
+
+    Args:
+        query: The unresolved cell line identifier supplied by the user.
+        sample_ids: All sample identifiers available in the study.
+        limit: The maximum number of names to return.
+        score_cutoff: The minimum similarity, out of 100, to include a name.
+
+    Returns:
+        Up to ``limit`` human-friendly cell-line names, best match first.
+    """
+    display_names: list[str] = []
+    normalized_names: list[str] = []
+    seen: set[str] = set()
+    for sample_id in sample_ids:
+        token = cell_line_name(sample_id)
+        key = normalize_cell_line(token)
+        if key in seen:
+            continue
+        seen.add(key)
+        display_names.append(token)
+        normalized_names.append(key)
+
+    matches = process.extract(
+        normalize_cell_line(query),
+        normalized_names,
+        scorer=fuzz.ratio,
+        limit=limit,
+        score_cutoff=score_cutoff,
+    )
+    return [humanize_cell_line(display_names[index]) for _name, _score, index in matches]
+
+
+def resolve_sample(query: str, sample_ids: Iterable[str]) -> str:
+    """
+    Resolve a cell line query to a single CCLE sample identifier.
+
+    A query first tries to match a whole sample identifier, then falls back to
+    matching the leading cell line token, both compared on their normalized
+    alphanumeric form.
+
+    Args:
+        query: The cell line identifier supplied by the user.
+        sample_ids: All sample identifiers available in the study.
+
+    Returns:
+        The single matching sample identifier.
+
+    Raises:
+        CellLineNotFoundError: If no sample matches the query.
+        AmbiguousCellLineError: If more than one sample matches the query.
+    """
+    wanted = normalize_cell_line(query)
+    identifiers = list(sample_ids)
+
+    whole = [s for s in identifiers if normalize_cell_line(s) == wanted]
+    if len(whole) == 1:
+        return whole[0]
+
+    by_token = [s for s in identifiers if normalize_cell_line(cell_line_name(s)) == wanted]
+    if len(by_token) == 1:
+        return by_token[0]
+    if not by_token:
+        suggestions = suggest_cell_lines(query, identifiers)
+        if suggestions:
+            hint = "Did you mean: " + ", ".join(suggestions) + "?"
+        else:
+            hint = "No close matches."
+        raise CellLineNotFoundError(f"no CCLE cell line matched {query!r}. {hint}")
+    raise AmbiguousCellLineError(
+        f"Query {query!r} matched multiple cell lines: {', '.join(sorted(by_token))}."
+    )
+
+
+def _normalize_chromosome(chromosome: str) -> str:
+    """
+    Map a CCLE chromosome code to its standard contig name.
+
+    CCLE reports the sex and mitochondrial chromosomes with numeric codes, where
+    23 is X, 24 is Y, and 25 is the mitochondrion.
+
+    Args:
+        chromosome: The raw ``chr`` value from a cBioPortal record.
+
+    Returns:
+        The standard contig name, unchanged when no alias applies.
+    """
+    return _CHROMOSOME_ALIASES.get(chromosome, chromosome)
+
+
+def _mutation_from_record(record: dict[str, Any]) -> Mutation:
+    """
+    Build a Mutation from one cBioPortal mutation record.
+
+    Args:
+        record: A decoded JSON object from the mutations fetch endpoint.
+
+    Returns:
+        The parsed Mutation.
+    """
+    gene = record.get("gene") or {}
+    symbol = gene.get("hugoGeneSymbol") or record.get("hugoGeneSymbol") or ""
+    entrez = record.get("entrezGeneId")
+    if entrez is None:
+        entrez = gene.get("entrezGeneId")
+    return Mutation(
+        gene=symbol,
+        entrez_gene_id=int(entrez) if entrez is not None else None,
+        chromosome=_normalize_chromosome(str(record["chr"])),
+        start_position=int(record["startPosition"]),
+        end_position=int(record["endPosition"]),
+        reference_allele=str(record.get("referenceAllele") or ""),
+        variant_allele=str(record.get("variantAllele") or ""),
+        protein_change=_clean(record.get("proteinChange")),
+        variant_class=str(record.get("mutationType") or ""),
+        variant_type=str(record.get("variantType") or ""),
+        ncbi_build=str(record.get("ncbiBuild") or ""),
+        refseq_mrna_id=_clean(record.get("refseqMrnaId")),
+        protein_pos_start=record.get("proteinPosStart"),
+        protein_pos_end=record.get("proteinPosEnd"),
+    )
+
+
+def fetch_sample_ids(
+    study: str = DEFAULT_STUDY,
+    *,
+    session: requests.Session | None = None,
+    base_url: str = CBIOPORTAL_API,
+) -> list[str]:
+    """
+    Fetch every sample identifier in a cBioPortal study.
+
+    Args:
+        study: The cBioPortal study identifier.
+        session: An optional requests session to reuse a connection.
+        base_url: The base URL of the cBioPortal API.
+
+    Returns:
+        The sample identifiers reported by the study.
+    """
+    http = session or requests
+    response = http.get(f"{base_url}/studies/{study}/samples", timeout=_REQUEST_TIMEOUT)
+    response.raise_for_status()
+    return [str(sample["sampleId"]) for sample in response.json()]
+
+
+def fetch_mutations(
+    study: str,
+    sample_id: str,
+    *,
+    session: requests.Session | None = None,
+    base_url: str = CBIOPORTAL_API,
+) -> list[Mutation]:
+    """
+    Fetch all mutations for a single sample from a study's mutation profile.
+
+    Args:
+        study: The cBioPortal study identifier.
+        sample_id: The sample identifier to fetch mutations for.
+        session: An optional requests session to reuse a connection.
+        base_url: The base URL of the cBioPortal API.
+
+    Returns:
+        The parsed mutations for the sample.
+    """
+    http = session or requests
+    profile = f"{study}_mutations"
+    url = f"{base_url}/molecular-profiles/{profile}/mutations/fetch"
+    response = http.post(
+        url,
+        params={"projection": "DETAILED"},
+        json={"sampleIds": [sample_id]},
+        timeout=_REQUEST_TIMEOUT,
+    )
+    response.raise_for_status()
+    return [_mutation_from_record(record) for record in response.json()]

cellme/main.py

@@ -0,0 +1,34 @@
+import logging
+import sys
+from collections.abc import Callable
+
+import defopt
+
+from cellme.cbioportal import CellLineError
+from cellme.tools.truth_track import truth_track
+
+_tools: list[Callable[..., None]] = [
+    truth_track,
+]
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """Set up basic logging to print to the console."""
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(name)s:%(funcName)s:%(lineno)s [%(levelname)s]: %(message)s",
+    )
+
+
+def run() -> None:
+    """Set up logging, then hand over to defopt for running the command line tool."""
+    setup_logging()
+    logger = logging.getLogger("cellme")
+    logger.info("Executing: " + " ".join(sys.argv))
+    (command,) = _tools
+    try:
+        defopt.run(command, argv=sys.argv[1:], version=True)
+    except CellLineError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        raise SystemExit(1) from error
+    logger.info("Finished executing successfully.")

cellme/tools/truth_track.py

@@ -0,0 +1,77 @@
+"""The cellme command: resolve a cell line and write its truth-track VCF."""
+
+import logging
+from pathlib import Path
+
+import requests
+
+from cellme import __version__
+from cellme.builds import GenomeBuild
+from cellme.cbioportal import DEFAULT_STUDY
+from cellme.cbioportal import cell_line_name
+from cellme.cbioportal import fetch_mutations
+from cellme.cbioportal import fetch_sample_ids
+from cellme.cbioportal import resolve_sample
+from cellme.vcf import TrackContext
+from cellme.vcf import build_header
+from cellme.vcf import build_records
+from cellme.vcf import make_anchor_base
+from cellme.vcf import make_lifter
+from cellme.vcf import write_vcf
+
+logger = logging.getLogger("cellme")
+
+CCLE_BUILD: GenomeBuild = GenomeBuild.GRCh37
+"""CCLE reports its coordinates against GRCh37, the source build for lifting."""
+
+
+def truth_track(
+    query: str,
+    *,
+    build: GenomeBuild = GenomeBuild.GRCh38,
+    reference: Path | None = None,
+    output: Path | None = None,
+    study: str = DEFAULT_STUDY,
+) -> None:
+    """
+    Write a truth-track VCF of a human cell line's known CCLE mutations.
+
+    The query is resolved to a Cancer Cell Line Encyclopedia sample, its somatic
+    mutations are fetched from cBioPortal, and each is written as a VCF record on
+    the requested genome build. CCLE coordinates are GRCh37; when the target
+    build is GRCh38 every coordinate is lifted with a UCSC chain file.
+
+    Args:
+        query: Cell line identifier, e.g. MOLT-4, MOLT4, or a full CCLE sample id.
+        build: Target genome build for the emitted VCF.
+        reference: Reference FASTA for the target build, used only to place
+            spec-compliant anchor bases on insertions and deletions. Without it,
+            indel anchors use a placeholder N and are marked ANCHOR=placeholder.
+        output: Output VCF path. Writes to standard output when omitted.
+        study: cBioPortal study identifier to query.
+    """
+    with requests.Session() as session:
+        session.headers["User-Agent"] = f"cellme/{__version__}"
+        sample_ids = fetch_sample_ids(study, session=session)
+        sample_id = resolve_sample(query, sample_ids)
+        logger.info(f"Resolved {query!r} to CCLE sample {sample_id}")
+        mutations = fetch_mutations(study, sample_id, session=session)
+    logger.info(f"Fetched {len(mutations)} mutations for {sample_id}")
+
+    context = TrackContext(
+        cell_line=cell_line_name(sample_id),
+        sample_id=sample_id,
+        study=study,
+        source_build=CCLE_BUILD,
+        target_build=build,
+    )
+    lift_position = make_lifter(CCLE_BUILD, build)
+    anchor_base = make_anchor_base(reference)
+    records, dropped = build_records(
+        mutations, context, lift_position=lift_position, anchor_base=anchor_base
+    )
+    if dropped:
+        logger.warning(f"Dropped {dropped} mutations that could not be lifted to {build}")
+    header = build_header(context, __version__)
+    write_vcf(records, header, output)
+    logger.info(f"Wrote {len(records)} records for {context.cell_line} on {build}")

cellme/vcf.py

@@ -0,0 +1,472 @@
+"""Conversion of CCLE mutations into a sorted, well-described truth-track VCF."""
+
+from collections.abc import Callable
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+import pysam
+from liftover import get_lifter
+
+from cellme.builds import GenomeBuild
+from cellme.builds import contig_order
+from cellme.builds import contigs_for
+from cellme.cbioportal import Mutation
+
+LiftPosition = Callable[[str, int], int | None]
+"""A callable mapping a source (contig, 1-based position) to a lifted position."""
+
+AnchorBase = Callable[[str, int], str]
+"""A callable returning the single reference base at a (contig, 1-based position)."""
+
+_DASH: str = "-"
+"""The MAF sentinel for the absent allele of an insertion or deletion."""
+
+InfoValue = str | int | bool
+"""The value types cellme writes into a VCF INFO field."""
+
+
+@dataclass(frozen=True)
+class InfoField:
+    """A single INFO field definition used for both the header and records."""
+
+    key: str
+    number: str
+    type: str
+    description: str
+
+
+INFO_FIELDS: tuple[InfoField, ...] = (
+    InfoField("GENE", "1", "String", "HUGO gene symbol"),
+    InfoField(
+        "PROTEIN_CHANGE",
+        "1",
+        "String",
+        "Protein-level change in CCLE short form (HGVS p.-like), e.g. R306*",
+    ),
+    InfoField(
+        "VARIANT_CLASS",
+        "1",
+        "String",
+        "Variant classification (MAF-style), e.g. Missense_Mutation",
+    ),
+    InfoField(
+        "VARIANT_TYPE",
+        "1",
+        "String",
+        "Sequence alteration type reported by CCLE: SNP, DNP, INS, or DEL",
+    ),
+    InfoField("CELL_LINE", "1", "String", "Cell line resolved from the query"),
+    InfoField("SAMPLE_ID", "1", "String", "CCLE sample identifier for the cell line"),
+    InfoField("ENTREZ", "1", "Integer", "NCBI Entrez gene identifier"),
+    InfoField("REFSEQ", "1", "String", "RefSeq mRNA accession for the annotated transcript"),
+    InfoField("PROTEIN_POS", "1", "String", "Affected protein position or range, 1-based"),
+    InfoField(
+        "SOURCE",
+        "1",
+        "String",
+        "Source database and study, e.g. cBioPortal CCLE ccle_broad_2019",
+    ),
+    InfoField(
+        "ORIGINAL_BUILD",
+        "1",
+        "String",
+        "Genome build of the source coordinates before any liftover",
+    ),
+    InfoField(
+        "ORIGINAL_LOCUS",
+        "1",
+        "String",
+        "Original locus before liftover in UCSC position format (chrom:pos) on ORIGINAL_BUILD",
+    ),
+    InfoField(
+        "LIFTED",
+        "0",
+        "Flag",
+        "Coordinate was lifted from ORIGINAL_BUILD to the output reference build",
+    ),
+    InfoField(
+        "ANCHOR",
+        "1",
+        "String",
+        "Provenance of the indel anchor base: reference (from --reference) or placeholder (N)",
+    ),
+)
+"""The complete, ordered INFO schema emitted by cellme."""
+
+
+@dataclass(frozen=True)
+class TrackContext:
+    """The per-run context shared by every record in a truth-track VCF."""
+
+    cell_line: str
+    sample_id: str
+    study: str
+    source_build: GenomeBuild
+    target_build: GenomeBuild
+
+
+@dataclass(frozen=True)
+class VcfRecord:
+    """A single VCF record with its 1-based position and resolved alleles."""
+
+    contig: str
+    position: int
+    identifier: str | None
+    reference_allele: str
+    alternate_allele: str
+    info: dict[str, InfoValue]
+
+
+def _identifier(mutation: Mutation) -> str | None:
+    """
+    Build a stable, meaningful VCF identifier for a mutation.
+
+    Args:
+        mutation: The source mutation.
+
+    Returns:
+        A ``gene:proteinChange`` token when available, a ``gene:chrom:pos`` token
+        when only the gene is known, otherwise None.
+    """
+    if mutation.gene and mutation.protein_change:
+        return f"{mutation.gene}:{mutation.protein_change}"
+    if mutation.gene:
+        return f"{mutation.gene}:{mutation.chromosome}:{mutation.start_position}"
+    return None
+
+
+def _format_protein_position(mutation: Mutation) -> str | None:
+    """
+    Format the affected protein position or range for the PROTEIN_POS field.
+
+    Args:
+        mutation: The source mutation.
+
+    Returns:
+        A single position, a hyphenated range, or None when unknown.
+    """
+    start = mutation.protein_pos_start
+    end = mutation.protein_pos_end
+    if start is None:
+        return None
+    if end is None or end == start:
+        return str(start)
+    return f"{start}-{end}"
+
+
+def _original_locus(mutation: Mutation) -> str:
+    """
+    Format the pre-liftover locus in UCSC position syntax.
+
+    CCLE contigs arrive without a ``chr`` prefix, so one is added. A variant
+    spanning a single base is rendered as ``chrom:pos``; a wider variant is
+    rendered as the range ``chrom:start-end`` using the original coordinates.
+
+    Args:
+        mutation: The source mutation, on the source build.
+
+    Returns:
+        The UCSC-style locus string, for example ``chr17:7577022``.
+    """
+    if mutation.start_position == mutation.end_position:
+        return f"chr{mutation.chromosome}:{mutation.start_position}"
+    return f"chr{mutation.chromosome}:{mutation.start_position}-{mutation.end_position}"
+
+
+def _build_info(
+    mutation: Mutation,
+    context: TrackContext,
+    *,
+    lifted: bool,
+    anchor_source: str | None,
+) -> dict[str, InfoValue]:
+    """
+    Assemble the INFO mapping for one record from its mutation and context.
+
+    Args:
+        mutation: The source mutation.
+        context: The shared per-run context.
+        lifted: Whether the coordinate was lifted to the target build.
+        anchor_source: The indel anchor provenance, or None for substitutions.
+
+    Returns:
+        A mapping of INFO keys to values, omitting fields with no value.
+    """
+    info: dict[str, InfoValue] = {}
+    if mutation.gene:
+        info["GENE"] = mutation.gene
+    if mutation.protein_change:
+        info["PROTEIN_CHANGE"] = mutation.protein_change
+    if mutation.variant_class:
+        info["VARIANT_CLASS"] = mutation.variant_class
+    if mutation.variant_type:
+        info["VARIANT_TYPE"] = mutation.variant_type
+    info["CELL_LINE"] = context.cell_line
+    info["SAMPLE_ID"] = context.sample_id
+    if mutation.entrez_gene_id is not None:
+        info["ENTREZ"] = mutation.entrez_gene_id
+    if mutation.refseq_mrna_id:
+        info["REFSEQ"] = mutation.refseq_mrna_id
+    protein_position = _format_protein_position(mutation)
+    if protein_position is not None:
+        info["PROTEIN_POS"] = protein_position
+    info["SOURCE"] = f"cBioPortal CCLE {context.study}"
+    info["ORIGINAL_BUILD"] = str(context.source_build)
+    if lifted:
+        info["ORIGINAL_LOCUS"] = _original_locus(mutation)
+        info["LIFTED"] = True
+    if anchor_source is not None:
+        info["ANCHOR"] = anchor_source
+    return info
+
+
+def build_record(
+    mutation: Mutation,
+    context: TrackContext,
+    *,
+    lift_position: LiftPosition | None,
+    anchor_base: AnchorBase | None,
+) -> VcfRecord | None:
+    """
+    Convert one CCLE mutation into a VCF record on the target build.
+
+    Substitutions carry their CCLE alleles through unchanged. Insertions and
+    deletions are left-anchored: a deletion sits one base to the left of the
+    deleted sequence and an insertion at the base preceding the insertion point.
+    The anchoring position is computed in the source build, then lifted, so the
+    anchor base is read from the target reference when one is supplied.
+
+    Args:
+        mutation: The source mutation to convert.
+        context: The shared per-run context.
+        lift_position: A callable that lifts a source position to the target
+            build, or None when the source and target builds are the same.
+        anchor_base: A callable returning the target reference base for indel
+            anchoring, or None to use a placeholder ``N`` anchor.
+
+    Returns:
+        The converted record, or None when the mutation is malformed or its
+        coordinate cannot be lifted to the target build.
+    """
+    is_deletion = mutation.variant_allele == _DASH
+    is_insertion = mutation.reference_allele == _DASH
+    if is_deletion and is_insertion:
+        return None
+
+    if is_deletion:
+        source_position = mutation.start_position - 1
+        if source_position < 1:
+            return None
+    else:
+        source_position = mutation.start_position
+
+    if lift_position is None:
+        position = source_position
+    else:
+        lifted_position = lift_position(mutation.chromosome, source_position)
+        if lifted_position is None:
+            return None
+        position = lifted_position
+
+    anchor_source: str | None = None
+    if is_deletion or is_insertion:
+        if anchor_base is None:
+            anchor = "N"
+            anchor_source = "placeholder"
+        else:
+            anchor = anchor_base(mutation.chromosome, position)
+            anchor_source = "reference"
+        if is_deletion:
+            reference_allele = anchor + mutation.reference_allele
+            alternate_allele = anchor
+        else:
+            reference_allele = anchor
+            alternate_allele = anchor + mutation.variant_allele
+    else:
+        reference_allele = mutation.reference_allele
+        alternate_allele = mutation.variant_allele
+        if not reference_allele or not alternate_allele:
+            return None
+
+    info = _build_info(
+        mutation,
+        context,
+        lifted=lift_position is not None,
+        anchor_source=anchor_source,
+    )
+    return VcfRecord(
+        contig=mutation.chromosome,
+        position=position,
+        identifier=_identifier(mutation),
+        reference_allele=reference_allele.upper(),
+        alternate_allele=alternate_allele.upper(),
+        info=info,
+    )
+
+
+def build_records(
+    mutations: Iterable[Mutation],
+    context: TrackContext,
+    *,
+    lift_position: LiftPosition | None,
+    anchor_base: AnchorBase | None,
+) -> tuple[list[VcfRecord], int]:
+    """
+    Convert many mutations, sorted into the target build's contig order.
+
+    Args:
+        mutations: The source mutations.
+        context: The shared per-run context.
+        lift_position: A callable that lifts a source position to the target
+            build, or None when the source and target builds are the same.
+        anchor_base: A callable returning the target reference base for indel
+            anchoring, or None to use a placeholder ``N`` anchor.
+
+    Returns:
+        A tuple of the sorted records and the count of mutations that were
+        dropped because they were malformed, could not be lifted, or sit on a
+        contig that is not part of the target build.
+    """
+    order = contig_order(context.target_build)
+    records: list[VcfRecord] = []
+    dropped = 0
+    for mutation in mutations:
+        record = build_record(
+            mutation, context, lift_position=lift_position, anchor_base=anchor_base
+        )
+        if record is None or record.contig not in order:
+            dropped += 1
+            continue
+        records.append(record)
+    records.sort(key=lambda record: (order[record.contig], record.position))
+    return records, dropped
+
+
+def build_header(context: TrackContext, version: str) -> "pysam.VariantHeader":
+    """
+    Build a VCF header for the target build with the full INFO schema.
+
+    Args:
+        context: The shared per-run context.
+        version: The cellme version string, written to the ``source`` line.
+
+    Returns:
+        A pysam variant header populated with meta, contig, and INFO lines.
+    """
+    header = pysam.VariantHeader()
+    header.add_line(f"##source=cellme {version}")
+    header.add_line(f"##reference={context.target_build}")
+    header.add_line(f"##cellme_cellLine={context.cell_line}")
+    header.add_line(f"##cellme_sampleId={context.sample_id}")
+    header.add_line(f"##cellme_sourceStudy=cBioPortal CCLE {context.study}")
+    header.add_line(f"##cellme_sourceBuild={context.source_build}")
+    for name, length in contigs_for(context.target_build):
+        header.add_line(f"##contig=<ID={name},length={length}>")
+    for field in INFO_FIELDS:
+        header.add_line(
+            f"##INFO=<ID={field.key},Number={field.number},"
+            f'Type={field.type},Description="{field.description}">'
+        )
+    return header
+
+
+def _to_pysam_record(header: "pysam.VariantHeader", record: VcfRecord) -> "pysam.VariantRecord":
+    """
+    Materialize a VcfRecord as a pysam record bound to a header.
+
+    Args:
+        header: The header the record will be written under.
+        record: The record to materialize.
+
+    Returns:
+        A pysam variant record ready to be written.
+    """
+    start = record.position - 1
+    stop = start + len(record.reference_allele)
+    return header.new_record(
+        contig=record.contig,
+        start=start,
+        stop=stop,
+        alleles=(record.reference_allele, record.alternate_allele),
+        id=record.identifier,
+        info=dict(record.info),
+    )
+
+
+def write_vcf(
+    records: Iterable[VcfRecord],
+    header: "pysam.VariantHeader",
+    output: Path | None,
+) -> None:
+    """
+    Write records to a VCF at a path, or to standard output when no path given.
+
+    Args:
+        records: The records to write, already in sorted order.
+        header: The header to write them under.
+        output: The destination path, or None to write to standard output.
+    """
+    destination = str(output) if output is not None else "-"
+    with pysam.VariantFile(destination, "w", header=header) as out:
+        for record in records:
+            out.write(_to_pysam_record(header, record))
+
+
+def make_lifter(source: GenomeBuild, target: GenomeBuild) -> LiftPosition | None:
+    """
+    Create a position lifter between two builds, or None when they match.
+
+    The returned callable drops coordinates that fail to lift or that lift to a
+    different contig, so that only confidently mapped positions are emitted.
+
+    Args:
+        source: The build the source coordinates are on.
+        target: The build to lift coordinates onto.
+
+    Returns:
+        A lifter callable, or None when ``source`` and ``target`` are equal.
+    """
+    if source == target:
+        return None
+    lifter = get_lifter(source.ucsc_name, target.ucsc_name)
+
+    def lift(chromosome: str, position: int) -> int | None:
+        result = lifter.query(chromosome, position)
+        if not result:
+            return None
+        lifted_chromosome, lifted_position, _ = result[0]
+        if lifted_chromosome.removeprefix("chr") != chromosome.removeprefix("chr"):
+            return None
+        return int(lifted_position)
+
+    return lift
+
+
+def make_anchor_base(reference: Path | None) -> AnchorBase | None:
+    """
+    Open a reference FASTA and return a base lookup for indel anchoring.
+
+    The FASTA is matched by contig name with and without a ``chr`` prefix, so a
+    reference using either naming convention works.
+
+    Args:
+        reference: The path to a FASTA for the target build, or None.
+
+    Returns:
+        A callable returning the reference base at a 1-based position, or None
+        when no reference was supplied.
+    """
+    if reference is None:
+        return None
+    fasta = pysam.FastaFile(str(reference))
+    contigs = set(fasta.references)
+
+    def anchor(chromosome: str, position: int) -> str:
+        for name in (chromosome, f"chr{chromosome}"):
+            if name in contigs:
+                base = fasta.fetch(name, position - 1, position)
+                return base.upper() if base else "N"
+        return "N"
+
+    return anchor

cellme-1.0.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: cellme
+Version: 1.0.0
+Summary: Convert a human cell line identifier into a truth-track VCF of its known mutations.
+Project-URL: homepage, https://github.com/clintval/cellme
+Project-URL: repository, https://github.com/clintval/cellme
+Project-URL: Bug Tracker, https://github.com/clintval/cellme/issues
+Author-email: Clint Valentine <valentine.clint@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: defopt~=6.4
+Requires-Dist: liftover>=1.3
+Requires-Dist: pysam>=0.23
+Requires-Dist: rapidfuzz>=3.14.5
+Requires-Dist: requests>=2.32
+Description-Content-Type: text/markdown
+
+# cellme
+
+[![PyPI version](https://img.shields.io/pypi/v/cellme.svg)](https://pypi.org/project/cellme/)
+[![CI](https://github.com/clintval/cellme/actions/workflows/python_package.yml/badge.svg?branch=main)](https://github.com/clintval/cellme/actions/workflows/python_package.yml?query=branch%3Amain)
+[![Python Versions](https://img.shields.io/badge/python-3.12_|_3.13_|_3.14-blue)](https://github.com/clintval/cellme)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![MyPy Checked](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://docs.astral.sh/ruff/)
+
+Convert a human cell line identifier into a truth-track VCF of its known mutations.
+
+## Introduction
+
+cellme builds a truth/known VCF for a cell line by resolving a name such as `MOLT-4` to a [Cancer Cell Line Encyclopedia](https://sites.broadinstitute.org/ccle/) sample, fetching that sample's somatic mutations from the [cBioPortal](https://www.cbioportal.org/) REST API, and writing them as a sorted VCF.
+The mutation source is the `ccle_broad_2019` study.
+Records are against the GRCh37 assembly but a liftover can be performed if you need GRCh38 output.
+
+## Installation
+
+Install the release from PyPI with `pip`:
+
+```console
+pip install cellme
+```
+
+Add cellme to a [`uv`](https://docs.astral.sh/uv/) project, or run it without installing, with:
+
+```console
+uv add cellme
+uvx cellme --help
+```
+
+## Development Installation
+
+Install the Python package and dependency management tool [`uv`](https://docs.astral.sh/uv/getting-started/installation/) using the official documentation.
+
+Install the dependencies of the project with:
+
+```console
+uv sync --locked
+```
+
+To check successful installation, run:
+
+```console
+uv run cellme --help
+```
+
+## Usage
+
+Write a GRCh38 truth track for the cell line MOLT-4 to a file:
+
+```console
+uv run cellme "MOLT-4" --build GRCh38 --reference /ref/hg38.fa --output MOLT-4.GRCh38.vcf
+```
+
+> [!IMPORTANT]
+> Always pass `--reference` with a FASTA for the build you target, as shown above.
+> It ensure the correct anchor bases are set for insertions and deletions.
+> Without it, indel anchor bases fall back to a placeholder `N` and those records are marked `ANCHOR=placeholder`.
+
+The query is matched case-insensitively on the leading cell line token, so `MOLT-4`, `MOLT4`, and the full `MOLT4_HAEMATOPOIETIC_AND_LYMPHOID_TISSUE` sample ID all resolve to the same sample.
+
+## VCF INFO Fields
+
+Every record is annotated with compact, self-describing INFO fields.
+
+| Key              | Type    | Description                                                                 |
+| ---------------- | ------- | --------------------------------------------------------------------------- |
+| `GENE`           | String  | HUGO gene symbol.                                                           |
+| `PROTEIN_CHANGE` | String  | Protein-level change in CCLE short form (HGVS p.-like), e.g. `R306*`.        |
+| `VARIANT_CLASS`  | String  | Variant classification (MAF-style), e.g. `Missense_Mutation`.               |
+| `VARIANT_TYPE`   | String  | Sequence alteration type reported by CCLE: `SNP`, `DNP`, `INS`, or `DEL`.    |
+| `CELL_LINE`      | String  | Cell line resolved from the query.                                          |
+| `SAMPLE_ID`      | String  | CCLE sample identifier for the cell line.                                   |
+| `ENTREZ`         | Integer | NCBI Entrez gene identifier.                                                |
+| `REFSEQ`         | String  | RefSeq mRNA accession for the annotated transcript.                        |
+| `PROTEIN_POS`    | String  | Affected protein position or range, 1-based.                                |
+| `SOURCE`         | String  | Source database and study, e.g. `cBioPortal CCLE ccle_broad_2019`.          |
+| `ORIGINAL_BUILD` | String  | Genome build of the source coordinates before any liftover.                 |
+| `ORIGINAL_LOCUS` | String  | Original locus before liftover in UCSC position format, e.g. `chr17:7577022`. |
+| `LIFTED`         | Flag    | Coordinate was lifted from `ORIGINAL_BUILD` to the output reference build.   |
+| `ANCHOR`         | String  | Provenance of the indel anchor base: `reference` or `placeholder`.          |
+
+The `ID` column is set to a stable `gene:proteinChange` token where one is available, for example `TP53:R306*`, and falls back to `gene:chrom:pos` otherwise.
+
+## Development and Testing
+
+See the [contributing guide](./CONTRIBUTING.md) for more information.

cellme-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cellme/__init__.py,sha256=5D2ExwAMD0Ey6XJ0aSfWq2Q3OEfhi6eqewCKZvvoMzg,72
+cellme/builds.py,sha256=27EA18OJmnk4NS_-64ieyKGZLc1bTwg3Z6XjJUsDnh8,3468
+cellme/cbioportal.py,sha256=6898btBLTw4ixw7wPLCVWxF6p-Iw59USWWvrD3YaFkc,10746
+cellme/main.py,sha256=SI0Lapl65-2xyVIBhfXZsv1Hv6W6BcsqzP-y4C6Z5s0,970
+cellme/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cellme/vcf.py,sha256=zMmkiqd5uYLbFZnUXXIoSoiWt4MqM_Xc1Hpb46uNvcA,15522
+cellme/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cellme/tools/truth_track.py,sha256=UuChceqm9hmINFnYqeUrQmRGzPJqJyKneEm5kBG9USk,3049
+cellme-1.0.0.dist-info/METADATA,sha256=Vezrw1HQuDohglwTLKWPAmVZph2n5Kut2Hb_3JIt-Eg,5941
+cellme-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+cellme-1.0.0.dist-info/entry_points.txt,sha256=JJFK4NDS42GjJ2YNePs0SvsyfihMwx1O8BkInnDLG-E,43
+cellme-1.0.0.dist-info/licenses/LICENSE,sha256=ANRqU0eXlG-kIJQDac3GBzNMxSLphMGs1QieZ_Bc0Ww,1076
+cellme-1.0.0.dist-info/RECORD,,

cellme-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cellme-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cellme = cellme.main:run

cellme-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Fulcrum Genomics LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.