Pipeline de génotypage jointJoint genotyping pipeline

Le pipeline de génotypage conjoint Azure Databricks est un pipeline conforme aux meilleures pratiques GATK pour le génotypage conjoint à l’aide de GenotypeGVCFs.The Azure Databricks joint genotyping pipeline is a GATK best practices compliant pipeline for joint genotyping using GenotypeGVCFs.

Procédure pas à pasWalkthrough

Le pipeline se compose généralement des étapes suivantes :The pipeline typically consists of the following steps:

  1. Réception des variantes dans Delta Lake.Ingest variants into Delta Lake.
  2. Articulation : appelez la cohorte avec GenotypeGVCFs.Joint-call the cohort with GenotypeGVCFs.

Pendant la réception de variantes, les gVCFs à un seul échantillon sont traités par lots et les lignes sont stockées dans Delta Lake pour fournir une tolérance de panne, une interrogation rapide et un génotype commun incrémentiel.During variant ingest, single-sample gVCFs are processed in batches and the rows are stored in Delta Lake to provide fault tolerance, fast querying, and incremental joint genotyping. Dans l’étape conjointe de génotypage, les lignes gVCF sont ingérées à partir de Delta Lake, fractionnées en emplacements et distribuées aux partitions.In the joint genotyping step, the gVCF rows are ingested from Delta Lake, split into bins, and distributed to partitions. Pour chaque site variant, les lignes gVCF pertinentes par échantillon sont identifiées et utilisées pour le regénotypage.For each variant site, the relevant gVCF rows per sample are identified and used for regenotyping.

Programme d’installationSetup

Le pipeline est exécuté en tant que tâche de Azure Databricks.The pipeline is run as an Azure Databricks job. Il est très probable qu’un Azure Databricks architecte solutions fonctionne avec vous pour configurer le travail initial.Most likely an Azure Databricks solutions architect will work with you to set up the initial job. Les informations nécessaires sont les suivantes :The necessary details are:

{
  "autoscale.min_workers": {
    "type": "unlimited",
    "defaultValue": 1
  },
  "autoscale.max_workers": {
    "type": "unlimited",
    "defaultValue": 25
  },
  "node_type_id": {
    "type": "unlimited",
    "defaultValue": "Standard_L32s_v2"
  },
  "spark_env_vars.refGenomeId": {
    "type": "unlimited",
    "defaultValue": "grch38"
  },
  "spark_version": {
    "type": "regex",
    "pattern": ".*-hls.*",
    "defaultValue": "7.4.x-hls-scala2.12"
  }
}
  • La configuration du cluster doit utiliser Databricks Runtime pour la génomique.The cluster configuration should use Databricks Runtime for Genomics.
  • La tâche doit être le bloc-notes de pipeline de génotype commun qui se trouve en bas de cette page.The task should be the joint genotyping pipeline notebook found at the bottom of this page.
  • Pour de meilleures performances, utilisez les machines virtuelles optimisées pour le stockage.For best performance, use the storage-optimized VMs. Nous vous recommandons de Standard_L32s_v2.We recommend Standard_L32s_v2.
  • Pour réduire les coûts, activez la mise à l’échelle automatique avec un minimum de 1 Worker et un maximum de 10-50 en fonction des exigences de latence.To reduce costs, enable autoscaling with a minimum of 1 worker and a maximum of 10-50 depending on latency requirements.

Référencer des génomesReference genomes

Vous devez configurer le génome de référence à l’aide de variables d’environnement.You must configure the reference genome using environment variables. Pour utiliser GRCh37, définissez la variable d’environnement :To use GRCh37, set the environment variable:

refGenomeId=grch37

Pour utiliser GRCh38, remplacez grch37 par grch38 .To use GRCh38, change grch37 to grch38.

Pour utiliser un génome de référence personnalisé, consultez les instructions dans informations de référence personnalisées génomes.To use a custom reference genome, see instructions in Custom reference genomes.

ParamètresParameters

Le pipeline accepte des paramètres qui contrôlent son comportement.The pipeline accepts parameters that control its behavior. Les paramètres les plus importants et les plus couramment modifiés sont décrits ici.The most important and commonly changed parameters are documented here. Pour afficher tous les paramètres disponibles et leurs informations d’utilisation, exécutez la première cellule du bloc-notes du pipeline.To view all available parameters and their usage information, run the first cell of the pipeline notebook. De nouveaux paramètres sont régulièrement ajoutés.New parameters are added regularly. Après avoir importé le bloc-notes et l’avoir défini en tant que tâche de travail, vous pouvez définir ces paramètres pour toutes les exécutions ou par exécution.After importing the notebook and setting it as a job task, you can set these parameters for all runs or per-run.

ParamètreParameter DefaultDefault DescriptionDescription
manifestmanifest n/an/a Manifeste décrivant l’entrée.The manifest describing the input.
sortieoutput n/an/a Chemin d’accès où la sortie du pipeline est écrite.The path where pipeline output is written.
replayModereplayMode skipskip Valeurs possibles :One of:

