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: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_comAPPENDIX
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
minium 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'