Pipeline DNASeqDNASeq pipeline

Notes

Les versions de bibliothèque suivantes sont empaquetées dans Databricks Runtime 7,0 pour la génomique.The following library versions are packaged in Databricks Runtime 7.0 for Genomics. Pour les bibliothèques incluses dans les versions inférieures de Databricks Runtime pour la génomique, consultez les notes de publication.For libraries included in lower versions of Databricks Runtime for Genomics, see the release notes.

Le pipeline DNASeq Azure Databricks est un pipeline conforme aux meilleures pratiques GATK pour l’alignement de lecture rapide, l’appel de variant et l’annotation de type Variant.The Azure Databricks DNASeq pipeline is a GATK best practices compliant pipeline for short read alignment, variant calling, and variant annotation. Il utilise les packages logiciels suivants, en parallèle à l’aide de Spark.It uses the following software packages, parallelized using Spark.

  • BWA v 0.7.17BWA v0.7.17
  • ADAM v 0.32.0ADAM v0.32.0
  • GATK HaplotypeCaller v 4.1.4.1GATK HaplotypeCaller v4.1.4.1
  • SnpEff v 4.3SnpEff v4.3

Pour plus d’informations sur l’implémentation du pipeline et les runtimes et coûts attendus pour diverses combinaisons d’options, consultez création du pipeline DNASeq le plus rapide dans Scala.For more information about the pipeline implementation and expected runtimes and costs for various option combinations, see Building the Fastest DNASeq Pipeline at Scala.

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. Vous pouvez configurer une stratégie de cluster pour enregistrer la configuration :You can set up a cluster policy to save the configuration:

