Loci genómicos: revisar llamadas de variantes en igv.js

Muestra un locus del genoma en igv.js dentro de Potato con una referencia local y pistas BAM, CRAM, VCF o BED, y haz que los revisores marquen cada llamada de variante como real o como artefacto.

Nuevo en v2.12.0

La visualización genome_locus abre una región de un genoma en igv.js con las pistas que necesita un revisor: la secuencia de referencia, los alineamientos de lecturas, las llamadas de variantes, las anotaciones y la señal. Su uso habitual es la revisión manual de variantes, en la que un anotador mira las lecturas bajo una llamada y responde una pregunta radio normal, como real, artefacto o incierta. Un esquema viewer_selection también puede registrar el locus que estaba viendo el anotador y las llamadas o elementos en los que hizo clic.

Motor: igv.js 3.8.9 viene con Potato. Dibuja con canvas 2D, así que no necesita WebGL.
Los archivos se sirven desde el directorio de multimedia. La ruta /media/ responde a peticiones HTTP de rango, así que igv.js lee un BAM, CRAM, VCF o FASTA indexado por fragmentos. Los archivos comprimidos con gzip se envían como sus bytes comprimidos, que es lo que necesita un .vcf.gz o un .bed.gz indexado con tabix.
Referencia: un FASTA indexado en el directorio de multimedia (.fa con su .fai). Los ID de genoma integrados de igv (hg38, mm39) descargan sus archivos de internet, así que solo se aceptan con allow_remote: true.
Sin conexión por defecto: con una referencia local y pistas locales, la página no carga nada de fuera del servidor de Potato, así que la tarea funciona en una red aislada.

Configuración

yaml

media_directory: media
data_files: [data/calls.json]
item_properties: {id_key: id, text_key: note}
 
instance_display:
  fields:
    - key: note
      type: text
    - key: locus                 # item field holding the locus
      type: genome_locus
      label: "Locus"
      display_options:
        reference:
          fasta: genome/ref.fa           # .fai next to it
          name: ref
        flank: 60
        tracks:
          - name: "Calls"
            url: calls/cohort.vcf.gz     # same file for every item; .tbi next to it
          - name: "Reads"
            field: bam                   # an item field names the file
            height: 260
          - name: "Regions"
            url: annotation/regions.bed
 
annotation_schemes:
  - annotation_type: radio
    name: call_review
    description: "Is this variant call real?"
    labels: ["Real", "Artifact", "Uncertain"]
    label_requirement:
      required: true
 
  - annotation_type: multiselect
    name: evidence_seen
    description: "What did you see in the reads?"
    labels:
      - "Alt allele on both strands"
      - "Alt allele on one strand only"
      - "Low base quality at the alt"
      - "In a homopolymer or repeat"
 
  - annotation_type: viewer_selection
    name: evidence
    description: "Evidence (optional): click the call or region you based this on"
    viewer_field: locus
    max_selections: 4

json

{"id": "call_1", "locus": "chr1:1201", "note": "C>G at chr1:1,201", "bam": "reads/sample1.bam"}

El campo del locus admite las mismas formas que el cuadro de locus de igv, con base 1 e inclusivas: chr1:1,450-1,550 abre ese rango, chr1:1500 abre la posición 1500 con flank bases a cada lado, y chr1 abre la secuencia entera. Con una referencia local, el nombre de la secuencia se comprueba con el .fai, y un ítem que nombra una secuencia que la referencia no tiene muestra un mensaje con la lista de las secuencias que sí tiene.

Opción de visualización	Valor por defecto	Significado
`reference`	ninguno	`{fasta: <path>, index: <path>, name: <label>}`. `index` es por defecto la ruta del FASTA más `.fai`
`genome`	ninguno	Un ID de genoma de igv. Necesita `allow_remote: true`. Indica `reference` o `genome`, no ambos
`tracks`	`[]`	La lista de pistas
`flank`	`50`	Bases que se muestran a cada lado de un locus de una sola posición
`select_features`	`true`	Hacer clic en una llamada o un elemento lo añade o lo quita de la selección en lugar de abrir la ventana emergente de igv
`allow_remote`	`false`	Permite URL http(s) para la referencia y las pistas, e ID de genoma

