view release on metacpan or  search on metacpan

lib/Bio/Community/Tools/Summarizer.pm  view on Meta::CPAN

=head1 DESCRIPTION

Summarize communities in a metacommunity by grouping members based on their
taxonomic affiliation first, then by collapsing or removing members with a
relative abundance above or below a specified threshold. Summarizing communities
should be the last step of any community analysis, because it compresses
communities (members, weights, taxonomy, etc.) in a way that cannot be undone.

=head1 AUTHOR

Florent Angly L<florent.angly@gmail.com>

=head1 SUPPORT AND BUGS

User feedback is an integral part of the evolution of this and other Bioperl
modules. Please direct usage questions or support issues to the mailing list, 
L<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.

If you have found a bug, please report it on the BioPerl bug tracking system
to help us keep track the bugs and their resolution:
L<https://redmine.open-bio.org/projects/bioperl/>

=head1 COPYRIGHT

Copyright 2011-2014 by Florent Angly <florent.angly@gmail.com>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.1 or,
at your option, any later version of Perl 5 you may have available.

=head1 APPENDIX

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

=head2 new

 Function: Create a new Bio::Community::Tool::Summarizer object
 Usage   : my $summarizer = Bio::Community::Tools::Summarizer->new(
              -metacommunity => $meta,
           );
 Args    : -metacommunity   : See metacommunity().
           -merge_dups      : See merge_dups().
           -identify_dups_by: See identify_dups_by().
           -by_tax_level    : See by_tax_level().
           -by_rel_ab       : See by_rel_ab().
 Returns : a Bio::Community::Tools::Summarizer object

=cut


package Bio::Community::Tools::Summarizer;

use Moose;
use MooseX::NonMoose;
use MooseX::StrictConstructor;
use Method::Signatures;
use namespace::autoclean;
use Bio::Community::IO;
use Bio::Community::Meta;
use Bio::Community::TaxonomyUtils
   qw(get_taxon_lineage get_lineage_string clean_lineage_arr);

use POSIX; # defines DBL_EPSILON to something like 2.22044604925031e-16
use constant EPSILON => 100 * DBL_EPSILON; # suggested in "Mastering Algorithms in Perl"


extends 'Bio::Root::Root';


=head2 metacommunity

 Function: Get/set communities, given as metacommunity, to summarize.
 Usage   : my $meta = $summarizer->metacommunity;
 Args    : A Bio::Community::Meta object
 Returns : A Bio::Community::Meta object

=cut

has metacommunity => (
   is => 'rw',
   isa => 'Maybe[Bio::Community::Meta]',
   required => 0,
   lazy => 1,
   default => undef,
   init_arg => '-metacommunity',
);


=head2 merge_dups

 Function: Merge duplicate community members into a single one. For example, if
           your community contained several members with a taxonomic lineage of
           'Archaea;Euryarchaeota;Halobacteria', all would be merged into a new
           member with the same taxonomy and the sum of the counts. See the
           identify_dups_by() method to specify what constitutes duplicates.
           Note that merging duplicates takes place before grouping by taxonomy
           level, by_tax_level().
 Usage   : $summarizer->merge_dups(1);
 Args    : 0 (no) or 1 (yes). Default: 1
 Returns : a positive integer

=cut

has merge_dups => (
   is => 'rw',
   isa => 'Bool',
   required => 0,
   lazy => 1,
   default => 1,
   init_arg => '-merge_dups',
);


=head2 identify_dups_by

 Function: Define what constitute duplicates, i.e. members that have the same
           desc() or the same taxon().