NAME

       Bio::Assembly::IO::maq - Driver to read assembly files in maq format *BETA*

SYNOPSIS

           # convert the native maq map format to plain text
           $ maq mapview all.map > all.maq

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

           # Assembly loading methods
           my $asmio = Bio::Assembly::IO->new( -file   => 'all.maq',
                                               -format => 'maq' );
           my $scaffold = $asmio->next_assembly;

DESCRIPTION

       This package loads and writes map information in/from "maq" map files converted by the
       "maq mapview" utility. This module is a driver module for Bio::Assembly::IO input/output.

       Parsing is based on Heng Li's description of "maq mapview" output, found at the "maq"
       manpage: <http://maq.sourceforge.net/maq-manpage.shtml>.

       The basic "maq" workflow is: map reads to a reference sequence (with "maq map"), then
       create a consensus from the map (with "maq assemble"). To read a complete assembly with
       this module, the following files need to be available:

        [basename].maq : created by maq mapview [basename].map > [basename].maq
        [basename].cns.fastq : created as follows
           $ maq assemble [basename].cns [refseq].bfa [basename].map
           $ maq cns2fq [basename].cns > [basename].cns.fastq

       "maq" produces only one "contig"; all reads map to the reference sequence, which covers
       everything. This module breaks the reads into contigs by dividing the "maq" consensus into
       pieces for which there are contiguous non-zero quality values.

       The module "Bio::Tools::Run::Maq" will help in this process (eventually).

       This module has no write capability.

   Implementation
       Assemblies are loaded into Bio::Assembly::Scaffold objects composed of
       Bio::Assembly::Contig and Bio::Assembly::Singlet objects. Contigs are not explicitly
       specified in "map" files; the division of the map into contigs is calculated in this
       module.

       Additional assembly information is stored as features. Contig objects have SeqFeature
       information associated with the primary_tag:

           _main_contig_feature:$contig_id -> misc contig information

       Read objects have sub_seqFeature information associated with the primary_tag:

           _main_read_feature:$read_id     -> misc read information

       Singlets are contigs of a single sequence, as calculated within this module.  They are
       cataloged separately, as specified in Bio::Assembly::Scaffold.

TODO

       •   Add pod descriptions of maq descriptive data (currently SeqFeatures added to each
           contig component)

       •   Add features describing the aggregate status of reads and contigs based on the maq
           "paired flag"

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 email or the web:

         bioperl-bugs@bio.perl.org
         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Mark A. Jensen

       Email maj -at- fortinbras -dot- us

CONTRIBUTORS

       Further improvements by Florent Angly (florent dot angly at gmail dot com)

ACKNOWLEDGEMENT

       Code and some POD text ripped liberally from Florent Angly's Bio::Assembly::IO::tigr.

APPENDIX

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

   next_assembly
        Title   : next_assembly
        Usage   : $scaffold = $stream->next_assembly()
        Function: return the assembly defined by the map and cns files
        Returns : 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

   _init_contig()
           Title   : _init_contig
           Usage   : my $contigobj; $contigobj = $self->_init_contig(
                     \%contiginfo, $scaffoldobj);
           Function: store information of a contig belonging to a scaffold in the
                     appropriate object
           Returns : Bio::Assembly::Contig object
           Args    : hash, Bio::Assembly::Scaffold

   _store_contig()
           Title   : _store_contig
           Usage   : my $contigobj; $contigobj = $self->_store_contig(
                     \%contiginfo, $contigobj);
           Function: store information of a contig belonging to a scaffold
                     in the appropriate object
           Returns : Bio::Assembly::Contig object
           Args    : hash, Bio::Assembly::Contig

   _parse_cns_file()
        Title   : _parse_cns_file
        Usage   : $self->_parse_cns_file
        Function: parse the .cns.fastq (consensus) file
                  associated with the present map;
                  set the objects cns attribute
        Returns : true on success; nil if file dne
        Args    : none

   _cons()
        Title   : _cons
        Usage   : @cons = $self->_cons
        Function: get the array of consensus fastq Bio::Seq::Quality objects
        Returns : array of Bio::Seq::Quality objects
        Args    : none

   _next_cons()
   _store_read()
           Title   : _store_read
           Usage   : my $readobj = $self->_store_read(\%readinfo, $contigobj);
           Function: store information of a read belonging to a contig
                     in the appropriate object
           Returns : a Bio::LocatableSeq object
           Args    : hash, Bio::Assembly::Contig

   _store_singlet()
           Title   : _store_singlet
           Usage   : my $singletobj = $self->_store_read(\%readinfo, \%contiginfo);
           Function: store information of a singlet belonging to a scaffold in a singlet object
           Returns : Bio::Assembly::Singlet
           Args    : hash, hash

   write_assembly()
           Title   : write_assembly
           Usage   :
           Function: not currently available for maq assemblies
           Returns : throw
           Args    :

   _basename()
        Title   : _basename
        Usage   : $self->_basename
        Function: return the basename of the associate IO file
        Returns : scalar string
        Args    : none