# How to Open a VCF File: A Practical Guide for Viewing and Inspecting Genomic Variants A Variant Call Format file is not a contact card, even though both formats use the `.vcf` extension. In genomics, a VCF is a tab-delimited text file that records variants relative to a reference genome. You can open a small uncompressed VCF in a plain text editor, but that is only the simplest case. Large files, compressed `.vcf.gz` files, binary `.bcf` files, and indexed cohort datasets need tools that understand genomic coordinates and VCF metadata. This tutorial shows several safe ways to open a genomic VCF without corrupting it or mistaking an allele code for a biological conclusion. It starts with file identification, then covers quick inspection, BCFtools, genome browsers, spreadsheets, and programmatic reading. The examples are suitable for public or teaching datasets. Clinical and research files can contain sensitive genomic information, so use approved storage, access, and analysis systems for identifiable samples. ## At a Glance | What you need to do | Best starting method | Why | | --- | --- | --- | | Confirm that a file is genomic VCF | `file`, `head`, or BCFtools header view | Verifies compression and the VCF header | | Read a small `.vcf` | Plain text editor or pager | Fast and no conversion required | | Read a `.vcf.gz` | BCFtools or a gzip-aware pager | Preserves compression and avoids loading the entire file | | Read a `.bcf` | BCFtools | BCF is binary and is not human-readable | | View variants along a genome | IGV or another genome browser | Adds reference coordinates and track context | | Extract selected columns | `bcftools query` | Uses VCF-aware field definitions | | Analyze records in code | pysam, cyvcf2, or another VCF library | Preserves types and sample structure | | Browse a tiny table | Export selected fields to TSV, then open the TSV | Safer than opening the source VCF directly in a spreadsheet | ## Step 1: Identify What Kind of File You Have Start with the full filename. Common forms include: - `sample.vcf`, an uncompressed text VCF. - `sample.vcf.gz`, usually a BGZF-compressed VCF. - `sample.vcf.gz.tbi` or `sample.vcf.gz.csi`, an index, not the variant file itself. - `sample.bcf`, a binary representation of VCF data. - `sample.g.vcf.gz`, often a genomic VCF that may include reference blocks as well as variant sites. File extensions are useful but not conclusive. A file can be renamed incorrectly, incompletely downloaded, or compressed with ordinary gzip when an application expects block gzip. On macOS or Linux, inspect the file type before opening it: ```bash file sample.vcf file sample.vcf.gz ``` For an uncompressed file, view only the first few lines: ```bash head -n 20 sample.vcf ``` For a compressed file, use BCFtools if available: ```bash bcftools head sample.vcf.gz ``` The first line should normally begin with `##fileformat=VCFv4`. Metadata lines begin with two hash marks. The final header line begins with `#CHROM`. If the output contains names, phone numbers, and contact fields rather than genomic columns, it is probably an electronic contact-card file that happens to share the extension. Do not double-click an unknown `.vcf` and assume the operating system will choose the right program. Contact applications may claim the extension. Opening a copy through a text or genomics tool is safer. ## Step 2: Understand the Header Before Reading Variants A genomic VCF has a metadata header and a record table. The header is not decorative. It defines the reference assembly, filters, annotations, sample names, and the meaning of many values in the body. Use BCFtools to show the header: ```bash bcftools view --header-only sample.vcf.gz ``` Look for these elements: - `##fileformat` identifies the VCF specification version. - `##reference` may identify the reference assembly or FASTA source. - `##contig` lines describe chromosomes or contigs. - `##FILTER` lines define filter labels. - `##INFO` lines define site-level annotations. - `##FORMAT` lines define per-sample fields. - `#CHROM` begins the column header and lists samples after the `FORMAT` column. The eight required record columns are `CHROM`, `POS`, `ID`, `REF`, `ALT`, `QUAL`, `FILTER`, and `INFO`. Genotyped VCFs then add `FORMAT` and one or more sample columns. The official VCF specification explains their exact grammar and cardinality [1]. Check the reference build before comparing positions with another resource. The coordinate `chr1:100000` in one assembly does not necessarily describe the same reference base in another. Also note whether chromosome names use `1` or `chr1`. That naming difference can prevent indexing, annotation, or genome-browser loading even when the biological assembly is otherwise correct. ## Step 3: Open a Small Uncompressed VCF as Text For a small teaching file, a text editor is enough. Use an editor that preserves tabs and does not automatically change quotation marks, encodings, or line endings. Visual Studio Code, Sublime Text, or a read-only terminal pager is preferable to a word processor. ```bash less -S sample.vcf ``` The `-S` option prevents long variant lines from wrapping. Use the arrow keys to move horizontally and press `q` to quit. Search within `less` by pressing `/`, entering a chromosome, position, identifier, or filter label, and pressing Enter. Avoid editing the only copy. VCF is sensitive to delimiters and header definitions. A single converted tab, removed hash mark, or altered sample name can make downstream tools reject the file. If an edit is truly required, work on a version-controlled copy and validate the result afterward. Plain-text viewing is useful for orientation, but it is a poor method for interpreting a large multi-sample file. Genotype columns can be extremely wide, and the meaning of a value depends on the `FORMAT` order for that record. A value such as `0/1:35:18,17:99` cannot be interpreted reliably until you confirm whether the corresponding format is `GT:DP:AD:GQ` or something else. ## Step 4: Open Compressed VCF and BCF Files with BCFtools BCFtools is the standard command-line toolkit for viewing, filtering, converting, and querying VCF and BCF. Its manual states that commands work with uncompressed VCF, BGZF-compressed VCF, and BCF, with file type detected automatically [2]. Show the first records while retaining the header: ```bash bcftools view sample.vcf.gz | head -n 40 ``` Show records without metadata lines: ```bash bcftools view --no-header sample.vcf.gz | head ``` List sample names: ```bash bcftools query --list-samples sample.vcf.gz ``` Inspect one genomic region: ```bash bcftools view --regions chr1:100000-200000 sample.vcf.gz ``` Region queries normally require a compressed and indexed file. Create a BGZF-compressed copy and index it like this: ```bash bgzip -c sample.vcf > sample.vcf.gz bcftools index sample.vcf.gz ``` Do not use the same output name as the input file. Confirm that the compressed file opens before removing or archiving the original. For a quick integrity check, run: ```bash bcftools stats sample.vcf.gz > sample.vcf.stats.txt ``` Review the report for the number of records, samples, single-nucleotide variants, insertions, deletions, and other summary fields. A successful report does not prove biological validity, but obvious truncation, malformed records, and some header inconsistencies become easier to detect. ## Step 5: Extract a Readable Table with `bcftools query` `bcftools query` is safer than manually splitting lines because it understands fixed columns, INFO tags, and per-sample FORMAT values. The official query guide provides examples for positions, alleles, frequencies, and genotypes [3]. Extract chromosome, position, reference allele, alternate allele, quality, and filter: ```bash bcftools query \ --format '%CHROM\t%POS\t%REF\t%ALT\t%QUAL\t%FILTER\n' \ sample.vcf.gz ``` Write that output to a tab-separated file: ```bash bcftools query \ --format '%CHROM\t%POS\t%REF\t%ALT\t%QUAL\t%FILTER\n' \ sample.vcf.gz > selected-variants.tsv ``` Extract a site-level INFO field such as allele frequency only if its header definition exists: ```bash bcftools query \ --format '%CHROM\t%POS\t%REF\t%ALT\t%INFO/AF\n' \ sample.vcf.gz ``` Extract sample names, genotypes, and depth: ```bash bcftools query \ --format '%CHROM\t%POS[\t%SAMPLE\t%GT\t%DP]\n' \ sample.vcf.gz ``` Square brackets tell BCFtools to loop through samples. If a field is absent, output may contain a dot. A dot means missing according to VCF conventions, not zero. ## Step 6: View a VCF in a Genome Browser A genome browser is useful when you need spatial context rather than a long table. In Integrative Genomics Viewer, load the correct reference genome first, then load the VCF or indexed VCF track. If you also have alignment files, load the BAM or CRAM and its index so you can compare variant calls with read evidence. Before trusting the display, check: 1. The genome assembly matches the VCF reference. 2. Chromosome naming is compatible. 3. The file is sorted by genomic coordinate. 4. A compressed file is BGZF-compressed and has a matching index. 5. The region actually contains records. A browser displays what the file reports. It does not determine whether a call is clinically meaningful or whether the variant caller was configured correctly. Low depth, strand bias, mapping artifacts, paralogous regions, and representation differences can all produce plausible-looking tracks. ## Step 7: Use a Spreadsheet Only After Exporting Selected Fields Spreadsheets are convenient for a few hundred rows, but opening the source VCF directly is risky. Automatic type conversion can alter identifiers, scientific notation, dates, and long numeric strings. Wide genotype columns also exceed practical spreadsheet limits quickly. Export only the columns needed for review, save them as TSV, and import all identifier and allele columns as text. Keep the original VCF unchanged. Document the command used to make the table so the extraction is reproducible. If the dataset contains more rows than the spreadsheet supports, use BCFtools, R, Python, or a database. Splitting a VCF into arbitrary chunks for manual review makes it easy to lose headers, miss multiallelic context, or combine incompatible samples. ## Step 8: Read VCF Records in Python Without Parsing Tabs Manually For programmatic analysis, use a library designed for VCF rather than a generic CSV reader. `pysam.VariantFile`, `cyvcf2`, and related packages preserve header definitions, genotype structure, and typed values. Conceptually, a safe workflow looks like this: ```python import pysam vcf = pysam.VariantFile("sample.vcf.gz") print(list(vcf.header.samples)) for record in vcf.fetch("chr1", 99999, 200000): print(record.chrom, record.pos, record.ref, record.alts, record.filter.keys()) ``` The fetch interval uses the library's coordinate conventions, which may differ from the one-based `POS` field displayed in VCF. Confirm coordinate rules before joining with BED, GFF, or custom interval tables. Off-by-one errors are common when VCF, BED, and programming-language slices are combined. ## How to Read One Variant Record Consider a simplified record: ```text chr7 140453136 . A T 99 PASS DP=52;AF=0.48 GT:DP:AD:GQ 0/1:52:27,25:99 ``` It can be read as follows: - The record is on `chr7` at one-based position `140453136`. - The reference allele is `A` and the alternate allele is `T`. - `QUAL=99` is a caller-specific confidence measure, not a universal probability of clinical truth. - `FILTER=PASS` means the record passed the filters applied by the producing pipeline. It does not mean all possible quality checks were applied. - The site-level depth is reported as 52 in `INFO/DP`, if that is how the header defines it. - The sample genotype is heterozygous, `0/1`. - The sample depth is 52, with allele depths 27 and 25. - The genotype quality is 99. Always inspect the header definitions because tools may use the same tag differently or omit it. The VCF specification defines standard fields, but custom INFO and FORMAT tags are common [1]. ## Common Problems and Their Fixes | Problem | Likely cause | Practical fix | | --- | --- | --- | | The file opens in Contacts | Operating system associated `.vcf` with vCard | Open from a text editor or genomics tool | | Text looks like random symbols | File is compressed or binary | Use BCFtools, `zless`, or the appropriate decompressor | | Region query fails | File is unindexed, unsorted, or not BGZF-compressed | Sort, BGZF-compress, and index a copy | | Browser shows no variants | Assembly or chromosome names do not match | Confirm reference build and contig naming | | Spreadsheet changed values | Automatic type detection altered the table | Re-import selected TSV columns as text | | BCFtools reports undefined tags | Header and record fields disagree | Inspect the header and producing pipeline; do not invent definitions | | File ends unexpectedly | Download or transfer was incomplete | Compare checksums and download again | | Two files describe the same indel differently | Variants were not normalized | Normalize against the same reference before comparison | ## Validation Checklist Before Analysis - Confirm the file type and compression. - Record the reference assembly and contig naming scheme. - Inspect header definitions and sample names. - Verify that the file is complete using a checksum when one is supplied. - Use BCFtools stats or a pipeline-specific validation step. - Keep the original file read-only. - Export only the fields needed for spreadsheet review. - Treat missing values as missing, not zero. - Confirm coordinate conventions before joining other genomic formats. - Do not infer clinical significance directly from genotype, quality, or filter fields. ## Limitations and When to Escalate Opening a VCF confirms that software can read the file. It does not prove that calls are accurate, normalized, correctly annotated, or clinically interpretable. Escalate unexpected sample names, reference-build conflicts, malformed headers, security concerns, or clinically consequential interpretation to the responsible bioinformatician, laboratory director, or genetics professional. Preserve the original file and record every transformation used to create a review copy. ## Related Bioinformatics Guides - [Variant Call Format and BCFtools Processing](/knowledge/bioinformatics/sequence-algorithms/vcf-format-bcftools-genomic-variants) - [Beginner's Guide to Variant Annotation](/knowledge/bioinformatics/sequence-algorithms/a-beginner-s-guide-to-variant-annotation-from-vcf-to-functional-insights) - [Structural Variant Calling Methods Compared](/knowledge/bioinformatics/genomics-gwas/a-comprehensive-guide-to-structural-variant-calling-read-pair-split-read-read-depth-and-assembly-bas) - [Docker and Containerization in Reproducible Research](/knowledge/bioinformatics/infrastructure-policy/docker-and-containerization-in-reproducible-research) - [Browse the Bioinformatics Knowledge Hub](/knowledge/bioinformatics) ## References 1. Global Alliance for Genomics and Health Data Working Group. [VCF specification in the HTS specifications repository](https://samtools.github.io/hts-specs/). 2. BCFtools project. [BCFtools manual](https://samtools.github.io/bcftools/bcftools). 3. BCFtools project. [Extracting information from VCFs](https://samtools.github.io/bcftools/howtos/query.html). 4. BCFtools project. [Filtering VCF and BCF records](https://samtools.github.io/bcftools/howtos/filtering.html). 5. Danecek P, Auton A, Abecasis G, et al. [The Variant Call Format and VCFtools](https://pubmed.ncbi.nlm.nih.gov/21653522/). Bioinformatics. 2011. 6. National Center for Biotechnology Information. [dbVar VCF Submission Format](https://www.ncbi.nlm.nih.gov/core/assets/dbvar/files/dbVar_VCF_Submission.pdf).