++ed by:

11 PAUSE users
14 non-PAUSE users.

Christopher Fields
and 1 contributors

# NAME

Bio::Assembly::Tools::ContigSpectrum

# 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;
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";

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";``````

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

## Implemention

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)
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://bio.perl.org/MailList.html     - About the mailing lists``````

## 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
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

## 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``````

``````  Title   : add
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``````

## _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
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

## _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]``````