.\" Automatically generated by Pod::Man 4.09 (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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" 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::Assembly::IO::ace 3pm"
.TH Bio::Assembly::IO::ace 3pm "2018-10-27" "perl v5.26.2" "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::Assembly::IO::ace \- module to load ACE files from various assembly programs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # Building an input stream
\&    use Bio::Assembly::IO;
\&
\&    # Load a reference ACE assembly
\&    my $in_io = Bio::Assembly::IO\->new( \-file   => \*(Aqresults.ace\*(Aq,
\&                                        \-format => \*(Aqace\*(Aq          );
\&
\&    # Read the entire scaffold
\&    my $scaffold = $in_io\->next_assembly;
\&
\&    # Or read one contig at a time to save resources
\&    while ( my $contig = $in_io\->next_contig ) {
\&      # Do something ...
\&    }
\&
\&    # Assembly writing methods
\&    my $out_io = Bio::Assembly::IO\->new( \-file   => ">output.ace",
\&                                         \-format => \*(Aqace\*(Aq );
\&    $out_io\->write_assembly( \-scaffold => $scaffold,
\&                             \-singlets => 1 );
\&
\&    # Read the \*(Aq454\*(Aq Newbler variant of ACE instead of the default \*(Aqconsed\*(Aq
\&    # reference ACE variant
\&    my $in_io = Bio::Assembly::IO\->new( \-file   => \*(Aqresults.ace\*(Aq,
\&                                        \-format => \*(Aqace\-454\*(Aq      );
\&    # or ...
\&    my $in_io = Bio::Assembly::IO\->new( \-file    => \*(Aqresults.ace\*(Aq,
\&                                        \-format  => \*(Aqace\*(Aq,
\&                                        \-variant => \*(Aq454\*(Aq      );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package loads the standard \s-1ACE\s0 files generated by various assembly programs
(Phrap, \s-1CAP3,\s0 Newbler, Arachne, ...). It was written to be used as a driver
module for Bio::Assembly::IO input/output.
.SS "Implemention"
.IX Subsection "Implemention"
Assemblies are loaded into Bio::Assembly::Scaffold objects composed by
Bio::Assembly::Contig and Bio::Assembly::Singlet objects. Only the \s-1ACE\s0 file is
used, so if you need singlets, make sure that they are present in the \s-1ACE\s0 file.
.PP
A brief description of the \s-1ACE\s0 format is available at
http://www.cbcb.umd.edu/research/contig_representation.shtml#ACE
Read the full format description from
http://bozeman.mbt.washington.edu/consed/distributions/README.14.0.txt
.PP
In addition to default \*(L"_aligned_coord:$seqID\*(R" feature class from
Bio::Assembly::Contig, contig objects loaded by this module will have the
following special feature classes in their feature collection:
.PP
\&\*(L"_align_clipping:$seqID\*(R" (\s-1AF\s0)
    Location of subsequence in read \f(CW$seqID\fR which is aligned to the contig. The
    coordinates are relative to the contig. If no feature containing this tag is
    present the read is considered low quality by Consed.
.PP
\&\*(L"_quality_clipping:$seqID\*(R" (\s-1AF\s0)
    The location of high quality subsequence in read \f(CW$seqID\fR (relative to contig)
.PP
\&\*(L"_base_segments\*(R" (\s-1BS\s0)
    Location of read subsequences used to build the consensus
.PP
\&\*(L"_read_tags:$readID\*(R" (\s-1RT\s0)
    Sequence features stored as sub_SeqFeatures of the sequence's coordinate
    feature (the corresponding \*(L"_aligned_coord:$seqID\*(R" feature, easily accessed
    through \fIget_seq_coord()\fR method).
.PP
\&\*(L"_read_desc:$readID\*(R" (\s-1DS\s0)
    Sequence features stored as sub_SeqFeatures of the read's coordinate feature
.PP
\&\*(L"consensus tags\*(R" (\s-1CT\s0)
    Equivalent to a bioperl sequence feature and, therefore, are added to the
    feature collection using their type field (see Consed's \s-1README\s0.txt file) as
    primary tag.
.PP
\&\*(L"whole assembly tags\*(R" (\s-1WA\s0)
    They have no start and end, as they are not associated to any particular
    sequence in the assembly, and are added to the assembly's annotation
    collection using \*(L"whole assembly\*(R" as tag.
.SS "Variants"
.IX Subsection "Variants"
The default \s-1ACE\s0 variant is called 'consed' and corresponds to the reference \s-1ACE\s0
format.
.PP
The \s-1ACE\s0 files produced by the 454 \s-1GS\s0 Assembler (Newbler) do not conform to the
reference \s-1ACE\s0 format. In 454 \s-1ACE,\s0 the consensus sequence reported covers only
its clear range and the start of the clear range consensus is defined as position
1. Consequently, aligned reads in the contig can have negative positions. Be sure 
to use the '454' variant to have positive alignment positions. No attempt is made
to construct the missing part of the consensus sequence (beyond the clear range)
based on the underlying reads in the contig. Instead the ends of the consensus
are simply padded with the gap character '\-'.
.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 lists  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 "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
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 \- Robson Francisco de Souza"
.IX Header "AUTHOR - Robson Francisco de Souza"
Email rfsouza@citri.iq.usp.br
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
.SH "Parser methods"
.IX Header "Parser methods"
.SS "next_assembly"
.IX Subsection "next_assembly"
.Vb 5
\& Title   : next_assembly
\& Usage   : $scaffold = $stream\->next_assembly()
\& Function: returns the next assembly in the stream
\& Returns : a Bio::Assembly::Scaffold object
\& Args    : none
.Ve
.SS "next_contig"
.IX Subsection "next_contig"
.Vb 5
\& Title   : next_contig
\& Usage   : $scaffold = $stream\->next_contig()
\& Function: Returns the next contig or singlet in the ACE stream.
\& Returns : a Bio::Assembly::Contig or Bio::Assembly::Single object
\& Args    : none
.Ve
.SS "scaffold_annotations"
.IX Subsection "scaffold_annotations"
.Vb 6
\& Title   : scaffold_annotations
\& Usage   : $stream\->scaffold_annotations($scaffold)
\& Function: Add assembly and contig annotations to a scaffold. In the ACE format,
\&           annotations are the WA and CT tags.
\& Returns : 1 for success
\& Args    : a Bio::Assembly::Scaffold object to attach the annotations to
.Ve
.SS "write_assembly"
.IX Subsection "write_assembly"
.Vb 9
\&    Title   : write_assembly
\&    Usage   : $ass_io\->write_assembly($assembly)
\&    Function: Write the assembly object in ACE compatible format. The contig IDs
\&              are sorted naturally if the Sort::Naturally module is present, or
\&              lexically otherwise. Internally, write_assembly use the
\&              write_contig, write_footer and write_header methods. Use these
\&              methods if you want more control on the writing process.
\&    Returns : 1 on success, 0 for error
\&    Args    : A Bio::Assembly::Scaffold object
.Ve
.SS "write_contig"
.IX Subsection "write_contig"
.Vb 7
\&    Title   : write_contig
\&    Usage   : $ass_io\->write_contig($contig)
\&    Function: Write a contig or singlet object in ACE compatible format. Quality
\&              scores are automatically generated if the contig does not contain
\&              any
\&    Returns : 1 on success, 0 for error
\&    Args    : A Bio::Assembly::Contig or Singlet object
.Ve
.SS "write_header"
.IX Subsection "write_header"
.Vb 10
\&    Title   : write_header
\&    Usage   : $ass_io\->write_header($scaffold)
\&                  or
\&              $ass_io\->write_header(\e@contigs);
\&                  or
\&              $ass_io\->write_header();
\&    Function: Write ACE header (AS tags). You can call this function at any time,
\&              i.e. not necessarily at the start of the stream \- this is useful
\&              if you have an undetermined number of contigs to write to ACE, e.g:
\&                for my $contig (@list_of_contigs) {
\&                  $ass_io\->_write_contig($contig);
\&                }
\&                $ass_io\->_write_header();
\&    Returns : 1 on success, 0 for error
\&    Args    : A Bio::Assembly::Scaffold
\&                  or
\&              an arrayref of Bio::Assembly::Contig
\&                  or
\&              nothing (the header is dynamically written based on the ACE file
\&              content)
.Ve
.SS "write_footer"
.IX Subsection "write_footer"
.Vb 5
\&    Title   : write_footer
\&    Usage   : $ass_io\->write_footer($scaffold)
\&    Function: Write ACE footer (WA and CT tags).
\&    Returns : 1 on success, 0 for error
\&    Args    : A Bio::Assembly::Scaffold object (optional)
.Ve
.SS "variant"
.IX Subsection "variant"
.Vb 6
\& Title   : variant
\& Usage   : $variant = $ass_io\->variant();
\& Function: Get and set method for the assembly variant. This is important since
\&           not all assemblers respect the reference ACE format.
\& Returns : string
\& Args    : string: \*(Aqconsed\*(Aq (default) or \*(Aq454\*(Aq
.Ve
.SS "_write_read"
.IX Subsection "_write_read"
.Vb 6
\&    Title   : _write_read
\&    Usage   : $ass_io\->_write_read($read, $contig)
\&    Function: Write a read object in ACE compatible format
\&    Returns : 1 on success, 0 for error
\&    Args    : a Bio::LocatableSeq read
\&              the Contig or Singlet object that this read belongs to
.Ve
.SS "_formatted_seq"
.IX Subsection "_formatted_seq"
.Vb 8
\&    Title   : _formatted_seq
\&    Usage   : Bio::Assembly::IO::ace::_formatted_seq($sequence, $line_width)
\&    Function: Format a sequence for ACE output:
\&              i ) replace gaps in the sequence by the \*(Aq*\*(Aq char
\&              ii) split the sequence on multiple lines as needed
\&    Returns : new sequence string
\&    Args    : sequence string on one line
\&              maximum line width
.Ve
.SS "_formatted_qual"
.IX Subsection "_formatted_qual"
.Vb 11
\&    Title   : _formatted_qual
\&    Usage   : Bio::Assembly::IO::ace::_formatted_qual($qual_arr, $sequence, $line_width, $qual_default)
\&    Function: Format quality scores for ACE output:
\&              i  ) use the default quality values when they are missing
\&              ii ) remove gaps (they get no score in ACE)
\&              iii) split the quality scores on several lines as needed
\&    Returns : new quality score string
\&    Args    : quality score array reference
\&              corresponding sequence string
\&              maximum line width
\&              default quality score
.Ve
.SS "_input_qual"
.IX Subsection "_input_qual"
.Vb 8
\&    Title   : _input_qual
\&    Usage   : Bio::Assembly::IO::ace::_input_qual($qual_string, $sequence)
\&    Function: Reads input quality string and converts it to an array of quality
\&              scores. Gaps get a quality score equals to the average of the
\&              quality score of its neighbours.
\&    Returns : new quality score array
\&    Args    : quality score string
\&              corresponding sequence string
.Ve
.SS "_initialize"
.IX Subsection "_initialize"
.Vb 5
\&    Title   : _initialize
\&    Usage   : $ass_io\->_initialize(@args)
\&    Function: Initialize the Bio::Assembly::IO object with the proper ACE variant
\&    Returns : 
\&    Args    :
.Ve