Reference

Bio::Assembly::Tools::ContigSpectrum(3pm)

create and manipulate contig spectra

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.

  [email protected]                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

Support

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

[email protected]

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:

  [email protected]
  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'

History