Provided by: libbio-perl-perl_1.7.2-2_all bug

NAME

       Bio::Assembly::IO::ace - module to load ACE files from various assembly programs

SYNOPSIS

           # Building an input stream
           use Bio::Assembly::IO;

           # Load a reference ACE assembly
           my $in_io = Bio::Assembly::IO->new( -file   => 'results.ace',
                                               -format => 'ace'          );

           # 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 => 'ace' );
           $out_io->write_assembly( -scaffold => $scaffold,
                                    -singlets => 1 );

           # Read the '454' Newbler variant of ACE instead of the default 'consed'
           # reference ACE variant
           my $in_io = Bio::Assembly::IO->new( -file   => 'results.ace',
                                               -format => 'ace-454'      );
           # or ...
           my $in_io = Bio::Assembly::IO->new( -file    => 'results.ace',
                                               -format  => 'ace',
                                               -variant => '454'      );

DESCRIPTION

       This package loads the standard ACE files generated by various assembly programs (Phrap,
       CAP3, Newbler, Arachne, ...). It was written to be used as a driver module for
       Bio::Assembly::IO input/output.

   Implemention
       Assemblies are loaded into Bio::Assembly::Scaffold objects composed by
       Bio::Assembly::Contig and Bio::Assembly::Singlet objects. Only the ACE file is used, so if
       you need singlets, make sure that they are present in the ACE file.

       A brief description of the ACE 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

       In addition to default "_aligned_coord:$seqID" feature class from Bio::Assembly::Contig,
       contig objects loaded by this module will have the following special feature classes in
       their feature collection:

       "_align_clipping:$seqID" (AF)
           Location of subsequence in read $seqID 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.

       "_quality_clipping:$seqID" (AF)
           The location of high quality subsequence in read $seqID (relative to contig)

       "_base_segments" (BS)
           Location of read subsequences used to build the consensus

       "_read_tags:$readID" (RT)
           Sequence features stored as sub_SeqFeatures of the sequence's coordinate
           feature (the corresponding "_aligned_coord:$seqID" feature, easily accessed
           through get_seq_coord() method).

       "_read_desc:$readID" (DS)
           Sequence features stored as sub_SeqFeatures of the read's coordinate feature

       "consensus tags" (CT)
           Equivalent to a bioperl sequence feature and, therefore, are added to the
           feature collection using their type field (see Consed's README.txt file) as
           primary tag.

       "whole assembly tags" (WA)
           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 "whole assembly" as tag.

   Variants
       The default ACE variant is called 'consed' and corresponds to the reference ACE format.

       The ACE files produced by the 454 GS Assembler (Newbler) do not conform to the reference
       ACE format. In 454 ACE, 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 '-'.

FEEDBACK

   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.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       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.

   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:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Robson Francisco de Souza

       Email rfsouza@citri.iq.usp.br

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

Parser methods

   next_assembly
        Title   : next_assembly
        Usage   : $scaffold = $stream->next_assembly()
        Function: returns the next assembly in the stream
        Returns : a Bio::Assembly::Scaffold object
        Args    : none

   next_contig
        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

   scaffold_annotations
        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

   write_assembly
           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

   write_contig
           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

   write_header
           Title   : write_header
           Usage   : $ass_io->write_header($scaffold)
                         or
                     $ass_io->write_header(\@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)

   write_footer
           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)

   variant
        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: 'consed' (default) or '454'

   _write_read
           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

   _formatted_seq
           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 '*' char
                     ii) split the sequence on multiple lines as needed
           Returns : new sequence string
           Args    : sequence string on one line
                     maximum line width

   _formatted_qual
           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

   _input_qual
           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

   _initialize
           Title   : _initialize
           Usage   : $ass_io->_initialize(@args)
           Function: Initialize the Bio::Assembly::IO object with the proper ACE variant
           Returns :
           Args    :