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

NAME

       Bio::Assembly::Tools::ContigSpectrum - create and manipulate contig spectra

SYNOPSIS

         # Simple contig spectrum creation
         my $csp1 = Bio::Assembly::Tools::ContigSpectrum->new(
           -id       => 'csp1',
           -spectrum => { 1 => 10,
                          2 => 2,
                          3 => 1 } );

         # ...or another way to create a simple contig spectrum
         my $csp2 = Bio::Assembly::Tools::ContigSpectrum->new;
         $csp2->id('csp2');
         $csp2->spectrum({ 1 => 20, 2 => 1, 4 => 1 });

         # Get some information
         print "This is contig spectrum ".$csp->id."\n";
         print "It contains ".$csp->nof_seq." sequences\n";
         print "The largest contig has ".$csp->max_size." sequences\n";
         print "The spectrum is: ".$csp->to_string($csp->spectrum)."\n";

         # Let's add the contig spectra
         my $summed_csp = Bio::Assembly::Tools::ContigSpectrum->new;
         $summed_csp->add($csp1);
         $summed_csp->add($csp2);
         print "The summed contig spectrum is ".$summed_csp->to_string."\n";

         # Make an average
         my $avg_csp = Bio::Assembly::Tools::ContigSpectrum->new;
         $avg_csp = $avg_csp->average([$csp1, $csp2]);
         print "The average contig spectrum is ".$avg_csp->to_string."\n";

         # Get a contig spectrum from an assembly
         my $from_assembly = Bio::Assembly::Tools::ContigSpectrum->new(
           -assembly       => $assembly_object,
           -eff_asm_params => 1);
         print "The contig spectrum from assembly is ".$from_assembly->to_string."\n";

         # Report advanced information (possible because eff_asm_params = 1)
         print "Average sequence length: ".$from_assembly->avg_seq_len." bp\n";
         print "Minimum overlap length: ".$from_assembly->min_overlap." bp\n";
         print "Average overlap length: ".$from_assembly->avg_overlap." bp\n";
         print "Minimum overlap match: ".$from_assembly->min_identity." %\n";
         print "Average overlap match: ".$from_assembly->avg_identity." %\n";

         # Assuming the assembly object contains sequences from several different
         # metagenomes, we have a mixed contig spectrum from which a cross contig
         # spectrum and dissolved contig spectra can be obtained
         my $mixed_csp = $from_assembly;

         # Calculate a dissolved contig spectrum
         my $meta1_dissolved = Bio::Assembly::Tools::ContigSpectrum->new(
           -dissolve => [$mixed_csp, 'metagenome1'] );
         my $meta2_dissolved = Bio::Assembly::Tools::ContigSpectrum->new(
           -dissolve => [$mixed_csp, 'metagenome2'] );
         print "The dissolved contig spectra are:\n".
           $meta1_dissolved->to_string."\n".
           $meta2_dissolved->to_string."\n";

         # Determine a cross contig spectrum
         my $cross_csp = Bio::Assembly::Tools::ContigSpectrum->new(
           -cross => $mixed_csp );
         print "The cross contig spectrum is ".$cross_csp->to_string."\n";

         # Score a contig spectrum (the more abundant the contigs and the larger their
         # size, the larger the score)
         my $csp_score = $csp->score( $csp->nof_seq );

