Struct Variant 

pub struct Variant { /* private fields */ }

A VCF/BCF variant record with convenient field accessors.

Variant wraps a rust_htslib::bcf::Record and provides methods for accessing standard VCF fields (CHROM, POS, REF, ALT, etc.) as well as INFO and FORMAT data.

Example

use htsvcf_core::variant::Variant;
use rust_htslib::bcf::{self, Read};

let mut reader = bcf::Reader::from_path("input.vcf.gz").unwrap();
for result in reader.records() {
    let record = result.unwrap();
    let variant = Variant::from_record(record);
    println!("{}:{} {}", variant.chrom(), variant.pos(), variant.reference());
}

Implementations

impl Variant

pub fn from_record(record: Record) -> Self

Create a Variant from a bcf::Record.

The record is unpacked and the chromosome name is cached for efficient access.

pub fn into_record(self) -> Record

Consume this Variant and return the underlying bcf::Record.

This is primarily used by writer bindings so write(variant) can consume a JS Variant without cloning.

pub fn record_mut(&mut self) -> &mut Record

Get a mutable reference to the underlying bcf::Record.

This is useful for passing the record to functions that need &mut bcf::Record, such as Writer::write_record.

pub fn chrom(&self) -> &str

Get the chromosome/contig name (CHROM column).

pub fn rid(&self) -> Option<u32>

Get the reference sequence ID (rid) from the header, if present.

pub fn start(&self) -> i64

Get the zero-based start position.

This is the internal representation used by htslib. For 1-based VCF coordinates, use pos().

pub fn pos(&self) -> i64

Get the 1-based position (POS column).

This matches the coordinate shown in VCF files.

pub fn end(&self) -> i64

Get the end coordinate (htslib semantics).

For SNPs this equals start + 1. For indels and other variants, this reflects the span of the reference allele.

pub fn id(&self) -> String

Get the variant ID (ID column).

Returns “.” if no ID is set.

pub fn set_id(&mut self, id: &str) -> Result<(), Error>

Set the variant ID (ID column).

Pass an empty string or “.” to clear the ID.

pub fn reference(&self) -> String

Get the reference allele (REF column).

pub fn alts(&self) -> Vec<String>

Get the alternate alleles (ALT column).

Returns a vector of alternate allele strings. May be empty if there are no alternates.

pub fn qual(&self) -> Option<f32>

Get the quality score (QUAL column).

Returns None if QUAL is missing (. in VCF).

pub fn set_qual(&mut self, qual: Option<f32>)

Set the quality score (QUAL column).

Pass None to set QUAL to missing (.).

pub fn filters(&self) -> Vec<String>

Return the FILTER column as a list of filter IDs.

Records that are ‘.’ return an empty list.

pub fn set_filters(&mut self, filters: &[String]) -> Result<(), Error>

Set the FILTER column.

Pass an empty slice, [""], or ["."] to clear all filters. Otherwise, provide an array of filter names to set.

pub fn set_info_flag( &mut self, header: &Header, tag: &str, is_set: bool, ) -> Result<(), Error>

Set an INFO flag value.

Pass true to set the flag, false to clear it. Returns an error if the tag is not defined in the header or is not a Flag type.

pub fn set_info_integer( &mut self, header: &Header, tag: &str, values: &[i32], ) -> Result<(), Error>

Set an INFO integer value.

Pass a slice of integers to set. For scalar fields (Number=1), pass a single-element slice. Returns an error if the tag is not defined in the header or is not an Integer type.

pub fn set_info_float( &mut self, header: &Header, tag: &str, values: &[f32], ) -> Result<(), Error>

Set an INFO float value.

Pass a slice of floats to set. For scalar fields (Number=1), pass a single-element slice. Returns an error if the tag is not defined in the header or is not a Float type.

pub fn set_info_string( &mut self, header: &Header, tag: &str, values: &[String], ) -> Result<(), Error>

Set an INFO string value.

