gatk4/gatk4_genomicsdbimport

variant calling

joint genotyping

germline

GATK

GATK4

GVCF

GenomicsDB

Description

Imports single-sample GVCFs into a GenomicsDB before joint genotyping.

GenomicsDBImport reads GVCF files produced by gatk4 HaplotypeCaller (or
similar tools) and consolidates them into a GenomicsDB datastore, a
scalable alternative to gatk4 CombineGVCFs for cohorts with large
numbers of samples. The initial import creates a new GenomicsDB workspace.

GATK Engine Options

Name	Type & Properties	Description
--interval_padding -ip	integer	Amount of padding (in bp) to add to each interval specified via `--intervals`, to capture flanking context (e.g. near capture/exome-bait edges). Default: 0. A commonly-used value in GATK's own exome workflows is `100`.
--sites_only_vcf_output	boolean_true	Only emit site-level information in the output VCF/GVCF, dropping the FORMAT/genotype columns. Useful for producing a compact, privacy-preserving sites-only VCF (e.g. for public release or QC).
--create_output_variant_index -OVI	boolean	Create a VCF index (`.tbi`) when writing a coordinate-sorted VCF output. Default: true.
--create_output_bam_index -OBI	boolean	Create a BAM/CRAM index when writing a coordinate-sorted BAM/CRAM output. Default: true.
--output_cram_version	string	CRAM version to write for CRAM output ('3.0' or '3.1'). Ignored for BAM/SAM output. Note that CRAM 3.1 cannot be read by tools that only support CRAM 3.0. Default: '3.1'.
--read_filter -RF	string multiple	Read filter(s) to apply before analysis, given by their GATK Java class name (e.g. `MappingQualityReadFilter`). Can be specified multiple times.
--disable_read_filter -DF	string multiple	Read filter(s) to disable before analysis, given by their GATK Java class name. Can be specified multiple times.
--disable_tool_default_read_filters	boolean_true	Disable all tool-default read filters. Many tools will not function correctly without their default read filters enabled, so use with caution.
--disable_sequence_dictionary_validation	boolean_true	Do not check the input sequence dictionaries for compatibility. Useful when combining files from different sources with mismatched (but compatible) dictionaries. Use at your own risk.

Name

Type & Properties

--interval_padding

-ip

integer

--sites_only_vcf_output

boolean_true

--create_output_variant_index

-OVI

boolean

--create_output_bam_index

-OBI

boolean

--output_cram_version

string

--read_filter

-RF

string

multiple

--disable_read_filter

-DF

string

multiple

--disable_tool_default_read_filters

boolean_true

--disable_sequence_dictionary_validation

boolean_true

Input

Name	Type & Properties	Description
--variant -V	file multiple	Single-sample GVCF files to import to GenomicsDB. Each file must contain data for only a single sample. Either this or `--sample_name_map` must be specified.
--sample_name_map	file	Tab-delimited file containing a mapping of sample name to file URI, one sample per line, e.g.: ``` sample1 /path/to/sample1.g.vcf.gz sample2 /path/to/sample2.g.vcf.gz ``` If specified, the header from the first sample is treated as the merged header rather than merging the headers, and sample names are taken from this file rather than the GVCF headers. This is an alternative to `--variant` and is a performance optimization for large cohorts, since it relaxes the normal checks for consistent headers.
--intervals -L	file required	One or more genomic intervals over which to operate, provided as a file (e.g. BED, interval_list). Unlike most other GATK tools, `--intervals` is mandatory for GenomicsDBImport. You may currently only import a single interval per workspace.

Name

Type & Properties

--variant

-V

file

multiple

--sample_name_map

file

--intervals

-L

file

required

Output

Name	Type & Properties	Description
--genomicsdb_workspace_path	file required output	Path for the GenomicsDB workspace to create. This must be an empty or non-existent directory (unless `--overwrite_existing_genomicsdb_workspace` is set). The resulting workspace directory can be consumed downstream by `gatk4 GenotypeGVCFs` by prefixing the path with `gendb://`.

Name

Type & Properties

--genomicsdb_workspace_path

file

required

output

Options

