Genes

Endpoints para obtener la anotación de un gen y consultar sus variantes.

GET /genes/{symbol}

Devuelve la GeneAnnotation completa para un símbolo génico.

Parámetros:

Parámetro	Tipo	Default	Descripción
symbol	path	—	Símbolo HGNC (e.g. BRCA1)
source	query	gencode	Fuente de anotación génica

Response: GeneAnnotation serializado.

{
  "gene": {
    "nomenclature": { "symbols": { "names": ["BRCA1"], "aliases": {} } },
    "position": { "chromosome": "17", "start": 43044295, "end": 43125483 }
  },
  "biotype": "PROTEIN_CODING",
  "transcripts": [ { "..." } ],
  "genomic_scores": [ { "name": "pLI", "value": 0.99 } ],
  "diseases": [ { "..." } ]
}

Ejemplo

import httpx

response = httpx.get("http://localhost:8000/genes/BRCA1")
gene = response.json()
print(gene["gene"]["position"])

---

GET /genes/{symbol}/variants

Devuelve todas las variantes en la región genómica del gen, anotadas con el pipeline seleccionado.

Parámetros:

Parámetro	Tipo	Default	Descripción
symbol	path	—	Símbolo HGNC
store	query	mcps_af	Region store para obtener variantes
gene_source	query	gencode	Fuente para resolver la posición del gen
profile	query	gene_view	Perfil de anotación a aplicar
add	query	[]	Stores extra añadidos al pipeline
exclude	query	[]	Stores excluidos del pipeline
workers	query	4	Workers tabix paralelos

Por qué gene_view como perfil default

El region store (mcps_af) ya adjunta frecuencias MCPS a las variantes durante la consulta por región. El perfil gene_view excluye mcps_af del pipeline de anotación para evitar re-anotar lo que ya viene incluido.

Response:

{
  "gene":          { "...GeneAnnotation..." },
  "variants":      [ { "...VariantAnnotation..." } ],
  "total":         847,
  "region_store":  "mcps_af",
  "stores_applied": ["clinvar", "loftee"]
}

Ejemplo

import httpx
from iris.adapters.driven.serializers.variant import converter
from iris.domain.genomics.entities import GeneAnnotation, VariantAnnotation

response = httpx.get(
    "http://localhost:8000/genes/BRCA2/variants",
    params={"profile": "clinical", "exclude": ["mcps_af"], "workers": 8},
)
data = response.json()

gene = converter.structure(data["gene"], GeneAnnotation)
variants = [converter.structure(v, VariantAnnotation) for v in data["variants"]]
print(f"{gene.gene.symbol}: {data['total']} variantes")

---

Referencia

iris.applications.api.routers.genes

Genes API router — gene annotation and region-based variant queries.

gene_annotation async

gene_annotation(symbol, source='gencode')

Return the full GeneAnnotation for a gene symbol.

PARAMETER	DESCRIPTION
symbol	HGNC gene symbol (case-insensitive). TYPE: str
source	Which gene registry to query (default: gencode). TYPE: str DEFAULT: 'gencode'

Source code in src/iris/applications/api/routers/genes.py

@router.get("/{symbol}", response_class=ORJSONResponse)
async def gene_annotation(
    symbol: Annotated[str, Path(description="HGNC gene symbol, e.g. BRCA1")],
    source: Annotated[str, Query(description="Gene annotation source")] = "gencode",
) -> ORJSONResponse:
    """Return the full GeneAnnotation for a gene symbol.

    Args:
        symbol: HGNC gene symbol (case-insensitive).
        source: Which gene registry to query (default: ``gencode``).
    """
    repo = require_gene_source(source)
    annotation: GeneAnnotation | None = repo.get_annotation(symbol.upper())

    if annotation is None:
        # Try the original case before giving up
        annotation = repo.get_annotation(symbol)

    if annotation is None:
        from fastapi import HTTPException

        raise HTTPException(status_code=404, detail=f"Gene {symbol!r} not found in {source!r}")

    return ORJSONResponse(content=converter.unstructure(annotation))

gene_variants async