{
  "num_workers": {
    "type": "unlimited",
    "defaultValue": 13
  },
  "node_type_id": {
    "type": "unlimited",
    "defaultValue": "Standard_F32s_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 DNASeq situé en bas de cette page.The task should be the DNASeq notebook found at the bottom of this page.
  • Pour de meilleures performances, utilisez les machines virtuelles optimisées pour le calcul avec au moins 60 Go de mémoire.For best performance, use the compute optimized VMs with at least 60GB of memory. Nous vous recommandons d’utiliser des machines virtuelles Standard_F32s_v2 .We recommend Standard_F32s_v2 VMs.
  • Si vous exécutez le réétalonnage de score de qualité de base, utilisez des instances à usage général (Standard_D32s_v3) à la place, car cette opération nécessite plus de mémoire.If you’re running base quality score recalibration, use general purpose (Standard_D32s_v3) instances instead since this operation requires more memory.

Référencer des génomesReference genomes

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

refGenomeId=grch37

Pour utiliser GRCh38 à la place, remplacez grch37 par grch38 .To use GRCh38 instead, replace grch37 with grch38.

Génomes de référence personnalisésCustom reference genomes

Notes

La prise en charge du génome de référence personnalisé est disponible dans Databricks Runtime 6,6 pour la génomique et les versions ultérieures.Custom reference genome support is available in Databricks Runtime 6.6 for Genomics and above.

Pour utiliser une version de référence différente de GRCh37 ou GRCh38, procédez comme suit :To use a reference build other than GRCh37 or GRCh38, follow these steps:

  1. Préparez la référence à utiliser avec BWA et GATK.Prepare the reference for use with BWA and GATK.

    Le contenu du répertoire de référence du génome doit inclure les fichiers suivants :The reference genome directory contents should include these files:

    <reference_name>.dict
    <reference_name>.fa
    <reference_name>.fa.amb
    <reference_name>.fa.ann
    <reference_name>.fa.bwt
    <reference_name>.fa.fai
    <reference_name>.fa.pac
    <reference_name>.fa.sa
    
  2. Chargez les fichiers de référence génome dans un répertoire dans le stockage cloud ou DBFS.Upload the reference genome files to a directory in cloud storage or DBFS. Si vous téléchargez les fichiers dans le stockage cloud, vous devez monter le répertoire à un emplacement dans dBFS.If you upload the files to cloud storage, you must mount the directory to a location in DBFS.

  3. Dans la configuration de votre cluster, définissez une variable d’environnement REF_GENOME_PATH qui pointe vers le chemin d’accès du fichier fasta dans dBFS.In your cluster configuration, set an environment variable REF_GENOME_PATH that points to the path of the fasta file in DBFS. Par exemple,For example,

    REF_GENOME_PATH=/mnt/reference-genome/reference.fa
    

    Le chemin d’accès ne doit pas inclure de dbfs: préfixe.The path must not include a dbfs: prefix.

    Lorsque vous utilisez un génome de référence personnalisé, l’étape d’annotation SnpEff est ignorée.When you use a custom reference genome, the SnpEff annotation stage is skipped.

Conseil

Pendant l’initialisation du cluster, le pipeline DNASeq Azure Databricks utilise les fichiers d’index BWA fournis pour générer un fichier image d’index.During cluster initialization, the Azure Databricks DNASeq pipeline uses the provided BWA index files to generate an index image file. Si vous prévoyez d’utiliser plusieurs fois le même génome de référence, vous pouvez accélérer le démarrage du cluster en générant le fichier d’image d’index à l’avance.If you plan to use the same reference genome many times, you can accelerate cluster startup by building the index image file ahead of time. Ce processus va réduire le temps de démarrage du cluster d’environ 30 secondes.This process will reduce cluster startup time by about 30 seconds.

  1. Copiez le répertoire de Genomes de référence sur le nœud de pilote d’un Databricks Runtime pour le cluster génomique.Copy the reference genome directory to the driver node of a Databricks Runtime for Genomics cluster.

    %sh cp -r /dbfs/<reference_dir_path> /local_disk0/reference-genome
    
  2. Générez le fichier image d’index à partir des fichiers d’index BWA.Generate the index image file from the BWA index files.

    import org.broadinstitute.hellbender.utils.bwa._
    BwaMemIndex.createIndexImageFromIndexFiles("/local_disk0/reference-genome/<reference_name>.fa", "/local_disk0/reference-genome/<reference_name>.fa.img")
    
  3. Copiez dans le fichier d’image d’index dans le même répertoire que les fichiers fasta de référence.Copy to the index image file to the same directory as the reference fasta files.

    %sh cp /local_disk0/reference-genome/<reference_name>.fa.img /dbfs/<reference_dir_path>
    
  4. Supprimez les fichiers d’index BWA inutiles ( .amb , .ann , .bwt , .pac , .sa ) de dBFS.Delete the unneeded BWA index files (.amb, .ann, .bwt, .pac, .sa) from DBFS.

    %fs rm <file>
    

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. le reste est disponible dans le bloc-notes DNASeq.The most important and commonly changed parameters are documented here; the rest can be found in the DNASeq notebook. 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 doit être écrite.The path where pipeline output should be 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.
referenceConfidenceModereferenceConfidenceMode AucuneNONE Valeurs possibles :One of:

* Si NONE , seuls les sites variant sont inclus dans la sortie* If NONE, only variant sites are included in the output
* Si GVCF , tous les sites sont inclus, avec des sites de référence adjacents.* If GVCF, all sites are included, with adjacent reference sites banded.
* Si BP_RESOLUTION , tous les sites sont inclus.* If BP_RESOLUTION, all sites are included.
perSampleTimeoutperSampleTimeout 12 h12h Délai d’expiration appliqué par échantillon.A timeout applied per sample. Une fois ce délai atteint, le pipeline continue à l’exemple suivant.After reaching this timeout, the pipeline continues on to the next sample. La valeur de ce paramètre doit inclure une unité de délai d’attente : 'pour les secondes, 'm’pour minutes ou’h’pour les heures.The value of this parameter must include a timeout unit: ‘s’ for seconds, ‘m’ for minutes, or ‘h’ for hours. Par exemple, « 60 min » génère un délai d’expiration de 60 minutes.For example, ‘60m’ results in a timeout of 60 minutes.

Conseil

Pour optimiser la durée d’exécution, définissez la spark.sql.shuffle.partitions configuration Spark sur trois fois le nombre de cœurs du cluster.To optimize run time, set the spark.sql.shuffle.partitions Spark configuration to three times the number of cores of the cluster.

PersonnalisationCustomization

Vous pouvez personnaliser le pipeline DNASeq en désactivant l’alignement de lecture, l’appel de variante et l’annotation de type Variant.You can customize the DNASeq pipeline by disabling read alignment, variant calling, and variant annotation. Par défaut, les trois étapes sont activées.By default, all three stages are enabled.

val pipeline = new DNASeqPipeline(align = true, callVariants = true, annotate = true)

Pour désactiver l’annotation de type Variant, définissez le pipeline comme suit :To disable variant annotation, set the pipeline as follows:

val pipeline = new DNASeqPipeline(align = true, callVariants = true, annotate = false)

Les combinaisons de phases autorisées sont les suivantes :The permitted stage combinations are:

Lire l’alignementRead alignment Appel de variantVariant calling Annotation de type VariantVariant annotation
truetrue truetrue truetrue
truetrue truetrue falsefalse
truetrue falsefalse falsefalse
falsefalse truetrue truetrue
falsefalse truetrue falsefalse

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 CSV ou un objet BLOB qui décrit où trouver les fichiers FASTQ ou BAM d’entrée.The manifest is a CSV file or blob describing where to find the input FASTQ or BAM files. Par exemple :For example:

file_path,sample_id,paired_end,read_group_id
*_R1_*.fastq.bgz,HG001,1,read_group
*_R2_*.fastq.bgz,HG001,2,read_group

Si votre entrée se compose de fichiers BAM non alignés, vous devez omettre le paired_end champ :If your input consists of unaligned BAM files, you should omit the paired_end field:

file_path,sample_id,paired_end,read_group_id
*.bam,HG001,,read_group

Conseil

Si le manifeste fourni est un fichier, le file_path champ de 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, the file_path field in each row can be an absolute path or a path relative to the manifest file. Si le manifeste fourni est un objet BLOB, le file_path champ doit être un chemin d’accès absolu.If the provided manifest is a blob, the file_path 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.

Formats d’entrée pris en chargeSupported input formats

  • SAMSAM
  • BAMBAM
  • RÉCOLTERCRAM
  • ParquetParquet
  • FASTQFASTQ
    • bgzip *.fastq.bgz (recommandé) les fichiers bgzipped avec l' *.fastq.gz extension sont reconnus comme bgz .bgzip *.fastq.bgz (recommended) bgzipped files with the *.fastq.gz extension are recognized as bgz.
    • non compressé *.fastquncompressed *.fastq
    • gzip *.fastq.gzgzip *.fastq.gz

Important

Les fichiers gzippé ne peuvent pas être fractionnés.Gzipped files are not splittable. Choisissez mise à l’échelle automatique pour réduire le coût de ces fichiers.Choose autoscaling clusters to minimize cost for these files.

Pour bloquer la compression d’un FASTQ, installez htslib, qui comprend l' bgzip exécutable.To block compress a FASTQ, install htslib, which includes the bgzip executable.

OutputOutput

Les lectures alignées, appelées variantes et variantes annotées sont toutes écrites dans les tables delta dans le répertoire de sortie fourni si les étapes correspondantes sont activées.The aligned reads, called variants, and annotated variants are all written out to Delta tables inside the provided output directory if the corresponding stages are enabled. Chaque table est partitionnée par un exemple d’ID.Each table is partitioned by sample ID. En outre, si vous avez configuré le pipeline pour exporter BAMs ou VCFs, ils s’affichent également sous le répertoire de sortie.In addition, if you configured the pipeline to export BAMs or VCFs, they’ll appear under the output directory as well.

|---alignments
    |---sampleId=HG001
        |---Parquet files
|---alignments.bam
    |---HG001.bam
|---annotations
    |---Delta files
|---annotations.vcf
    |---HG001.vcf
|---genotypes
    |---Delta files
|---genotypes.vcf
    |---HG001.vcf

Quand vous exécutez le pipeline sur un nouvel exemple, il apparaît sous la forme d’une nouvelle partition.When you run the pipeline on a new sample, it’ll appear as a new partition. Si vous exécutez le pipeline pour un exemple qui figure déjà dans le répertoire de sortie, cette partition sera remplacée.If you run the pipeline for a sample that already appears in the output directory, that partition will be overwritten.

Étant donné que toutes les informations sont disponibles dans Delta Lake, vous pouvez facilement les analyser avec Spark dans Python, R, Scala ou SQL.Since all the information is available in Delta Lake, you can easily analyze it with Spark in Python, R, Scala, or SQL. Par exemple :For example:

PythonPython

# Load the data
df = spark.read.format("delta").load("/genomics/output_dir/genotypes")
# Show all variants from chromosome 12
display(df.where("contigName == '12'").orderBy("sampleId", "start"))

SQLSQL

-- Register the table in the catalog
CREATE TABLE genotypes
USING delta
LOCATION '/genomics/output_dir/genotypes'

DépannageTroubleshooting

Le travail est lent et les tâches en cours d’exécutionJob is slow and few tasks are running

Indique généralement que les fichiers FASTQ d’entrée sont compressés avec gzip au lieu de bgzip .Usually indicates that the input FASTQ files are compressed with gzip instead of bgzip. Les fichiers gzippé ne sont pas divisés. l’entrée ne peut donc pas être traitée en parallèle.Gzipped files are not splittable, so the input cannot be processed in parallel. Essayez d’utiliser le bloc-notes Parallel bgzip pour convertir un répertoire de fichiers de en gzip bgzip en parallèle.Try using the parallel bgzip notebook to convert a directory of files from gzip to bgzip in parallel.

Exécuter programmatiquementRun programmatically

Outre l’utilisation de l’interface utilisateur, vous pouvez démarrer des exécutions du pipeline par programme à l’aide de l’interface CLI Databricks.In addition to using the UI, you can start runs of the pipeline programmatically using the Databricks CLI.

Rechercher l’ID du travailFind the job id

Après avoir configuré le travail de pipeline dans l’interface utilisateur, copiez l' ID de travail à mesure que vous le transmettez à la jobs run-now commande CLI.After setting up the pipeline job in the UI, copy the Job ID as you pass it to the jobs run-now CLI command.

Voici un exemple de script bash que vous pouvez adapter pour votre flux de travail :Here’s an example bash script that you can adapt for your workflow:

# Generate a manifest file
cat <<HERE >manifest.csv
file_path,sample_id,paired_end,read_group_id
dbfs:/genomics/my_new_sample/*_R1_*.fastq.bgz,my_new_sample,1,read_group
dbfs:/genomics/my_new_sample/*_R2_*.fastq.bgz,my_new_sample,2,read_group
HERE

# Upload the file to DBFS
DBFS_PATH=dbfs:/genomics/manifests/$(date +"%Y-%m-%dT%H-%M-%S")-manifest.csv
databricks fs cp manifest.csv $DBFS_PATH

# Start a new run
databricks jobs run-now --job-id <job-id> --notebook-params "{\"manifest\": \"$DBFS_PATH\"}"

En plus de démarrer des exécutions à partir de la ligne de commande, vous pouvez utiliser ce modèle pour appeler le pipeline à partir de systèmes automatisés comme Jenkins.In addition to starting runs from the command line, you can use this pattern to invoke the pipeline from automated systems like Jenkins.

Bloc-notes DNASeq pipelineDNASeq pipeline notebook

Obtenir le notebookGet notebook