LICENSE¶

Copyright [2015-2018] EMBL-European Bioinformatics Institute

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

AUTHORS¶

Rishi Nag <rishi@ebi.ac.uk>, original author.

Alessandro Vullo "<avullo at cpan.org>", the current developer and maintainer.

NAME¶

Bio::DB::HTS::VCF -- Read VCF/BCF data files

DESCRIPTION¶

This module provides a Perl interface to the HTSlib library for reading variant calls stored in VCF and BCF file databases.

The functions provided are for opening a VCF/BCF file, reading header values, querying specific chromosome intervals and then reading row values.

A sweep set of methods allows running through rows one by one, either backwards or forwards through the file.

SYNOPSIS¶

  use Bio::DB::HTS::VCF ;
  ### File Open ###
  my $v = Bio::DB::HTS::VCF->new( filename => "/path/to/myfile.vcf.gz" );
  # once the file has been opened, various global values can be read from the header
  my $h = $v->header();
  $h->get_seqnames() ;
  $h->version() ;  # read the VCF file version
  $h->num_samples() ;
  $h->get_sample_names() ; #return an array of sample names
  $h->num_seqnames() ;
  $h->get_seqnames() ; # return an array of sequence names
  ### Individual rows can be read in and fields accessed ###
  my $row = $v->next() ;
  # row functions
  $row->chromosome($h) ;
  $row->position() ;
  $row->id() ;
  $row->num_filters() ;
  $row->quality() ;
  # retrieve alleles
  my $num_alleles = $row->num_alleles();
  my $alleles = $row->get_alleles();
  my $allele_index = 1;
  for my $a (@$alleles) {
    printf( "(%s, %s)\n", $a, $row->get_variant_type($allele_index++) ) ;
  }
  # query filters
  $row->has_filter($h,"DP50");
  $row->has_filter($h,"."); # PASS filter check
  $row->get_info_type($h, "AF"); # one of "String", "Integer", "Float" or "Flag".
  $info_result = $row->get_info($h, "NS"); # [3]
  $row->get_format_type($h, "GT") ; # "String"
  $row->get_format($h, "DP") ; # [ 1, 8, 5 ]
  ### free memory associated with the row
  Bio::DB::HTS::VCF::Row->destroy($row);
  ### query specific locations
  my $iter = $v->query("20:1000000-1231000");
  while (my $result = $iter->next) {
    print $result->chromosome($h), $result->position(), $result->id(), $result->num_filters(), $result->quality(), "\n";
  }

METHODS¶

Querying an indexed VCF/BCF file¶

If the file is indexed, the file can be queried for variants on a specified region. Regions can be specified using either the "chr", "chr:start" or "chr:start-end" format, with start <= end.

Once an iterator is obtained, individual rows belonging to the result set can be sequentially accessed by iteratively invoking the iterator next method until it returns nothing.

HEADER METHODS¶

Once the file has been opened, various global values can be read from the header.

ROW METHODS¶

Individual rows can be read in and fields accessed. To read a row use the next function, which returns a Bio::DB::HTS::VCF::Row instance.

Various fields can then be read from the row object. Some of the functions to read these fields will need the header object supplied.

$row->print($header)

Returns a formatted textual representation of the row.

$row->chromosome($header)

$row->position()

$row->id()

$row->quality()

$row->reference()

VCF SWEEP OBJECTS¶

Open the file and process using sweeps. Note that the two methods maintain pointers that are independant of one another. Using the next_row() will start at the first row in the file and go on to the next row in subsequent reads. This is independant of previous_row() calls. Similarly previous_row() will start at the last row and read backwards. However a call to next_row() is needed beforehand as the read fails otherwise.

At the time of writing there are issues which seem to be due to the underlying HTSlib API calls, so using the next() function is preferable to using sweeps.

  use Bio::DB::HTS::VCF ;
  my $sweep = Bio::DB::HTS::VCFSweep->new(filename => "data/test.vcf.gz");
  $sweep->header;
  my $row_forwards = $sweep->next_row(); #returns first row in file
  my $row_backwards = $sweep->previous_row(); #returns last row in file
  my $row_forwards = $sweep->next_row(); # returns second row in file
  my $row_backwards = $sweep->previous_row(); #returns penultimate row in file