Name	Type & Properties	Description
--avoid_nio	boolean_true	If set, do not attempt to open the input GVCF file paths in Java. This can only be used together with `--bypass_feature_reader`, and allows operating on file systems which GenomicsDB understands how to open but GATK does not. This disables many sanity checks and cannot be used together with `--variant` (only with `--sample_name_map`). GATK also requires `--header` to be set whenever `--avoid_nio` is used.
--batch_size	integer	Batch size controls the number of samples for which readers are open at once and therefore provides a way to minimize memory consumption. However, it can take longer to complete. Use `--consolidate` if more than a hundred batches were used, to improve feature read time. A value of `0` means no batching (i.e. readers for all samples will be opened at once). Default: 0.
--bypass_feature_reader	boolean_true	If set, use htslib to read input GVCFs instead of GATK's FeatureReader. This reduces memory usage and can speed up the import. Lower memory requirements may also enable parallelism through `--max_num_intervals_to_import_in_parallel`. To enable this option, GVCFs must be normalized, block-compressed and indexed.
--consolidate	boolean_true	If set, merge all fragments into one. If importing data in batches, a new fragment is created for each batch. In case thousands of fragments are created, GenomicsDB feature readers will try to open ~20x as many files, and internally GenomicsDB would consume more memory to maintain bookkeeping data from all fragments. Merging can potentially improve read performance, however this has no effect if only one batch is used.
--genomicsdb_segment_size	integer	Buffer size in bytes allocated for GenomicsDB attributes during import. Should be large enough to hold data from one site. Default: 1048576.
--genomicsdb_shared_posixfs_optimizations	boolean_true	If set, allow for optimizations to improve the usability and performance for shared POSIX filesystems (e.g. NFS, Lustre). File level locking is disabled and file system writes are minimized by keeping a higher number of file descriptors open for longer periods of time. Use with `--batch_size` if keeping a large number of file descriptors open is an issue.
--genomicsdb_vcf_buffer_size	integer	Buffer size in bytes to store variant contexts. Larger values are better, as smaller values cause frequent disk writes. Default: 16384.
--header	file	VCF file to use instead of reading and combining headers from the input GVCFs. Cannot be used together with an incremental import into an existing GenomicsDB workspace.
--max_num_intervals_to_import_in_parallel	integer	Maximum number of intervals to import in parallel. Higher values may improve performance but require more memory and a higher number of file descriptors open at the same time. Default: 1.
--merge_contigs_into_num_partitions	integer	Number of GenomicsDB arrays to merge input intervals into. A value of `0` disables this merging. This option can only be used if entire contigs are specified as intervals: the tool will not split a contig into multiple arrays, so the actual number of partitions may be less than what is specified here. This can improve performance when importing a very large number of contigs (more than 100). Default: 0.
--merge_input_intervals	boolean_true	If set, import all data in between intervals. Improves performance using large lists of intervals, as in exome sequencing, especially if GVCF data only exists for specified intervals.
--overwrite_existing_genomicsdb_workspace	boolean_true	If set, overwrite `--genomicsdb_workspace_path` if it already exists. Otherwise a new workspace is created.
--reader_threads	integer	How many simultaneous threads to use when opening VCFs in batches. Higher values may improve performance when network latency is an issue. Multiple reader threads are not supported when running with multiple intervals. Default: 1.
--validate_sample_name_map	boolean_true	If set, enable checks on the `--sample_name_map` file. Verifies that feature readers are valid and shows a warning if sample names do not match with the headers.

Name

Type & Properties

--avoid_nio

boolean_true

--batch_size

integer

--bypass_feature_reader

boolean_true

--consolidate

boolean_true

--genomicsdb_segment_size

integer

--genomicsdb_shared_posixfs_optimizations

boolean_true

--genomicsdb_vcf_buffer_size

integer

--header

file

--max_num_intervals_to_import_in_parallel

integer

--merge_contigs_into_num_partitions

integer

--merge_input_intervals

boolean_true

--overwrite_existing_genomicsdb_workspace

boolean_true

--reader_threads

integer

--validate_sample_name_map

boolean_true

Run this component

Run the following command to execute this component with Nextflow:

cat > params.yaml <<'EOM'  
genomicsdb_workspace_path: "$id.$key.genomicsdb_workspace_path.genomicsdb_workspace"  
id: "run"  
publish_dir: "output/"  
EOM

nextflow run https://packages.viash-hub.com/vsh/biobox.git \  
  -revision v0.5.0 \  
  -main-script target/nextflow/gatk4/gatk4_genomicsdbimport/main.nf \  
  -params-file params.yaml

gatk4/gatk4_genomicsdbimport

GATK Engine Options

Input

Output

Options

Run this component

Relationships

Used by

Uses