Bio::Assembly::Tools::ContigSpectrum.3pm

Langue: en

Version: 2010-05-19 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

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_length." 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)
 
 

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_seq         number of sequences
     nof_rep         number of repetitions (assemblies) used
     max_size        size of (number of sequences in) the largest contig
     nof_overlaps    number of overlaps
     min_overlap     minimum overlap length for building a contig
     min_identity    minimum sequence identity over the overlap length
     avg_overlap     average overlap length
     avg_identity    average overlap identity
     avg_seq_length  average sequence length
     eff_asm_params  effective assembly parameters
     spectrum        hash representation of a contig spectrum
 
   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
     dissolve        calculate a dissolved contig spectrum (based on assembly)
     cross           produce a cross contig spectrum (based on assembly)
     add             add a contig spectrum to an existing one
     average         make an average of several contig spectra
 
 

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, ...

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
   http://bugzilla.bioperl.org/
 
 

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 calulated. 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 @asm_list = $csp->assembly();
   Function: Get a reference to the list of assembly object reference used to
             make the contig spectrum object / Update the contig spectrum object
             based on an assembly object.
   Returns : array of Bio::Assembly::Scaffold
   Args    : Bio::Assembly::Scaffold
 
 

drop_assembly

   Title   : drop_assembly
   Usage   : $csp->drop_assembly();
   Function: Remove all assembly objects associated with a contig spectrum.
             Assembly objects can be big. This method allows to free some memory
             when assembly information is not needed anymore.
   Returns : 1 for success, 0 for failure
   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 based on the assembly.
             The mixed contig spectrum object must have been created based on one
             (or several) assembly object(s). Additionally, min_overlap and
             min_identity must have been set (either manually using min_overlap
             or automatically by switching on the eff_asm_params option).
   Returns : 1 for success, 0 for failure
   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.
   Returns : 1 for success, 0 for failure
   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, 0 for failure
   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
   Args    : number of total sequences to assume [optional]
 
 

_naive_assembler

   Title   : _naive_assembler
   Usage   : 
   Function: Determines the contig spectrum (hash representation) of a subset of
             sequences from a mixed contig spectrum by "reassembling" 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. There is no actual alignment done
   Returns : contig spectrum hash reference
   Args    : Bio::Assembly::Contig
             sequence ID array reference
             minimum overlap length (integer) [optional]
             minimum percentage identity (integer) [optional]
 
 

_new_from_assembly

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

_new_dissolved_csp

   Title   : 
   Usage   : create a dissolved contig spectrum object
   Function: 
   Returns : 
   Args    :
 
 

_new_cross_csp

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

_import_assembly

   Title   : _import_assembly
   Usage   : $csp->_import_assembly($assemblyobj);
   Function: Update a contig spectrum object based on an assembly object
   Returns : 1 for success, 0 for error
   Args    : Bio::Assembly::Scaffold assembly 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, 0 for error
   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, 0 for error
   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, 0 for error
   Args    : Bio::Assembly::Tools::ContigSpectrum
 
 

_get_seq_stats

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

_get_overlap_stats

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

_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
             minium overlap length [optional]
             minimum overlap percentage identity [optional]