Loci génomiques : revoir des appels de variants dans igv.js

Nouveau dans la v2.12.0

L'affichage genome_locus ouvre une région d'un génome dans igv.js avec les pistes dont un relecteur a besoin : la séquence de référence, les alignements de lectures, les appels de variants, les annotations et le signal. Son usage habituel est la revue manuelle de variants, où un annotateur examine les lectures sous un appel et répond à une question radio ordinaire comme réel, artefact ou incertain. Un schéma viewer_selection peut aussi enregistrer le locus que l'annotateur consultait et les appels ou éléments sur lesquels il a cliqué.

• Moteur : igv.js 3.8.9 est fourni avec Potato. Il dessine avec le canvas 2D et n'a donc pas besoin de WebGL.
• Les fichiers sont servis depuis le répertoire des médias. La route /media/ répond aux requêtes HTTP de plage (range), de sorte qu'igv.js lit un BAM, un CRAM, un VCF ou un FASTA indexé tranche par tranche. Les fichiers compressés en gzip sont envoyés sous forme de leurs octets compressés, ce dont a besoin un .vcf.gz ou un .bed.gz indexé par tabix.
• Référence : un FASTA indexé dans le répertoire des médias (.fa avec son .fai). Les identifiants de génome intégrés à igv (hg38, mm39) téléchargent leurs fichiers depuis Internet ; ils ne sont donc acceptés qu'avec allow_remote: true.
• Hors ligne par défaut : avec une référence locale et des pistes locales, la page ne charge rien en dehors du serveur Potato, et la tâche fonctionne donc sur un réseau isolé (air-gapped).

Configuration

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

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

Le champ de locus accepte les formes qu'accepte la zone de locus d'igv, en base 1 et bornes incluses : chr1:1,450-1,550 ouvre cet intervalle, chr1:1500 ouvre la position 1500 avec flank bases de chaque côté, et chr1 ouvre la séquence entière. Avec une référence locale, le nom de séquence est vérifié par rapport au .fai, et un item qui désigne une séquence absente de la référence affiche un message listant les séquences qu'elle contient.

Chaque piste prend name, et soit url (un fichier du répertoire des médias, le même pour tous les items), soit field (un champ de l'item contenant le fichier, de sorte que chaque item apporte le sien). format vaut bam, cram, vcf, bed, gff3, gff, gtf, bigbed, bigwig, bedgraph ou wig, et se déduit de l'extension s'il est omis. index ou index_field désigne l'index, par défaut le .bai, le .crai ou le .tbi placé à côté du fichier. height, color et display_mode sont transmis à igv.

La valeur d'une piste field est vérifiée dans le navigateur avant son chargement. Une valeur vide, un chemin hors du répertoire des médias, une valeur qui n'est pas un chemin, une URL distante quand allow_remote est désactivé, ou un nom dont le format ne peut pas être déterminé empêchent la piste d'apparaître dans la vue, et une ligne sous le visualiseur indique la piste et la raison.

Préparer les fichiers

Utilisez la référence sur laquelle les lectures ont été alignées, avec les mêmes noms de séquences, puisque chr1 et 1 sont des séquences différentes pour igv. Un .vcf.gz produit avec un simple gzip ne peut pas être indexé ; recompressez-le donc avec bgzip. Pour un jeu de revue tiré d'une grande cohorte, découpez les BAM aux régions examinées pour que le dossier des médias reste petit. Un proxy inverse qui ajoute Content-Encoding ou supprime Range casse les lectures indexées ; servez donc /media/ sans modification.

Revoir un appel

L'annotateur lit l'appel dans la note, puis examine les lectures au centre de la vue, où igv colore les bases discordantes et où la barre de couverture montre les fractions alléliques. Il peut faire défiler la vue en la faisant glisser, zoomer avec les boutons ou la molette, et saisir un locus dans la zone de recherche d'igv. Avec select_features activé, cliquer sur un appel ou un élément le sélectionne, l'ombre dans la vue et le liste sous la question viewer_selection. Ouvrir un item ne compte pas comme une réponse, et les raccourcis de la question radio (1, 2, 3) fonctionnent pendant qu'igv est sur la page.

Réponse stockée

{"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 est la vue dans laquelle l'annotateur a quitté l'item en dernier. start et end sont en base 1 et bornes incluses ; un élément BED chr1 900 2400 est donc stocké sous la forme start: 901, end: 2400. kind vaut variant pour un appel et feature pour un élément d'une piste d'annotation. Les réponses radio et multiselect s'exportent comme celles de tout autre schéma, et le JSON de viewer_selection est la valeur du schéma dans les exports jsonl, csv et tsv. Pour trouver les appels sur lesquels les relecteurs sont en désaccord, regroupez les réponses call_review par identifiant d'item, ou utilisez le rapport d'accord sur le schéma radio.

Exemple

examples/advanced/variant-review/ contient un génome synthétique, 144 lectures simulées et quatre appels :

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

Deux de ses appels sont étayés par les lectures. Un autre n'est porté que par des lectures du brin inverse de faible qualité de base, et le dernier est une délétion d'une base à l'intérieur d'une série de A ; l'exemple montre donc chaque réponse.

Pour aller plus loin

• Structures de protéines - Sélection de résidus dans 3Dmol.js ou Mol*
• Affichage des instances - Configuration des champs d'affichage
• Annotation hors ligne (air-gapped) - Exécuter Potato sans accès à Internet

Pour les détails d'implémentation, consultez la documentation source sur les loci génomiques et la revue de variants.