Cada pista admite name, y url (un archivo del directorio de multimedia, el mismo para todos los ítems) o field (un campo del ítem que contiene el archivo, para que cada ítem aporte el suyo). format es bam, cram, vcf, bed, gff3, gff, gtf, bigbed, bigwig, bedgraph o wig, y se toma de la extensión cuando se omite. index o index_field nombra el índice, que por defecto es .bai, .crai o .tbi junto al archivo. height, color y display_mode se pasan a igv tal cual.

El valor de una pista field se comprueba en el navegador antes de cargarla. Un valor vacío, una ruta fuera del directorio de multimedia, un valor que no es una ruta, una URL remota cuando allow_remote está desactivado, o un nombre del que no puede deducirse el formato dejan la pista fuera de la vista, y una línea bajo el visor nombra la pista y el motivo.

Preparar los archivos

Archivo	Índice	Comandos habituales
FASTA de referencia	`.fai`	`samtools faidx ref.fa`
Lecturas (BAM, CRAM)	`.bai`, `.crai`	`samtools sort -o s.bam in.bam && samtools index s.bam`
Llamadas (VCF)	`.tbi`	`bgzip calls.vcf && tabix -p vcf calls.vcf.gz`
Regiones (BED, GFF3)	`.tbi`, o ninguno para un archivo pequeño sin comprimir	`bgzip regions.bed && tabix -p bed regions.bed.gz`

Usa la referencia contra la que se alinearon las lecturas, con los mismos nombres de secuencia, ya que para igv chr1 y 1 son secuencias distintas. Un .vcf.gz hecho con gzip simple no puede indexarse, así que vuelve a comprimirlo con bgzip. Para un conjunto de revisión extraído de una cohorte grande, recorta los BAM a las regiones que se revisan para que la carpeta de multimedia siga siendo pequeña. Un proxy inverso que añade Content-Encoding o elimina Range rompe las lecturas indexadas, así que sirve /media/ sin cambios.

Revisar una llamada

El anotador lee la llamada en la nota y después mira las lecturas en el centro de la vista, donde igv colorea las bases que no coinciden y la barra de cobertura muestra las fracciones alélicas. Puede desplazarse arrastrando, hacer zoom con los botones o la rueda, y escribir un locus en el cuadro de búsqueda de igv. Con select_features activado, hacer clic en una llamada o un elemento lo selecciona, lo sombrea en la vista y lo enumera bajo la pregunta viewer_selection. Abrir un ítem no cuenta como respuesta, y los atajos de las preguntas radio (1, 2, 3) funcionan mientras igv está en la página.

Respuesta guardada

json

{"viewer": "genome_locus",
 "locus": "chr1:1141-1261",
 "items": [{"chr": "chr1", "start": 1201, "end": 1201, "kind": "variant",
            "name": "call_1", "ref": "C", "alt": "G", "track": "Calls"}]}

locus es la vista en la que el anotador dejó el ítem por última vez. start y end tienen base 1 y son inclusivos, así que un elemento BED chr1 900 2400 se guarda como start: 901, end: 2400. kind es variant para una llamada y feature para un elemento de una pista de anotación. Las respuestas radio y multiselect se exportan como cualquier otro esquema, y el JSON de viewer_selection es el valor del esquema en las exportaciones jsonl, csv y tsv. Para encontrar las llamadas en las que los revisores no coinciden, agrupa las respuestas de call_review por ID de ítem, o usa el informe de concordancia sobre el esquema radio.

Ejemplo

examples/advanced/variant-review/ tiene un genoma sintético, 144 lecturas simuladas y cuatro llamadas:

bash

python potato/flask_server.py start examples/advanced/variant-review/config.yaml -p 8000

Dos de sus llamadas están respaldadas por las lecturas. Otra solo la llevan lecturas de la hebra inversa con baja calidad de base, y la última es una deleción de una base dentro de una serie de poli-A, así que el ejemplo muestra cada respuesta.

Lecturas adicionales

Estructuras de proteínas - Selección de residuos en 3Dmol.js o Mol*
Visualización de instancias - Cómo se configuran los campos de visualización
Anotación sin conexión a la red - Ejecutar Potato sin acceso a internet

Para detalles de implementación, consulta la documentación fuente sobre los loci genómicos y la revisión de variantes.