DNASeq-pipeline

Anteckning

Databricks Runtime för Genomics är inaktuell. Databricks bygger inte längre nya Databricks Runtime for Genomics-versioner och kommer att ta bort stödet för Databricks Runtime for Genomics den 24 september 2022 när Databricks Runtime for Genomics 7.3 LTS-stödet upphör. Då är Databricks Runtime för Genomics inte längre tillgängligt för val när du skapar ett kluster. Mer information om policyn och schemat för utfasningen av Databricks Runtime finns i Databricks Runtime-versioner som stöds och supportschema.

Anteckning

Följande biblioteksversioner är paketerade i Databricks Runtime 7.0 for Genomics. För bibliotek som ingår i lägre versioner Databricks Runtime för Genomics, se versionsanteckningarna.

Den Azure Databricks DNASeq-pipelinen är en GATK-bästa praxis-kompatibel pipeline för kort läsjustering, variantanrop och variantanteckningar. Den använder följande programvarupaket som parallelliseras med Spark.

  • BWA v0.7.17
  • ADAM v0.32.0
  • GATK HaplotypeCaller v4.1.4.1
  • SnpEff v4.3

Mer information om pipelineimplementering och förväntade körningar och kostnader för olika alternativkombinationer finns i Building the Fastest DNASeq Pipeline at Scala (Skapa den snabbaste DNASeq-pipelinen på Scala).

Installation

Pipelinen körs som ett Azure Databricks jobb. Du kan konfigurera en klusterprincip för att spara konfigurationen:

{
  "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"
  }
}
  • Klusterkonfigurationen bör använda Databricks Runtime för Genomics.
  • Uppgiften ska vara dnaseq-anteckningsboken som finns längst ned på den här sidan.
  • För bästa prestanda bör du använda de beräkningsoptimerade virtuella datorerna med minst 60 GB minne. Vi rekommenderar Standard_F32s_v2 virtuella datorer.
  • Om du kör omcalibration för baskvalitetspoäng använder du instanser för generell användning (Standard_D32s_v3) i stället eftersom den här åtgärden kräver mer minne.

Referensgenom

Du måste konfigurera referensgenomet med hjälp av miljövariabeln. Om du vill använda GRCh37 anger du miljövariabeln:

refGenomeId=grch37

Om du vill använda GRCh38 i stället ersätter grch37 du med grch38 .

Anpassade referensgenom

Anteckning

Anpassat stöd för referensgenom finns i Databricks Runtime 6.6 för Genomics och högre.

Följ dessa steg om du vill använda ett annat referensbygge än GRCh37 eller GRCh38:

  1. Förbered referensen för användning med BWA och GATK.

    Kataloginnehållet i referensgenomet ska innehålla följande filer:

    <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. Upload referensgenomfilerna till en katalog i molnlagring eller DBFS. Om du laddar upp filerna till molnlagringen måste du montera katalogen på en plats i DBFS.

  3. I klusterkonfigurationen anger du en miljövariabel REF_GENOME_PATH som pekar på sökvägen till fast-filen i DBFS. Exempel:

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

    Sökvägen får inte innehålla något dbfs: prefix.

    När du använder ett anpassat referensgenom hoppas SnpEff-anteckningsfasen över.

Tips

Under klusteritieringen använder Azure Databricks DNASeq-pipeline de tillhandahållna BWA-indexfilerna för att generera en indexavbildningsfil. Om du planerar att använda samma referensgenom många gånger kan du påskynda klusterstarten genom att skapa indexavbildningsfilen i förväg. Den här processen minskar klusterstarttiden med cirka 30 sekunder.

  1. Kopiera referensgenomkatalogen till drivrutinsnoden för ett Databricks Runtime för Genomics-kluster.

    %sh cp -r /dbfs/<reference_dir_path> /local_disk0/reference-genome
    
  2. Generera indexavbildningsfilen från BWA-indexfilerna.

    import org.broadinstitute.hellbender.utils.bwa._
    BwaMemIndex.createIndexImageFromIndexFiles("/local_disk0/reference-genome/<reference_name>.fa", "/local_disk0/reference-genome/<reference_name>.fa.img")
    
  3. Kopiera till indexavbildningsfilen till samma katalog som referensfilerna för fasta filer.

    %sh cp /local_disk0/reference-genome/<reference_name>.fa.img /dbfs/<reference_dir_path>
    
  4. Ta bort BWA-indexfiler som inte används ( .amb , , , , ) från .ann .bwt .pac .sa DBFS.

    %fs rm <file>
    

Parametrar

Pipelinen accepterar parametrar som styr dess beteende. De viktigaste och mest ändrade parametrarna dokumenteras här. resten finns i dnaseq-anteckningsboken. När du har importerat anteckningsboken och angett den som en jobbaktivitet kan du ange dessa parametrar för alla körningar eller per körning.