Pass a slice of strings to set. For scalar fields (Number=1), pass a single-element slice. Returns an error if the tag is not defined in the header or is not a String type.

pub fn translate(&mut self, header: &Header) -> Result<(), Error>

Translate this record to a new header.

This is required when you mutate the header (e.g. add a new INFO field) and then want to set values for those new tags.

IMPORTANT: this does not duplicate/copy the header.

pub fn clear_info(&mut self, header: &Header, tag: &str) -> Result<(), Error>

Clear (remove) an INFO field from the record.

Returns an error if the tag is not defined in the header.

pub fn set_format_integer( &mut self, header: &Header, tag: &str, values: &[i32], ) -> Result<(), Error>

Set a FORMAT integer field.

The values slice should be flattened: for a field with n values per sample and s samples, provide s * n values in sample-major order.

Use format_int_missing() to represent missing values.

Errors

Returns an error if the tag is not defined, is not Integer type, or is “GT”.

pub fn set_format_float( &mut self, header: &Header, tag: &str, values: &[f32], ) -> Result<(), Error>

Set a FORMAT float field.

The values slice should be flattened: for a field with n values per sample and s samples, provide s * n values in sample-major order.

Use format_float_missing() to represent missing values.

Errors

Returns an error if the tag is not defined or is not Float type.

pub fn set_format_string( &mut self, header: &Header, tag: &str, values: &[String], ) -> Result<(), Error>

Set a FORMAT string field.

Provide one string per sample.

Errors

Returns an error if the tag is not defined, is not String type, or is “GT”.

pub fn clear_format(&mut self, header: &Header, tag: &str) -> Result<(), Error>

Clear (remove) a FORMAT field from this record.

Errors

Returns an error if the tag is not defined in the header or is “GT”.

pub fn info(&self, header: &Header, tag: &str) -> InfoValue

Get an INFO field value by tag name.

Returns the appropriate InfoValue variant based on the tag’s type as defined in the header. Returns InfoValue::Absent if the tag is not present in this record.

pub fn format(&self, header: &Header, tag: &str) -> FormatValue

Get a FORMAT field value by tag name.

Returns a FormatValue::PerSample containing values for all samples, or FormatValue::Absent if the tag is not present in this record.

pub fn sample( &self, header: &Header, sample: &str, ) -> Option<Vec<(String, FormatValue)>>

Get all FORMAT field values for a single sample by name.

Returns a vector of (tag_name, value) pairs for all FORMAT fields present in this record, plus a genotype entry with the parsed GT and a sample_name entry with the sample’s name. Returns None if the sample is not found.

pub fn samples( &self, header: &Header, subset: Option<&[&str]>, ) -> Vec<Vec<(String, FormatValue)>>

Returns samples’ FORMAT data as an array of objects.

If subset is None, returns all samples in header order. If subset is Some(names), returns only the specified samples in the order given. Unknown sample names are silently skipped.

Each element contains all FORMAT fields plus a sample_name key. Returns an empty Vec if the VCF has no samples or no requested samples exist.

pub fn genotypes( &self, header: &Header, subset: Option<&[&str]>, ) -> Vec<Genotype>

Get parsed genotypes for all samples or a subset.

Returns a vector of Genotype structs, one per requested sample. If subset is None, returns genotypes for all samples in header order. If subset is Some(names), returns genotypes only for those samples in the order specified (unknown sample names are skipped).

Returns an empty vector if the record has no GT field or no samples.

pub fn set_genotypes(&mut self, genotypes: &[Genotype]) -> Result<(), Error>

Set genotypes for all samples.

Takes a slice of Genotype structs (same format returned by Variant::genotypes()). The length should match the sample count.

Errors

Returns an error if the GT field cannot be set (e.g., not defined in header).

pub fn to_string(&self, header: &Header) -> Option<String>

Format the record as a VCF line string.

Returns the record formatted as a tab-separated VCF line (without newline), or None if formatting fails.

Trait Implementations

impl Debug for Variant

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.