DESCRIPTION

       The Bio::Assembly::Tools::ContigSpectrum Perl module enables to manually create contig
       spectra, import them from assemblies, manipulate them, transform between different types
       of contig spectra and output them.

       Bio::Assembly::Tools::ContigSpectrum is a module to create, manipulate and output contig
       spectra, assembly-derived data used in metagenomics (community genomics) for diversity
       estimation.

   Background
       A contig spectrum is the count of the number of contigs of different size in an assembly.
       For example, the contig spectrum [100 5 1 0 0 ...] means that there were 100 singlets
       (1-contigs), 5 contigs of 2 sequences (2-contigs), 1 contig of 3 sequences (3-contig) and
       no larger contigs.

       An assembly can be produced from a mixture of sequences from different metagenomes. The
       contig obtained from this assembly is a mixed contig spectrum. The contribution of each
       metagenome in this mixed contig spectrum can be obtained by determining a dissolved contig
       spectrum.

       Finally, based on a mixed contig spectrum, a cross contig spectrum can be determined. In a
       cross contig spectrum, only contigs containing sequences from different metagenomes are
       kept; "pure" contigs are excluded. Additionally, the total number of singletons
       (1-contigs) from each region that assembles with any fragments from other regions is the
       number of 1-contigs in the cross contig spectrum.

   Implementation
       The simplest representation of a contig spectrum is as a hash representation where the key
       is the contig size (number of sequences making up the contig) and the value the number of
       contigs of this size.

       In fact, it is useful to have more information associated with the contig spectrum, hence
       the Bio::Assembly::Tools::ContigSpectrum module implements an object containing a contig
       spectrum hash and additional information. The get/set methods to access them are:

           id              contig spectrum ID
           nof_rep         number of repetitions (assemblies) used
           max_size        size of (number of sequences in) the largest contig
           spectrum        hash representation of a contig spectrum

           nof_seq         number of sequences
           avg_seq_len     average sequence length

           eff_asm_params  reports effective assembly parameters

           nof_overlaps    number of overlaps (needs eff_asm_params)
           min_overlap     minimum overlap length in a contig (needs eff_asm_params)
           min_identity    minimum sequence identity percentage (needs eff_asm_params)
           avg_overlap     average overlap length (needs eff_asm_params)
           avg_identity    average overlap identity percentage (needs eff_asm_params)

         Operations on the contig spectra:

           to_string       create a string representation of the spectrum
           spectrum        import a hash contig spectrum
           assembly        determine a contig spectrum from an assembly, contig or singlet
           dissolve        calculate a dissolved contig spectrum (depends on assembly)
           cross           produce a cross contig spectrum (depends on assembly)
           add             add a contig spectrum to an existing one
           average         make an average of several contig spectra
           score           score a contig spectrum: the higher the number of contigs
                             and the larger their size, the higher the score.

       When using operations that rely on knowing "where" (from what metagenomes) a sequence came
       from (i.e. when creating a dissolved or cross contig spectrum), make sure that the
       sequences used for the assembly have a name header, e.g.  >metagenome1|seq1,
       >metagenome2|seq1, ...

       Note: The following operations require the "Graph::Undirected" module:
          eff_asm_params, cross, dissolve

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 - Florent E Angly

       Email florent_dot_angly_at_gmail_dot_com

