.\" 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
.\" ========================================================================
.\"
.IX Title "Bio::Seq::SimulatedRead 3pm"
.TH Bio::Seq::SimulatedRead 3pm "2021-08-15" "perl v5.32.1" "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::Seq::SimulatedRead \- Read with sequencing errors taken from a reference sequence
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Bio::Seq::SimulatedRead;
\&    use Bio::PrimarySeq;
\&  
\&    # Create a reference sequence
\&    my $genome = Bio::PrimarySeq\->new( \-id    => \*(Aqhuman_chr2\*(Aq,
\&                                       \-seq   => \*(AqTAAAAAAACCCCTG\*(Aq,
\&                                       \-desc  => \*(AqThe human genome\*(Aq );
\&
\&    # A 10\-bp error\-free read taken from a genome
\&    my $read = Bio::Seq::SimulatedRead\->new(
\&       \-reference => $genome  , # sequence to generate the read from
\&       \-id        => \*(Aqread001\*(Aq, # read ID
\&       \-start     => 3        , # start of the read on the genome forward strand
\&       \-end       => 12       , # end of the read on the genome forward strand
\&       \-strand    => 1        , # genome strand that the read is on
\&    );
\&
\&    # Display the sequence of the read
\&    print $read\->seq."\en";
\&
\&    # Add a tag or MID to the beginning of the read
\&    $read\->mid(\*(AqACGT\*(Aq);
\&
\&    # Add sequencing errors (error positions are 1\-based and relative to the
\&    # error\-free MID\-containing read)
\&    my $errors = {};
\&    $errors\->{\*(Aq8\*(Aq}\->{\*(Aq+\*(Aq} = \*(AqAAA\*(Aq; # insertion of AAA after residue 8
\&    $errors\->{\*(Aq1\*(Aq}\->{\*(Aq%\*(Aq} = \*(AqG\*(Aq;   # substitution of residue 1 by a G
\&    $errors\->{\*(Aq4\*(Aq}\->{\*(Aq\-\*(Aq} = undef; # deletion of residue 4
\&    $read\->errors($errors);
\&
\&    # Display the sequence of the read with errors
\&    print $read\->seq."\en";
\&
\&    # String representation of where the read came from and its errors
\&    print $read\->desc."\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object is a simulated read with sequencing errors. The user can provide a
reference sequence to take a read from, the position and orientation of the 
read on the reference sequence, and the sequencing errors to generate.
.PP
The sequence of the read is automatically calculated based on this information.
By default, the description of the reads contain tracking information and will
look like this (Bioperl-style):
.PP
.Vb 1
\&  reference=human_chr2 start=3 end=12 strand=\-1 mid=ACGT errors=1%G,4\-,8+AAA description="The human genome"
.Ve
.PP
or Genbank-style:
.PP
.Vb 1
\&  reference=human_chr2 position=complement(3..12) mid=ACGT errors=1%G,4\-,8+AAA description="The human genome"
.Ve
.PP
Creating a simulated read follows these steps:
  1/ Define the read \fBstart()\fR, \fBend()\fR, \fBstrand()\fR and \fBqual_levels()\fR if you want
     quality scores to be generated. Do not change these values once set because
     the read will not be updated.
  2/ Specify the reference sequence that the read should be taken from. Once
     this is done, you have a fully functional read. Do not use the \fBreference()\fR
     method again after you have gone to the next step.
  3/ Use \fBmid()\fR to input a \s-1MID\s0 (or tag or barcode) to add to the beginning of the
     read. You can change the \s-1MID\s0 until you go to next step.
  4/ Give sequencing error specifications using \fBerrors()\fR as the last step. You
     can do that as many times as you like, and the read will be updated.
.SH "AUTHOR"
.IX Header "AUTHOR"
Florent E Angly <florent . angly @ gmail\-dot\-com>.
.PP
Copyright (c) 2011 Florent E Angly.
.PP
This library is free software; you can redistribute it under the \s-1GNU\s0 General
Public License version 3.
.SS "new"
.IX Subsection "new"
.Vb 10
\& Title    : new
\& Function : Create a new simulated read object
\& Usage    : my $read = Bio::Seq::SimulatedRead\->new(
\&               \-id        => \*(Aqread001\*(Aq,
\&               \-reference => $seq_obj ,
\&               \-errors    => $errors  ,
\&               \-start     => 10       ,
\&               \-end       => 135      ,
\&               \-strand    => 1        ,
\&            );
\& Arguments: \-reference   => Bio::SeqI, Bio::PrimarySeqI object representing the
\&                            reference sequence to take the read from. See
\&                            reference().
\&            \-errors      => Hashref representing the position of errors in the read
\&                            See errors().
\&            \-mid         => String of a MID to prepend to the read. See mid().
\&            \-track       => Track where the read came from in the read description?
\&                            See track().
\&            \-coord_style => Define what coordinate system to use. See coord_style().
\&            All other methods from Bio::LocatableSeq are available.
\& Returns  : new Bio::Seq::SimulatedRead object
.Ve
.SS "qual_levels"
.IX Subsection "qual_levels"
.Vb 10
\& Title    : qual_levels
\& Function : Get or set the quality scores to give to the read. By default, if your
\&            reference sequence does not have quality scores, no quality scores
\&            are generated for the simulated read. The generated quality scores
\&            are very basic. If a residue is error\-free, it gets the quality score
\&            defined for good residues. If the residue has an error (is an
\&            addition or a mutation), the residue gets the quality score specified
\&            for bad residues. Call the qual_levels() method before using the
\&            reference() method.
\& Usage    : my $qual_levels = $read\->qual_levels( );
\& Arguments: Array reference containing the quality scores to use for:
\&            1/ good residues (e.g. 30)
\&            2/ bad residues (e.g. 10)
\& Returns  : Array reference containing the quality scores to use.
.Ve
.SS "reference"
.IX Subsection "reference"
.Vb 8
\& Title    : reference
\& Function : Get or set the reference sequence that the read comes from. Once the
\&            reference has been set, you have a functional simulated read which
\&            supports all the Bio::LocatableSeq methods. This method must be
\&            called after qual_levels() but before mid() or errors().
\& Usage    : my $seq_obj = $read\->reference();
\& Arguments: Bio::SeqI or Bio::PrimarySeqI object
\& Returns  : Bio::SeqI or Bio::PrimarySeqI object
.Ve
.SS "mid"
.IX Subsection "mid"
.Vb 7
\& Title    : mid
\& Function : Get or set a multiplex identifier (or MID, or tag, or barcode) to
\&            add to the read. By default, no MID is used. This method must be
\&            called after reference() but before errors().
\& Usage    : my $mid = read\->mid();
\& Arguments: MID sequence string (e.g. \*(AqACGT\*(Aq)
\& Returns  : MID sequence string
.Ve
.SS "errors"
.IX Subsection "errors"
.Vb 10
\& Title    : errors
\& Function : Get or set the sequencing errors and update the read. By default, no
\&            errors are made. This method must be called after the mid() method.
\& Usage    : my $errors = $read\->errors();
\& Arguments: Reference to a hash of the position and nature of sequencing errors.
\&            The positions are 1\-based relative to the error\-free MID\-containing
\&            read (not relative to the reference sequence). For example:
\&               $errors\->{34}\->{\*(Aq%\*(Aq} = \*(AqT\*(Aq  ; # substitution of residue 34 by a T
\&               $errors\->{23}\->{\*(Aq+\*(Aq} = \*(AqGG\*(Aq ; # insertion of GG after residue 23
\&               $errors\->{45}\->{\*(Aq\-\*(Aq} = undef; # deletion of residue 45
\&            Substitutions and deletions are for a single residue, but additions
\&            can be additions of several residues.
\&            An alternative way to specify errors is by using array references
\&            instead of scalar for the hash values. This allows one to specify
\&            redundant mutations. For example, the case presented above would
\&            result in the same read sequence as the example below:
\&               $errors\->{34}\->{\*(Aq%\*(Aq} = [\*(AqC\*(Aq, \*(AqT\*(Aq]    ; # substitution by a C and then a T
\&               $errors\->{23}\->{\*(Aq+\*(Aq} = [\*(AqG\*(Aq, \*(AqG\*(Aq]    ; # insertion of G and then a G
\&               $errors\->{45}\->{\*(Aq\-\*(Aq} = [undef, undef]; # deletion of residue, and again
\& Returns  : Reference to a hash of the position and nature of sequencing errors.
.Ve
.SS "track"
.IX Subsection "track"
.Vb 6
\& Title    : track
\& Function : Get or set the tracking status in the read description. By default,
\&            tracking is on. This method can be called at any time.
\& Usage    : my $track = $read\->track();
\& Arguments: 1 for tracking, 0 otherwise
\& Returns  : 1 for tracking, 0 otherwise
.Ve
.SS "coord_style"
.IX Subsection "coord_style"
.Vb 10
\& Title    : coord_style
\& Function : When tracking is on, define which 1\-based coordinate system to use
\&            in the read description:
\&              * \*(Aqbioperl\*(Aq uses the start, end and strand keywords (default),
\&                similarly to the GFF3 format. Example:
\&                  start=1 end=10 strand=+1
\&                  start=1 end=10 strand=\-1
\&              * \*(Aqgenbank\*(Aq does only provide the position keyword. Example:
\&                  position=1..10
\&                  position=complement(1..10)
\& Usage    : my $coord_style = $read\->track();
\& Arguments: \*(Aqbioperl\*(Aq or \*(Aqgenbank\*(Aq
\& Returns  : \*(Aqbioperl\*(Aq or \*(Aqgenbank\*(Aq
.Ve