Frequently Asked Questions¶
What input coverage do I need?¶
A mean of 100x over the MUC1 VNTR window on GRCh38 (290x on GRCh37, whose shorter window reads about 2.9 times higher) is recommended for reliable variant detection. Between 50x and 100x on GRCh38 a variant with a weak signal can be missed; below 50x variants are often missed. See Coverage thresholds. Whole-genome sequencing at 30x average depth typically yields sufficient VNTR coverage. Whole-exome sequencing coverage varies according to capture probe efficiency across the GC-rich MUC1 VNTR.
BAM versus FASTQ: which is faster?¶
BAM or CRAM input is significantly faster. With aligned input, VNtyper extracts only reads covering the MUC1 locus and unmapped read pools. FASTQ input requires whole-sample read alignment before downstream processing, substantially increasing runtime.
Do I need adVNTR?¶
No. adVNTR is an optional module providing independent, alignment-based validation of Kestrel calls. Enabling it adds approximately 9 minutes per sample. It is valuable for orthogonal confirmation in research workflows, but is not required for primary genotyping.
What does Low_Precision mean?¶
A call classified as Low_Precision indicates that Kestrel detected a variant, but its depth score falls between the configured low and high confidence thresholds in kestrel_config.json. These calls represent borderline read support and benefit from visual inspection in the HTML report or orthogonal validation. See Scoring & Confidence for threshold specifications.
Can I use GRCh38?¶
Yes. VNtyper 2 supports standard UCSC, NCBI, and Ensembl naming conventions via the --reference-assembly argument:
hg19orGRCh37(includinghg19_ensemblandhg19_ncbi)hg38orGRCh38(includinghg38_ensemblandhg38_ncbi)
Example:
Docker versus local installation?¶
Docker bundles all system dependencies (BWA, samtools, fastp, Java 11, and the Kestrel JAR) within a self-contained image. It provides the most reproducible execution environment.
A local installation avoids containerization overhead, but requires that BWA, samtools, fastp, and Java 11 reside on your PATH.
How do I interpret the HTML report?¶
The interactive HTML report displays an executive screening summary, variant calls with confidence tiers, quality control metrics, and, for a sample with a Kestrel call, an embedded IGV view of Kestrel's resolved haplotype records around the called position. Those records are not sequencing reads (see Kestrel output.bam evidence). A sample with no Kestrel call has no alignment view, and that is expected: see The report has no IGV alignment view. Refer to Output Files for a comprehensive field-by-field breakdown.
Does SHARK support BAM input?¶
No. SHARK operates directly on paired-end FASTQ reads to extract MUC1-matching reads prior to alignment. If invoked with --bam or --cram, the pipeline logs a warning and exits. When using --extra-modules shark, provide paired FASTQ files:
How do I process multi-sample cohorts?¶
Execute individual samples with vntyper pipeline, then aggregate the sample output directories with vntyper cohort. This generates cohort-wide summary reports, category breakdowns, and allele frequency tables. See Cohort Analysis.
A run failed with an error. Where do I start?¶
Search Troubleshooting for the first line of the error. It covers missing references ("Kestrel cannot run because required files are missing"), Kestrel errors, "no usable VCF", CRAM decoding, and running thousands of samples on a cluster.
Where can I get help?¶
Open an issue on GitHub. Search open and resolved issues before creating new tickets.