Parameter Standardvärde Beskrivning
manifest saknas Manifestet som beskriver indata.
utdata saknas Sökvägen där pipelineutdata ska skrivas.
replayMode hoppa över Något av följande:

* skip: faser hoppas över om utdata redan finns.
* overwrite: befintliga utdata tas bort.
exportVCF falskt Om sant skriver pipelinen resultat i VCF samt Delta Lake.
referenceConfidenceMode Ingen Något av följande:

* Om NONE , inkluderas endast variantplatser i utdata
* Om GVCF , inkluderas alla platser, med intilliggande referensplatser bandade.
* Om BP_RESOLUTION , inkluderas alla platser.
perSampleTimeout 12 h En tidsgräns som tillämpas per exempel. När tidsgränsen har nåtts fortsätter pipelinen till nästa exempel. Värdet för den här parametern måste innehålla en timeout-enhet: "s" för sekunder, "m" i minuter eller "h" i timmar. Till exempel resulterar "60 m" i en tidsgräns på 60 minuter.

Tips

Om du vill optimera körningstiden spark.sql.shuffle.partitions anger du Spark-konfigurationen till tre gånger antalet kärnor i klustret.

Anpassning

Du kan anpassa DNASeq-pipelinen genom att inaktivera läsjustering, variantanrop och variantanteckningar. Som standard är alla tre stegen aktiverade.

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

Om du vill inaktivera variantanteckningar anger du pipelinen på följande sätt:

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

De tillåtna faskombinationerna är:

Läsjustering Variant-anrop Variantanteckningar
true true true
true true falskt
true falskt falskt
falskt true true
falskt true falskt

Manifestformat

Anteckning

Manifestblobar stöds i Databricks Runtime 6.6 för Genomics och högre.

Manifestet är en CSV-fil eller blob som beskriver var indata FASTQ- eller BAM-filerna finns. Ett exempel:

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

Om dina indata består av ej justerade BAM-filer bör du utelämna paired_end fältet:

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

Tips

Om det angivna manifestet är en fil kan file_path fältet på varje rad vara en absolut sökväg eller en sökväg i förhållande till manifestfilen. Om det angivna manifestet är en blob måste file_path fältet vara en absolut sökväg. Du kan inkludera globs (*) för att matcha många filer.

Indataformat som stöds

  • Sam
  • Bam
  • Cram
  • Parquet
  • FASTQ
    • bgzip *.fastq.bgz (rekommenderas) bgzipped-filer *.fastq.gz med tillägget identifieras som bgz .
    • Okomprimerade *.fastq
    • Gzip *.fastq.gz

Viktigt

Gzippade filer kan inte delas upp. Välj kluster för automatisk skalning för att minimera kostnaderna för dessa filer.

Om du vill blockera komprimering av en FASTQ installerar du htslib, som innehåller den bgzip körbara filen.

Utdata

Justerade läsningar, som kallas varianter, och kommenterade varianter skrivs alla ut till Delta-tabeller i den angivna utdatakatalogen om motsvarande steg är aktiverade. Varje tabell partitioneras med exempel-ID. Om du dessutom har konfigurerat pipelinen för att exportera BAM:er eller VCO:er visas de även under utdatakatalogen.

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

När du kör pipelinen på ett nytt exempel visas den som en ny partition. Om du kör pipelinen för ett exempel som redan visas i utdatakatalogen skrivs partitionen över.

Eftersom all information är tillgänglig i Delta Lake kan du enkelt analysera den med Spark i Python, R, Scala eller SQL. Ett exempel:

Python

# 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"))

SQL

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

Felsökning

Jobbet är långsamt och få uppgifter körs

Anger vanligtvis att FASTQ-indatafilerna komprimeras med gzip i stället för bgzip . Gzipped-filer kan inte delas upp, så indata kan inte bearbetas parallellt. Prova att använda den parallella bgzip-notebook-filen för att konvertera en katalog med filer gzip från till bgzip parallellt.

Köra programmatiskt

Förutom att använda användargränssnittet kan du starta körningar av pipelinen programmatiskt med hjälp av Databricks CLI.

Hitta jobb-ID:t

När du har konfigurerat pipelinejobbet i användargränssnittet kopierar du jobb-ID:t när du skickar det till jobs run-now CLI-kommandot.

Här är ett exempel på ett bash-skript som du kan anpassa för ditt arbetsflöde:

# 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\"}"

Förutom att starta körningar från kommandoraden kan du använda det här mönstret för att anropa pipelinen från automatiserade system som Jenkins.

DNASeq pipeline notebook

Hämta notebook-fil