APPENDIX

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

   new
         Title   : new
         Usage   : my $csp = Bio::Assembly::Tools::ContigSpectrum->new();
                     or
                   my $csp = Bio::Assembly::Tools::ContigSpectrum->new(
                     -id => 'some_name',
                     -spectrum =>  { 1 => 90 , 2 => 3 , 4 => 1 },
                   );
                     or
                   my $csp = Bio::Assembly::Tools::ContigSpectrum->new(
                     -assembly =>  $assembly_obj
                   );
         Function: create a new contig spectrum object
         Returns : reference to a contig spectrum object
         Args    : none

   id
         Title   : id
         Usage   : $csp->id
         Function: get/set contig spectrum id
         Returns : string
         Args    : string [optional]

   nof_seq
         Title   : nof_seq
         Usage   : $csp->nof_seq
         Function: get/set the number of sequences making up the contig spectrum
         Returns : integer
         Args    : integer [optional]

   nof_rep
         Title   : nof_rep
         Usage   : $csp->nof_rep
         Function: Get/Set the number of repetitions (assemblies) used to create the
                   contig spectrum
         Returns : integer
         Args    : integer [optional]

   max_size
         Title   : max_size
         Usage   : $csp->max_size
         Function: get/set the size of (number of sequences in) the largest contig
         Returns : integer
         Args    : integer [optional]

   nof_overlaps
         Title   : nof_overlaps
         Usage   : $csp->nof_overlaps
         Function: Get/Set the number of overlaps in the assembly.
         Returns : integer
         Args    : integer [optional]

   min_overlap
         Title   : min_overlap
         Usage   : $csp->min_overlap
         Function: get/set the assembly minimum overlap length
         Returns : integer
         Args    : integer [optional]

   avg_overlap
         Title   : avg_overlap
         Usage   : $csp->avg_overlap
         Function: get/set the assembly average overlap length
         Returns : decimal
         Args    : decimal [optional]

   min_identity
         Title   : min_identity
         Usage   : $csp->min_identity
         Function: get/set the assembly minimum overlap identity percent
         Returns : 0 < decimal < 100
         Args    : 0 < decimal < 100 [optional]

   avg_identity
         Title   : avg_identity
         Usage   : $csp->avg_identity
         Function: get/set the assembly average overlap identity percent
         Returns : 0 < decimal < 100
         Args    : 0 < decimal < 100 [optional]

   avg_seq_len
         Title   : avg_seq_len
         Usage   : $csp->avg_seq_len
         Function: get/set the assembly average sequence length
         Returns : avg_seq_len
         Args    : real [optional]

   eff_asm_params
         Title   : eff_asm_params
         Usage   : $csp->eff_asm_params(1)
         Function: Get/set the effective assembly parameters option. It defines if the
                   effective assembly parameters should be determined when a contig
                   spectrum based or derived from an assembly is calculated. The
                   effective assembly parameters include avg_seq_length, nof_overlaps,
                   min_overlap, avg_overlap, min_identity and avg_identity.
                   1 = get them, 0 = don't.
         Returns : integer
         Args    : integer [optional]

   spectrum
         Title   : spectrum
         Usage   : my $spectrum = $csp->spectrum({1=>10, 2=>2, 3=>1});
         Function: Get the current contig spectrum represented as a hash / Update a
                   contig spectrum object based on a contig spectrum represented as a
                   hash
                   The hash representation of a contig spectrum is as following:
                     key   -> contig size (in number of sequences)
                     value -> number of contigs of this size
         Returns : contig spectrum as a hash reference
         Args    : contig spectrum as a hash reference [optional]

   assembly
         Title   : assembly
         Usage   : my @obj_list = $csp->assembly();
         Function: get/set the contig spectrum object by adding an assembly, contig or
                   singlet object to it, or get the list of objects associated with it
         Returns : arrayref of assembly, contig and singlet objects used in the contig
                   spectrum object (Bio::Assembly::Scaffold, Bio::Assembly::Contig and
                   Bio::Assembly::Singlet objects)
         Args    : Bio::Assembly::Scaffold, Contig or Singlet object

   drop_assembly
         Title   : drop_assembly
         Usage   : $csp->drop_assembly();
         Function: Remove all assembly objects associated with a contig spectrum.
                   Assembly objects can take a lot of memory, which can be freed by
                   calling this method. Don't call this method if you need the assembly
                   object later on, for example for creating a dissolved or cross
                   contig spectrum.
         Returns : 1 for success
         Args    : none

   dissolve
         Title   : dissolve
         Usage   : $dissolved_csp->dissolve($mixed_csp, $seq_header);
         Function: Dissolve a mixed contig spectrum for the set of sequences that
                   contain the specified header, i.e. determine the contribution of
                   these sequences to the mixed contig spectrum. The mixed contig
                   spectrum object must have one or several assembly object(s). In
                   addition, min_overlap, min_identity and eff_asm_params are taken
                   from the mixed contig spectrum, unless they are specified manually
                   for the dissolved contig spectrum. The dissolved contigs underlying
                   the contig spectrum can be obtained by calling the assembly() method.
         Returns : 1 for success
         Args    : Bio::Assembly::Tools::ContigSpectrum reference
                   sequence header string

   cross
         Title   : cross
         Usage   : $cross_csp->cross($mixed_csp);
         Function: Calculate a cross contig_spectrum based on a mixed contig_spectrum.
                   The underlying cross-contigs themselves can be obtained by calling
                   the assembly() method.
         Returns : 1 for success
         Args    : Bio::Assembly::Tools::ContigSpectrum reference

   to_string
         Title   : to_string
         Usage   : my $csp_string = $csp->to_string;
         Function: Convert the contig spectrum into a string (easy to print!!).
         Returns : string
         Args    : element separator (integer) [optional]
                     1 -> space-separated
                     2 -> tab-separated
                     3 -> newline-separated

   add
         Title   : add
         Usage   : $csp->add($additional_csp);
         Function: Add a contig spectrum to an existing one: sums the spectra, update
                   the number of sequences, number of repetitions, ...
         Returns : 1 for success
         Args    : Bio::Assembly::Tools::ContigSpectrum object

   average
         Title   : average
         Usage   : my $avg_csp = $csp->average([$csp1, $csp2, $csp3]);
         Function: Average one contig spectrum or the sum of several contig spectra by
                   the number of repetitions
         Returns : Bio::Assembly::Tools::ContigSpectrum
         Args    : Bio::Assembly::Tools::ContigSpectrum array reference
                   eff_asm_params

   score
         Title   : score
         Usage   : my $score = $csp->score();
         Function: Score a contig spectrum (or cross-contig spectrum) such that the
                    higher the number of contigs (or cross-contigs) and the larger their
                    size, the higher the score.
                    Let n   : total number of sequences
                        c_q : number of contigs of size q
                        q   : number of sequence in a contig
                    We define: score = n/(n-1) * (X - 1/n)
                         where X = sum ( c_q * q^2 ) / n**2
                    The score ranges from 0 (singlets only) to 1 (a single large contig)
                    It is possible to specify a value for the number of sequences to
                     assume in the contig spectrum.
         Returns : contig score, or undef if there were no sequences in the contig spectrum
         Args    : number of total sequences to assume [optional]

   _naive_assembler
         Title   : _naive_assembler
         Usage   :
         Function: Reassemble the specified sequences only based on their position in
                   the contig. This naive assembly only verifies that the minimum
                   overlap length and percentage identity are respected. No actual
                   alignment is done
         Returns : arrayref of contigs and singlets
         Args    : Bio::Assembly::Contig
                   array reference of sequence IDs to use [optional]
                   minimum overlap length (integer)       [optional]
                   minimum percentage identity (integer)  [optional]

   _create_subcontig
         Title   : _create_subcontig
         Usage   :
         Function: Create a subcontig from another contig
         Returns : Bio::Assembly::Contig object
         Args    : Bio::Assembly::Contig
                   arrayref of the IDs of the reads to includes in the subcontig
                   ID to give to the subcontig

   _obj_copy
         Title   : _obj_copy
         Usage   :
         Function: Copy (most of) an object, and optionally truncate it
         Returns : another a Bio::LocatableSeq, Bio::Seq::PrimaryQual, or
                     Bio::SeqFeature::Generic object
         Args    : a Bio::LocatableSeq, Bio::Seq::PrimaryQual, or
                     Bio::SeqFeature::Generic object
                   a start position
                   an end position

   _new_from_assembly
         Title   : _new_from_assembly
         Usage   :
         Function: Creates a new contig spectrum object based solely on the result of
                   an assembly, contig or singlet
         Returns : Bio::Assembly::Tools::ContigSpectrum object
         Args    : Bio::Assembly::Scaffold, Contig or Singlet object

   _new_dissolved_csp
         Title   : _new_dissolved_csp
         Usage   :
         Function: create a dissolved contig spectrum object
         Returns : dissolved contig spectrum
         Args    : mixed contig spectrum
                   header of sequences to keep in this contig spectrum

   _dissolve_contig
         Title   : _dissolve_contig
         Usage   :
         Function: dissolve a contig
         Returns : arrayref of contigs and singlets
         Args    : mixed contig spectrum
                   header of sequences to keep in this contig spectrum
                   minimum overlap
                   minimum identity

   _new_cross_csp
         Title   : _new_cross_csp
         Usage   :
         Function: create a cross contig spectrum object
         Returns : cross-contig spectrum
         Args    : mixed contig spectrum

   _cross_contig
         Title   : _cross_contig
         Usage   :
         Function: calculate cross contigs
         Returns : arrayref of cross-contigs
                   number of cross-singlets
         Args    : contig
                   minimum overlap
                   minimum identity

   _seq_origin
         Title   : _seq_origin
         Usage   :
         Function: determines where a sequence comes from using its header. For example
                   the origin of the sequence 'metagenome1|gi|9626988|ref|NC_001508.1|'
                   is 'metagenome1'
         Returns : origin
         Args    : sequence ID

   _import_assembly
         Title   : _import_assembly
         Usage   : $csp->_import_assembly($assemblyobj);
         Function: Update a contig spectrum object based on an assembly, contig or
                   singlet object
         Returns : 1 for success
         Args    : Bio::Assembly::Scaffold, Contig or Singlet object

   _import_spectrum
         Title   : _import_spectrum
         Usage   : $csp->_import_spectrum({ 1 => 90 , 2 => 3 , 4 => 1 })
         Function: update a contig spectrum object based on a contig spectrum
                   represented as a hash (key: contig size, value: number of contigs of
                   this size)
         Returns : 1 for success
         Args    : contig spectrum as a hash reference

   _import_dissolved_csp
         Title   : _import_dissolved_csp
         Usage   : $csp->_import_dissolved_csp($mixed_csp, $seq_header);
         Function: Update a contig spectrum object by dissolving a mixed contig
                   spectrum based on the header of the sequences
         Returns : 1 for success
         Args    : Bio::Assembly::Tools::ContigSpectrum
                   sequence header string

   _import_cross_csp
         Title   : _import_cross_csp
         Usage   : $csp->_import_cross_csp($mixed_csp);
         Function: Update a contig spectrum object by calculating the cross contig
                   spectrum based on a mixed contig spectrum
         Returns : 1 for success
         Args    : Bio::Assembly::Tools::ContigSpectrum

   _get_contig_like
         Title   : _get_contig_like
         Usage   : my @contig_like_objs = $csp->_get_contig_like($assembly_obj);
         Function: Get contigs and singlets from an assembly, contig or singlet
         Returns : array of Bio::Assembly::Contig and Singlet objects
         Args    : a Bio::Assembly::Scaffold, Contig or singlet object

   _get_assembly_seq_stats
         Title   : _get_assembly_seq_stats
         Usage   : my $seqlength = $csp->_get_assembly_seq_stats($assemblyobj);
         Function: Get sequence statistics from an assembly:
                     average sequence length, number of sequences
         Returns : average sequence length (decimal)
                   number of sequences (integer)
         Args    : Bio::Assembly::Scaffold, Contig or singlet object
                   hash reference with the IDs of the sequences to consider [optional]

   _get_contig_seq_stats
         Title   : _get_contig_seq_stats
         Usage   : my $seqlength = $csp->_get_contig_seq_stats($contigobj);
         Function: Get sequence statistics from a contig:
                     average sequence length, number of sequences
         Returns : average sequence length (decimal)
                   number of sequences (integer)
         Args    : contig object reference
                   hash reference with the IDs of the sequences to consider [optional]

   _update_seq_stats
         Title   : _update_seq_stats
         Usage   :
         Function: Update the number of sequences and their average length 1
                   average identity 1
                   minimum length 1
                   minimum identity 1
                   number of overlaps 1 average sequence length
         Returns : average sequence length
                   number of sequences
         Args    : average sequence length 1
                   number of sequences 1
                   average sequence length 2
                   number of sequences 2

   _get_assembly_overlap_stats
         Title   : _get_assembly_overlap_stats
         Usage   : my ($avglength, $avgidentity, $minlength, $min_identity, $nof_overlaps)
                     = $csp->_get_assembly_overlap_stats($assemblyobj);
         Function: Get statistics about pairwise overlaps in contigs of an assembly
         Returns : average overlap length
                   average identity percent
                   minimum overlap length
                   minimum identity percent
                   number of overlaps
         Args    : Bio::Assembly::Scaffold, Contig or Singlet object
                   hash reference with the IDs of the sequences to consider [optional]

   _get_contig_overlap_stats
         Title   : _get_contig_overlap_stats
         Usage   : my ($avglength, $avgidentity, $minlength, $min_identity, $nof_overlaps)
                     = $csp->_get_contig_overlap_stats($contigobj);
         Function: Get statistics about pairwise overlaps in a contig or singlet. The
                     statistics are obtained using graph theory: each read is a node
                     and the edges between 2 reads are weighted by minus the number of
                     conserved residues in the alignment between the 2 reads. The
                     minimum spanning tree of this graph represents the overlaps that
                     form the contig. Overlaps that do not satisfy the minimum overlap
                     length and similarity get a malus on their score.
                     Note: This function requires the optional BioPerl dependency
                     module called 'Graph'
         Returns : average overlap length
                   average identity percent
                   minimum overlap length
                   minimum identity percent
                   number of overlaps
         Args    : Bio::Assembly::Contig or Singlet object
                   hash reference with the IDs of the sequences to consider [optional]

   _update_overlap_stats
         Title   : _update_overlap_stats
         Usage   :
         Function: update the number of overlaps and their minimum and average length
                   and identity
         Returns :
         Args    : average length 1
                   average identity 1
                   minimum length 1
                   minimum identity 1
                   number of overlaps 1
                   average length 2
                   average identity 2
                   minimum length 2
                   minimum identity 2
                   number of overlaps 2

   _overlap_alignment
         Title   : _overlap_alignment
         Usage   :
         Function: Produce an alignment of the overlapping section of two sequences of
                   a contig. Minimum overlap length and percentage identity can be
                   specified. Return undef if the sequences do not overlap or do not
                   meet the minimum overlap criteria.
         Return  : Bio::SimpleAlign object reference
                   alignment overlap length
                   alignment overlap identity
         Args    : Bio::Assembly::Contig object reference
                   Bio::LocatableSeq contig sequence 1
                   Bio::LocatableSeq contig sequence 2
                   minimum overlap length [optional]
                   minimum overlap identity percentage[optional]

   _contig_graph
         Title   : _contig_graph
         Usage   :
         Function: Creates a graph data structure of the contig.The graph is undirected.
                   The vertices are the reads of the contig and edges are the overlap
                   between the reads. The edges are weighted by the opposite of the
                   overlap, so it is negative and the better the overlap, the lower the
                   weight.
         Return  : Graph object or undef
                   hashref of overlaps (score, length, identity) for each read pair
         Args    : Bio::Assembly::Contig object reference
                   hash reference with the IDs of the sequences to consider [optional]
                   minimum overlap length (integer)                         [optional]
                   minimum percentage identity (integer)                    [optional]

   _draw_graph
         Title   : _draw_graph
         Usage   :
         Function: Generates a PNG picture of the contig graph. It is mostly for
                   debugging purposes.
         Return  : 1 for success
         Args    : a Graph object
                   hashref of overlaps (score, length, identity) for each read pair
                   name of output file
                   overlap info to display: 'score' (default), 'length' or 'identity'