.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::DB::HTS::VCF 3pm"
.TH Bio::DB::HTS::VCF 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "LICENSE"
.IX Header "LICENSE"
Copyright [2015\-2018] EMBL-European Bioinformatics Institute
.PP
Licensed under the Apache License, Version 2.0 (the \*(L"License\*(R");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
.PP
.Vb 1
\&     http://www.apache.org/licenses/LICENSE\-2.0
.Ve
.PP
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an \*(L"\s-1AS IS\*(R" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,\s0 either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.SH "AUTHORS"
.IX Header "AUTHORS"
Rishi Nag <rishi@ebi.ac.uk>, original author.
.PP
Alessandro Vullo \f(CW\*(C`<avullo at cpan.org>\*(C'\fR, the current developer and maintainer.
.SH "NAME"
Bio::DB::HTS::VCF \-\- Read VCF/BCF data files
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a Perl interface to the HTSlib library for reading variant calls 
stored in \s-1VCF\s0 and \s-1BCF\s0 file databases.
.PP
The functions provided are for opening a \s-1VCF/BCF\s0 file, reading header values, querying 
specific chromosome intervals and then reading row values.
.PP
A sweep set of methods allows running through rows one by one, either backwards or
forwards through the file.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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)\en", $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(), "\en";
\&  }
.Ve
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS """new"""
.el .SS "\f(CWnew\fP"
.IX Subsection "new"
Opens a \s-1VCF/BCF\s0 file for reading. If the file is indexed (i.e. tabix for \s-1VCF,\s0 csi for \s-1BCF\s0) 
the index is opened and used for querying arbitrary locations on the chromosomes.
.ie n .IP "$vcf = Bio::DB::HTS::VCF\->new($filepath)" 1
.el .IP "\f(CW$vcf\fR = Bio::DB::HTS::VCF\->new($filepath)" 1
.IX Item "$vcf = Bio::DB::HTS::VCF->new($filepath)"
Returns an instance of Bio::DB::HTS::VCF.
.ie n .SS """header"""
.el .SS "\f(CWheader\fP"
.IX Subsection "header"
Returns instance of Bio::DB::HTS::VCF::Header, representing the header of the file.
.ie n .IP "$header = $vcf\->\fBheader()\fR" 1
.el .IP "\f(CW$header\fR = \f(CW$vcf\fR\->\fBheader()\fR" 1
.IX Item "$header = $vcf->header()"
.ie n .SS """num_variants"""
.el .SS "\f(CWnum_variants\fP"
.IX Subsection "num_variants"
Returns the number of variants (i.e. rows) of the file.
.ie n .IP "$nv = $vcf\->\fBnum_variants()\fR;" 1
.el .IP "\f(CW$nv\fR = \f(CW$vcf\fR\->\fBnum_variants()\fR;" 1
.IX Item "$nv = $vcf->num_variants();"
.ie n .SS """close"""
.el .SS "\f(CWclose\fP"
.IX Subsection "close"
Close the \s-1VCF/BCF\s0 file, allocated memory will be released, included the index, if present.
.ie n .IP "$vcf\->\fBclose()\fR" 1
.el .IP "\f(CW$vcf\fR\->\fBclose()\fR" 1
.IX Item "$vcf->close()"
.ie n .SS """next"""
.el .SS "\f(CWnext\fP"
.IX Subsection "next"
Returns the next row (starting from the first one) read from the file.
.ie n .IP "$row = $vcf\->\fBnext()\fR" 4
.el .IP "\f(CW$row\fR = \f(CW$vcf\fR\->\fBnext()\fR" 4
.IX Item "$row = $vcf->next()"
Returns an instance of Bio::DB::HTS::VCF::Row or undef if end of file is reached.
.SH "Querying an indexed VCF/BCF file"
.IX Header "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 \*(L"chr\*(R", \*(L"chr:start\*(R" or \*(L"chr:start\-end\*(R" format,
with start <= end.
.PP
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.
.ie n .SS """query"""
.el .SS "\f(CWquery\fP"
.IX Subsection "query"
.ie n .IP "$iterator = $vcf\->query($region);" 1
.el .IP "\f(CW$iterator\fR = \f(CW$vcf\fR\->query($region);" 1
.IX Item "$iterator = $vcf->query($region);"
Returns an instance of Bio::DB::HTS::VCF::Iterator or undef if the chromosome is not 
found in the index or raises an exception in case the underlying HTSlib library cannot 
parse the region.
.SH "HEADER METHODS"
.IX Header "HEADER METHODS"
Once the file has been opened, various global values can be read from the header.
.ie n .SS """version"""
.el .SS "\f(CWversion\fP"
.IX Subsection "version"
Returns the \s-1VCF\s0 file version, as a string
.ie n .IP "$h\->\fBversion()\fR" 1
.el .IP "\f(CW$h\fR\->\fBversion()\fR" 1
.IX Item "$h->version()"
.ie n .SS """num_samples"""
.el .SS "\f(CWnum_samples\fP"
.IX Subsection "num_samples"
Returns the number of samples
.ie n .IP "$h\->\fBnum_samples()\fR" 1
.el .IP "\f(CW$h\fR\->\fBnum_samples()\fR" 1
.IX Item "$h->num_samples()"
.ie n .SS """get_sample_names"""
.el .SS "\f(CWget_sample_names\fP"
.IX Subsection "get_sample_names"
Returns the list of sample names
.ie n .IP "$sample_names = $h\->\fBget_sample_names()\fR" 1
.el .IP "\f(CW$sample_names\fR = \f(CW$h\fR\->\fBget_sample_names()\fR" 1
.IX Item "$sample_names = $h->get_sample_names()"
Returns an array ref of strings representing the sample names
.ie n .SS """get_seqnames"""
.el .SS "\f(CWget_seqnames\fP"
.IX Subsection "get_seqnames"
Returns the number of sequence names
.ie n .IP "$h\->\fBnum_seqnames()\fR" 1
.el .IP "\f(CW$h\fR\->\fBnum_seqnames()\fR" 1
.IX Item "$h->num_seqnames()"
.ie n .SS """get_seqnames"""
.el .SS "\f(CWget_seqnames\fP"
.IX Subsection "get_seqnames"
Returns the list of sequence names
.ie n .IP "$h\->\fBget_seqnames()\fR" 1
.el .IP "\f(CW$h\fR\->\fBget_seqnames()\fR" 1
.IX Item "$h->get_seqnames()"
Returns an array ref of strings representing the sequence names
.ie n .SS """fmt_text"""
.el .SS "\f(CWfmt_text\fP"
.IX Subsection "fmt_text"
Get header formatted text, as a string
.ie n .IP "$h\->\fBfmt_text()\fR" 1
.el .IP "\f(CW$h\fR\->\fBfmt_text()\fR" 1
.IX Item "$h->fmt_text()"
Returns the text string representing the content of the header
.SH "ROW METHODS"
.IX 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.
.PP
Various fields can then be read from the row object. Some of the functions to read these 
fields will need the header object supplied.
.ie n .IP "$row\->print($header)" 6
.el .IP "\f(CW$row\fR\->print($header)" 6
.IX Item "$row->print($header)"
Returns a formatted textual representation of the row.
.ie n .IP "$row\->chromosome($header)" 6
.el .IP "\f(CW$row\fR\->chromosome($header)" 6
.IX Item "$row->chromosome($header)"
.PD 0
.ie n .IP "$row\->\fBposition()\fR" 6
.el .IP "\f(CW$row\fR\->\fBposition()\fR" 6
.IX Item "$row->position()"
.ie n .IP "$row\->\fBid()\fR" 6
.el .IP "\f(CW$row\fR\->\fBid()\fR" 6
.IX Item "$row->id()"
.ie n .IP "$row\->\fBquality()\fR" 6
.el .IP "\f(CW$row\fR\->\fBquality()\fR" 6
.IX Item "$row->quality()"
.ie n .IP "$row\->\fBreference()\fR" 6
.el .IP "\f(CW$row\fR\->\fBreference()\fR" 6
.IX Item "$row->reference()"
.PD
.SS "Accessing alleles information"
.IX Subsection "Accessing alleles information"
.ie n .IP "$row\->\fBnum_alleles()\fR" 2
.el .IP "\f(CW$row\fR\->\fBnum_alleles()\fR" 2
.IX Item "$row->num_alleles()"
Returns the number of alleles
.ie n .IP "$row\->\fBget_alleles()\fR" 2
.el .IP "\f(CW$row\fR\->\fBget_alleles()\fR" 2
.IX Item "$row->get_alleles()"
Returns the alleles as strings in an array ref
.PP
The variant type of an allele can be determined using the index of the allele. The index starts
from 1 for the first allele:
.ie n .IP "$row\->\fBis_snp()\fR" 2
.el .IP "\f(CW$row\fR\->\fBis_snp()\fR" 2
.IX Item "$row->is_snp()"
Returns a true value if the row refers to a \s-1SNP.\s0
.ie n .IP "$row\->get_variant_type($allele_index)" 2
.el .IP "\f(CW$row\fR\->get_variant_type($allele_index)" 2
.IX Item "$row->get_variant_type($allele_index)"
This will return one of the values as defined in htslib. As of v1.3.1 these are as follows.
.RS 2
.IP "\s-1VCF_REF\s0   0" 5
.IX Item "VCF_REF 0"
.PD 0
.IP "\s-1VCF_SNP\s0   1" 5
.IX Item "VCF_SNP 1"
.IP "\s-1VCF_MNP\s0   2" 5
.IX Item "VCF_MNP 2"
.IP "\s-1VCF_INDEL 4\s0" 5
.IX Item "VCF_INDEL 4"
.IP "\s-1VCF_OTHER 8\s0" 5
.IX Item "VCF_OTHER 8"
.RE
.RS 2
.RE
.PD
.SS "Row filters"
.IX Subsection "Row filters"
Each row object has filters that may or may not have been applied to it.
.ie n .IP "$row\->\fBnum_filters()\fR" 2
.el .IP "\f(CW$row\fR\->\fBnum_filters()\fR" 2
.IX Item "$row->num_filters()"
Returns the number of filters of the row.
.ie n .IP "$row\->has_filter($header, $filter)" 2
.el .IP "\f(CW$row\fR\->has_filter($header, \f(CW$filter\fR)" 2
.IX Item "$row->has_filter($header, $filter)"
Returns 0 if the filter is not present, 1 if it is present. The \s-1PASS\s0 filter is represented by a dot.
.SS "Accessing info fields"
.IX Subsection "Accessing info fields"
Each row may have additional info fields associated with each allele in the row.
.ie n .IP "$row\->get_info_type($header, $info_id)" 2
.el .IP "\f(CW$row\fR\->get_info_type($header, \f(CW$info_id\fR)" 2
.IX Item "$row->get_info_type($header, $info_id)"
Returns the type of the info \s-1ID\s0 as specified in the \s-1VCF\s0 file header, one of \*(L"String\*(R", \*(L"Integer\*(R", \*(L"Float\*(R" or \*(L"Flag\*(R".
.ie n .IP "$row\->get_info($header, $info_id) or $row\->get_info($header)" 2
.el .IP "\f(CW$row\fR\->get_info($header, \f(CW$info_id\fR) or \f(CW$row\fR\->get_info($header)" 2
.IX Item "$row->get_info($header, $info_id) or $row->get_info($header)"
If an info_id string is passed, returns an array ref of values for that particular info field, 
one for each allele in the row. If the row does not have an item of that info, or it does not 
exist in the file, a string \*(L"\s-1ID_NOT_FOUND\*(R"\s0 will be returned.
.Sp
Alternatively, the \fBget_info()\fR method can be invoked by just passing the header. In this case,
the whole info field is returned organised as a hash ref where keys are the info IDs and values
are the info fields for the corresponding \s-1ID.\s0
.SS "Accessing format fields"
.IX Subsection "Accessing format fields"
Formats are dealt with similarly to info fields.
.ie n .IP "$row\->get_format_type($header, $format_id)" 2
.el .IP "\f(CW$row\fR\->get_format_type($header, \f(CW$format_id\fR)" 2
.IX Item "$row->get_format_type($header, $format_id)"
Returns the type of the format \s-1ID\s0 as specified in the \s-1VCF\s0 file header, one of \*(L"String\*(R", \*(L"Integer\*(R", \*(L"Float\*(R" or \*(L"Flag\*(R".
.ie n .IP "$row\->get_format($header, $format_id) or $row\->get_format($header)" 2
.el .IP "\f(CW$row\fR\->get_format($header, \f(CW$format_id\fR) or \f(CW$row\fR\->get_format($header)" 2
.IX Item "$row->get_format($header, $format_id) or $row->get_format($header)"
If a format_id string is passed, returns an array ref of values for that particular format \s-1ID.\s0 
If the row does not have an item of that format, or it does not exist in the file, a string 
\&\*(L"\s-1ID_NOT_FOUND\*(R"\s0 will be returned.
.Sp
Alternatively, the \fBget_format()\fR method can be invoked by just passing the header. In this case,
it returns the complete format specification as a hash ref of \s-1FORMAT_ID\s0 => [ \s-1FORMAT_ID_VALUE, ...\s0 ].
.SS "Accessing genotypes"
.IX Subsection "Accessing genotypes"
Genotype records are currently returned as a series of integers, across all the samples for the row.
.ie n .IP "$row\->get_genotypes($header)" 1
.el .IP "\f(CW$row\fR\->get_genotypes($header)" 1
.IX Item "$row->get_genotypes($header)"
Returns an array reference of integers representing genotype records.
.SH "VCF SWEEP OBJECTS"
.IX Header "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 \fBnext_row()\fR will start at the first row in the file
and go on to the next row in subsequent reads. This is independant of \fBprevious_row()\fR calls.
Similarly \fBprevious_row()\fR will start at the last row and read backwards. However a call to \fBnext_row()\fR
is needed beforehand as the read fails otherwise.
.PP
At the time of writing there are issues which seem to be due to the underlying HTSlib \s-1API\s0 calls,
so using the \fBnext()\fR function is preferable to using sweeps.
.PP
.Vb 1
\&  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
.Ve