.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "Bio::SeqIO::mbsout 3pm"
.TH Bio::SeqIO::mbsout 3pm "2020-10-28" "perl v5.30.3" "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 "NAME"
Bio::SeqIO::mbsout \- input stream for output by Teshima et al.'s mbs.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Do not use this module directly.  Use it via the Bio::SeqIO class.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
mbs (Teshima \s-1KM,\s0 Innan H (2009) mbs: modifying Hudson's ms software to generate
samples of \s-1DNA\s0 sequences with a biallelic site under selection. \s-1BMC\s0
Bioinformatics 10: 166 ) can be found at
http://www.biomedcentral.com/1471\-2105/10/166/additional/.
.PP
Currently this object can be used to read output from mbs into seq objects.
However, because bioperl has no support for haplotypes created using an infinite
sites model (where '1' identifies a derived allele and '0' identifies an
ancestral allele), the sequences returned by mbsout are coded using A, T, C and
G. To decode the bases, use the sequence conversion table (a hash) returned by
\&\fBget_base_conversion_table()\fR. In the table, 4 and 5 are used when the ancestry is
unclear. This should not ever happen when creating files with mbs, but it will 
be used when creating mbsOUT files from a collection of seq objects ( To be 
added later ). Alternatively, use \fBget_next_hap()\fR to get a string with 1's and 
0's instead of a seq object.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to the
Bioperl mailing list. Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
of the bugs and their resolution. Bug reports can be submitted via the
web:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Warren Kretzschmar"
.IX Header "AUTHOR - Warren Kretzschmar"
This module was written by Warren Kretzschmar
.PP
email: wkretzsch@gmail.com
.PP
This module grew out of a parser written by Aida Andres.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.SS "Public Domain Notice"
.IX Subsection "Public Domain Notice"
This software/database is ``United States Government Work'' under the
terms of the United States Copyright Act. It was written as part of
the authors' official duties for the United States Government and thus
cannot be copyrighted. This software/database is freely available to
the public for use without a copyright notice. Restrictions cannot
be placed on its present or future use.
.PP
Although all reasonable efforts have been taken to ensure the accuracy
and reliability of the software and data, the National Human Genome
Research Institute (\s-1NHGRI\s0) and the U.S. Government does not and cannot
warrant the performance or results that may be obtained by using this
software or data.  \s-1NHGRI\s0 and the U.S. Government disclaims all
warranties as to performance, merchantability or fitness for any
particular purpose.
.SH "METHODS"
.IX Header "METHODS"
.SS "\s-1INTERNAL METHODS\s0"
.IX Subsection "INTERNAL METHODS"
\fI_initialize\fR
.IX Subsection "_initialize"
.PP
Title   : _initialize
Usage   : \f(CW$stream\fR = Bio::SeqIO::mbsout\->new($infile)
Function: extracts basic information about the file.
Returns : Bio::SeqIO object
Args    : no_og
Details	: include 'no_og' flag = 0 if the last population of an mbsout file 
          contains only one haplotype and you want the last haplotype to be 
          treated as the outgroup.
.PP
\fI_read_start\fR
.IX Subsection "_read_start"
.PP
Title   : _read_start
Usage   : \f(CW$stream\fR\->\fB_read_start()\fR
Function: reads from the filehandle \f(CW$stream\fR\->{_filehandle} all information up to the first haplotype (sequence). 
Returns : void
Args    : none
.SS "Methods to retrieve mbsout data"
.IX Subsection "Methods to retrieve mbsout data"
\fIget_segsites\fR
.IX Subsection "get_segsites"
.PP
Title   : get_segsites
Usage   : \f(CW$segsites\fR = \f(CW$stream\fR\->\fBget_segsites()\fR
Function: returns the number segsites in the mbsout file (according to the mbsout header line).
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_current_run_segsites\fR
.IX Subsection "get_current_run_segsites"
.PP
Title   : get_current_run_segsites
Usage   : \f(CW$segsites\fR = \f(CW$stream\fR\->\fBget_current_run_segsites()\fR
Function: returns the number of segsites in the run of the last read haplotype (sequence).
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_pop_mut_param_per_site\fR
.IX Subsection "get_pop_mut_param_per_site"
.PP
Title   : get_pop_mut_param_per_site
Usage   : \f(CW$pop_mut_param_per_site\fR = \f(CW$stream\fR\->\fBget_pop_mut_param_per_site()\fR
Function: returns 4*N0*mu or the \*(L"population mutation parameter per site\*(R"
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_pop_recomb_param_per_site\fR
.IX Subsection "get_pop_recomb_param_per_site"
.PP
Title   : get_pop_recomb_param_per_site
Usage   : \f(CW$pop_recomb_param_per_site\fR = \f(CW$stream\fR\->\fBget_pop_recomb_param_per_site()\fR
Function: returns 4*N0*r or the \*(L"population recombination parameter per site\*(R"
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_nsites\fR
.IX Subsection "get_nsites"
.PP
Title   : get_nsites
Usage   : \f(CW$nsites\fR = \f(CW$stream\fR\->\fBget_nsites()\fR
Function: returns the number of sites simulated by mbs.
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_selpos\fR
.IX Subsection "get_selpos"
.PP
Title   : get_selpos
Usage   : \f(CW$selpos\fR = \f(CW$stream\fR\->\fBget_selpos()\fR
Function: returns the location on the chromosome where the allele is located that was selected for by mbs.
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_nreps\fR
.IX Subsection "get_nreps"
.PP
Title   : get_nreps
Usage   : \f(CW$nreps\fR = \f(CW$stream\fR\->\fBget_nreps()\fR
Function: returns the number replications done by mbs on each trajectory file to create the mbsout file.
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_nfiles\fR
.IX Subsection "get_nfiles"
.PP
Title   : get_nfiles
Usage   : \f(CW$nfiles\fR = \f(CW$stream\fR\->\fBget_nfiles()\fR
Function: returns the number of trajectory files used by mbs to create the mbsout file
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_traj_filename\fR
.IX Subsection "get_traj_filename"
.PP
Title   : get_traj_filename
Usage   : \f(CW$traj_filename\fR = \f(CW$stream\fR\->\fBget_traj_filename()\fR
Function: returns the prefix of the trajectory files used by mbs to create the mbsout file
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_runs\fR
.IX Subsection "get_runs"
.PP
Title   : get_runs
Usage   : \f(CW$runs\fR = \f(CW$stream\fR\->\fBget_runs()\fR
Function: returns the number of runs in the mbsout file
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fIget_Positions\fR
.IX Subsection "get_Positions"
.PP
Title   : get_Positions
Usage   : \f(CW@positions\fR = \f(CW$stream\fR\->\fBget_Positions()\fR
Function: returns an array of the names of each segsite of the run of the last read hap.
Returns : array
Args    : \s-1NONE\s0
.PP
\fIget_tot_run_haps\fR
.IX Subsection "get_tot_run_haps"
.PP
Title   : get_tot_run_haps
Usage   : \f(CW$number_of_haps_per_run\fR = \f(CW$stream\fR\->\fBget_tot_run_haps()\fR
Function: returns the number of haplotypes (sequences) in each run of the mbsout file.
Returns : scalar >= 0
Args    : \s-1NONE\s0
.PP
\fIget_mbs_info_line\fR
.IX Subsection "get_mbs_info_line"
.PP
Title   : get_mbs_info_line
Usage   : \f(CW$mbs_info_line\fR = \f(CW$stream\fR\->\fBget_mbs_info_line()\fR
Function: returns the header line of the mbsout file.
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fItot_haps\fR
.IX Subsection "tot_haps"
.PP
Title   : tot_haps
Usage   : \f(CW$number_of_haplotypes_in_file\fR = \f(CW$stream\fR\->\fBtot_haps()\fR
Function: returns the number of haplotypes (sequences) in the mbsout file.  Information gathered from mbsout header line.
Returns : scalar
Args    : \s-1NONE\s0
.PP
\fInext_run_num\fR
.IX Subsection "next_run_num"
.PP
Title   : next_run_num
Usage   : \f(CW$next_run_number\fR = \f(CW$stream\fR\->\fBnext_run_num()\fR
Function: returns the number of the mbs run that the next haplotype (sequence) 
          will be taken from (starting at 1).  Returns undef if the complete 
          file has been read.
Returns : scalar > 0 or undef
Args    : \s-1NONE\s0
.PP
\fIget_last_haps_run_num\fR
.IX Subsection "get_last_haps_run_num"
.PP
Title   : get_last_haps_run_num
Usage   : \f(CW$last_haps_run_number\fR = \f(CW$stream\fR\->\fBget_last_haps_run_num()\fR
Function: returns the number of the ms run that the last haplotype (sequence)
          was taken from (starting at 1).  Returns undef if no hap has been
          read yet.
Returns : scalar > 0 or undef
Args    : \s-1NONE\s0
.PP
\fIget_last_read_hap_num\fR
.IX Subsection "get_last_read_hap_num"
.PP
Title   : get_last_read_hap_num
Usage   : \f(CW$last_read_hap_num\fR = \f(CW$stream\fR\->\fBget_last_read_hap_num()\fR
          Function: returns the number (starting with 1) of the last haplotype 
          read from the mbs file
Returns : scalar >= 0
Args    : \s-1NONE\s0
Details	: 0 means that no haplotype has been read yet.
.PP
\fIoutgroup\fR
.IX Subsection "outgroup"
.PP
Title   : outgroup
Usage   : \f(CW$outgroup\fR = \f(CW$stream\fR\->\fBoutgroup()\fR
Function: returns '1' if the mbsout object has an outgroup.  Returns '0' 
          otherwise.
Returns :  1 or 0, currently always 0
Args    : \s-1NONE\s0
Details	: This method will return '1' only if the last population in the mbsout 
          file contains only one haplotype.  If the last population is not an 
          outgroup then create the mbsout object using 'no_outgroup' as input 
          parameter for \fBnew()\fR (see mbsout\->\fBnew()\fR).
.PP
.Vb 2
\&          Currently there exists no way of introducing an outgroup into an mbs 
\&          file, so this function will always return \*(Aq0\*(Aq.
.Ve
.PP
\fIget_next_seq\fR
.IX Subsection "get_next_seq"
.PP
Title   : get_next_seq
Usage   : \f(CW$seq\fR = \f(CW$stream\fR\->\fBget_next_seq()\fR
Function: reads and returns the next sequence (haplotype) in the stream
Returns : Bio::Seq object
Args    : \s-1NONE\s0
Note	: This function is included only to conform to convention.  It only 
          calls \fBnext_hap()\fR and passes on that method's return value.  Use 
          \fBnext_hap()\fR instead for better performance.
.PP
\fIget_next_hap\fR
.IX Subsection "get_next_hap"
.PP
Title   : get_next_hap
Usage   : \f(CW$seq\fR = \f(CW$stream\fR\->\fBget_next_hap()\fR
Function: reads and returns the next sequence (haplotype) in the stream. Returns 
          void if all sequences in stream have been read.
Returns : Bio::Seq object
Args    : \s-1NONE\s0
Note	: Use this instead of \fBget_next_seq()\fR.
.PP
\fIget_next_run\fR
.IX Subsection "get_next_run"
.PP
Title   : get_next_run
Usage   : \f(CW@seqs\fR = \f(CW$stream\fR\->\fBget_next_run()\fR
Function: reads and returns all the remaining sequences (haplotypes) in the mbs 
          run of the next sequence.  
Returns : array of Bio::Seq objects
Args    : \s-1NONE\s0
.SS "\s-1METHODS TO RETRIEVE CONSTANTS\s0"
.IX Subsection "METHODS TO RETRIEVE CONSTANTS"
\fIbase_conversion_table\fR
.IX Subsection "base_conversion_table"
.PP
Title   : get_base_conversion_table
Usage   : \f(CW$table_hash_ref\fR = \f(CW$stream\fR\->\fBget_base_conversion_table()\fR
Function: returns a reference to a hash.  The keys of the hash are the letters 
          'A','T','G','C'.  The values associated with each key are the value 
          that each letter in the sequence of a seq object returned by a 
          Bio::SeqIO::mbsout stream should be translated to.
Returns : reference to a hash
Args    : \s-1NONE\s0  
Synopsis:
.PP
.Vb 3
\&        # retrieve the Bio::Seq object\*(Aqs sequence
\&        my $haplotype = $seq\->seq;
\&        my $rh_base_conversion_table = $stream\->get_base_conversion_table();
\&        
\&        # need to convert all letters to their corresponding numbers.
\&        foreach my $base (keys %{$rh_base_conversion_table}){
\&                $haplotype =~ s/($base)/$rh_base_conversion_table\->{$base}/g;
\&        }
\&        
\&        # $haplotype is now an ms style haplotype. (e.g. \*(Aq100101101455\*(Aq)
.Ve