* skip: les étapes sont ignorées si la sortie existe déjà.* skip: stages are skipped if output already exists.
* overwrite: la sortie existante est supprimée.* overwrite: existing output is deleted.
exportVCFexportVCF falsefalse Si la valeur est true, le pipeline écrit les résultats dans VCF et Delta Lake.If true, the pipeline writes results in VCF as well as Delta Lake.
targetedRegionstargetedRegions n/an/a Chemin d’accès aux fichiers contenant les régions à appeler.Path to files containing regions to call. En cas d’omission, appelle toutes les régions.If omitted, calls all regions.
gvcfDeltaOutputgvcfDeltaOutput n/an/a S’ils sont spécifiés, les gVCFs sont ingérés dans une table Delta avant le génotypage.If specified, gVCFs are ingested to a Delta table before genotyping. Vous devez spécifier ce paramètre uniquement si vous envisagez d’appeler le même gVCFs plusieurs fois.You should specify this parameter only if you expect to joint call the same gVCFs many times.
performValidationperformValidation falsefalse Si true la, le système vérifie que chaque enregistrement contient les informations nécessaires pour le génotypage conjoint.If true, the system verifies that each record contains the necessary information for joint genotyping. En particulier, il vérifie que le nombre correct de probabilités de génotype est présent.In particular, it checks that the correct number of genotype probabilities are present.
validationStringencyvalidationStringency INTERDIRESTRICT Comment gérer des enregistrements incorrects au cours du chargement et de la validation.How to handle malformed records, both during loading and validation.

* STRICT: échec du travail* STRICT: fail the job
* LENIENT: enregistrer un avertissement et supprimer l’enregistrement* LENIENT: log a warning and drop the record
* SILENT: supprimer l’enregistrement sans avertissement* SILENT: drop the record without a warning

Conseil

Pour effectuer un appel conjoint à partir d’une table Delta existante, définissez gvcfDeltaOutput sur le chemin d’accès de la table et replayMode sur skip .To perform joint calling from an existing Delta table, set gvcfDeltaOutput to the table path and replayMode to skip. Vous pouvez également fournir le manifest , qui sera utilisé pour définir le schéma et les exemples du VCF. ceux-ci seront déduits de la table Delta dans le cas contraire.You can also provide the manifest, which will be used to define the VCF schema and samples; these will be inferred from the Delta table otherwise. Nous ignorons targetedRegions les performValidation paramètres et dans ce programme d’installation.We ignore the targetedRegions and performValidation parameters in this setup.

Sortie Output

Les variantes regénotypes sont toutes écrites dans des tables delta dans le répertoire de sortie fourni.The regenotyped variants are all written out to Delta tables inside the provided output directory. En outre, si vous avez configuré le pipeline pour exporter des VCFs, ils s’affichent également sous le répertoire de sortie.In addition, if you configured the pipeline to export VCFs, they’ll appear under the output directory as well.

output
|---genotypes
    |---Delta files
|---genotypes.vcf
    |---VCF files

Format du manifesteManifest format

Notes

Les objets BLOB de manifeste sont pris en charge dans Databricks Runtime 6,6 pour la génomique et les versions ultérieures.Manifest blobs are supported in Databricks Runtime 6.6 for Genomics and above.

Le manifeste est un fichier ou un objet BLOB qui décrit où trouver les fichiers GVCF en entrée d’exemple unique, avec chaque chemin d’accès de fichier sur une nouvelle ligne.The manifest is a file or blob describing where to find the input single-sample GVCF files, with each file path on a new row. Par exemple :For example:

HG00096.g.vcf.bgz
HG00097.g.vcf.bgz

Conseil

Si le manifeste fourni est un fichier, chaque ligne peut être un chemin d’accès absolu ou un chemin d’accès relatif au fichier manifeste.If the provided manifest is a file, each row may be an absolute path or a path relative to the manifest file. Si le manifeste fourni est un objet BLOB, le champ de ligne doit être un chemin d’accès absolu.If the provided manifest is a blob, the row field must be an absolute path. Vous pouvez inclure des modèles glob (*) pour faire correspondre de nombreux fichiers.You can include globs (*) to match many files.

DépannageTroubleshooting

La tâche échoue avec un ArrayIndexOutOfBoundsExceptionJob fails with an ArrayIndexOutOfBoundsException

Cette erreur indique généralement qu’un enregistrement d’entrée comporte un nombre incorrect de probabilités de génotypage.This error usually indicates that an input record has an incorrect number of genotype probabilities. Essayez de définir l' performValidation option sur true et l' validationStringency option sur LENIENT ou SILENT .Try setting the performValidation option to true and the validationStringency option to LENIENT or SILENT.

Informations supplémentaires sur l’utilisationAdditional usage info

Le pipeline de génotype commun partage de nombreux détails opérationnels avec les autres pipelines de Azure Databricks.The joint genotyping pipeline shares many operational details with the other Azure Databricks pipelines. Pour obtenir des informations plus détaillées sur l’utilisation, telles que la structure de format de sortie, des conseils pour l’exécution par programme et des étapes de configuration de génomes de référence personnalisés, consultez pipeline DNASeq.For more detailed usage information, such as output format structure, tips for running programmatically, and steps for setting up custom reference genomes, see DNASeq pipeline.

Bloc-notes de pipeline de génotypage conjointJoint genotyping pipeline notebook

Obtenir le notebookGet notebook