gene_variants(
    symbol,
    store="mcps_af",
    gene_source="gencode",
    profile="gene_view",
    add=[],
    exclude=[],
    workers=4,
)

Return all variants in a gene's genomic region, annotated through a pipeline.

Steps:

1. Resolve symbol → GeneAnnotation (from gene_source).
2. Query all variants overlapping the gene's GenomicPosition (from store).
3. Apply the annotation pipeline: profile stores + add − exclude.

The gene_view profile excludes mcps_af by default because the region store already attaches MCPS frequencies during step 2.

PARAMETER	DESCRIPTION
symbol	HGNC gene symbol. TYPE: str
store	Region store to pull variants from (default: mcps_af). TYPE: str DEFAULT: 'mcps_af'
gene_source	Gene registry used to resolve the genomic position. TYPE: str DEFAULT: 'gencode'
profile	Annotation profile (default: gene_view). TYPE: str | None DEFAULT: 'gene_view'
add	Extra stores appended after the profile. TYPE: list[str] DEFAULT: []
exclude	Stores to remove from the pipeline. TYPE: list[str] DEFAULT: []
workers	Parallel tabix workers. TYPE: int DEFAULT: 4

Source code in src/iris/applications/api/routers/genes.py

@router.get("/{symbol}/variants", response_class=ORJSONResponse)
async def gene_variants(
    symbol: Annotated[str, Path(description="HGNC gene symbol, e.g. BRCA1")],
    store: Annotated[str, Query(description="Region store to query variants from")] = "mcps_af",
    gene_source: Annotated[
        str, Query(description="Gene annotation source used to resolve the genomic region")
    ] = "gencode",
    profile: Annotated[
        str | None, Query(description="Annotation profile to apply on retrieved variants")
    ] = "gene_view",
    add: Annotated[
        list[str], Query(description="Extra annotator stores appended after the profile")
    ] = [],
    exclude: Annotated[
        list[str], Query(description="Stores to remove from the annotation pipeline")
    ] = [],
    workers: Annotated[int, Query(ge=1, le=32)] = 4,
) -> ORJSONResponse:
    """Return all variants in a gene's genomic region, annotated through a pipeline.

    Steps:

    1. Resolve ``symbol`` → ``GeneAnnotation`` (from ``gene_source``).
    2. Query all variants overlapping the gene's ``GenomicPosition``
       (from ``store``).
    3. Apply the annotation pipeline: ``profile`` stores + ``add`` − ``exclude``.

    The ``gene_view`` profile excludes ``mcps_af`` by default because the
    region store already attaches MCPS frequencies during step 2.

    Args:
        symbol: HGNC gene symbol.
        store: Region store to pull variants from (default: ``mcps_af``).
        gene_source: Gene registry used to resolve the genomic position.
        profile: Annotation profile (default: ``gene_view``).
        add: Extra stores appended after the profile.
        exclude: Stores to remove from the pipeline.
        workers: Parallel tabix workers.
    """
    # 1. Resolve gene → position
    repo = require_gene_source(gene_source)
    annotation: GeneAnnotation | None = repo.get_annotation(symbol.upper()) or repo.get_annotation(
        symbol
    )

    if annotation is None:
        raise HTTPException(
            status_code=404, detail=f"Gene {symbol!r} not found in {gene_source!r}"
        )

    position = annotation.gene.position
    if position is None:
        raise HTTPException(
            status_code=422, detail=f"Gene {symbol!r} has no genomic position in {gene_source!r}"
        )

    # 2. Query variants in gene region
    region_store = require_region_store(store)
    variants: list[VariantAnnotation] = region_store.query_region(position, workers=workers)

    # 3. Annotate
    store_names = resolve_stores(profile, add, exclude, get_profiles())
    for name in store_names:
        annotator = require_annotator(name)
        variants = annotator.annotate(variants, workers=workers)

    return ORJSONResponse(
        content={
            "gene": converter.unstructure(annotation),
            "variants": [converter.unstructure(va) for va in variants],
            "total": len(variants),
            "region_store": store,
            "stores_applied": store_names,
        }
    )