NAME

Bio::Community::Tools::Summarizer - Create a summary of communities

SYNOPSIS

use Bio::Community::Tools::Summarizer;

# Given a metacommunity, merge community members with the same taxonomy, then
# group members at the second level of their taxonomy (i.e. phylum level when
# using the Greengenes taxonomy), then group members at less than 1% relative
# abundance into a single group called 'Other':
my $summarizer = Bio::Community::Tools::Summarizer->new(
   -metacommunity => $meta,
   -merge_dups    => 1,
   -by_tax_level  => 2,
   -by_rel_ab     => ['<', 1],
);
my $summarized_meta = $summarizer->get_summary;

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.

AUTHOR

Florent Angly florent.angly@gmail.com

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, 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: https://redmine.open-bio.org/projects/bioperl/

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.

APPENDIX

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

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

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

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

identify_dups_by

Function: Define what constitute duplicates, i.e. members that have the same
          desc() or the same taxon().
Usage   : $summarizer->identify_dups_by('taxon');
Args    : 'desc' or 'taxon'. Default: 'desc'
Returns : 'desc' or 'taxon'

by_tax_level

Function: Get/set the taxonomic level at which to group community members. When
          community members have taxonomic information attached, add the
          relative abundance of all members belonging to the same taxonomic
          level. The taxonomic level depends on which taxonomy is used. For the
          Greengenes taxonomy, level 1 represents kingdom, level 2 represents
          phylum, and so on, until level 7, representing the species level.
          Members without taxonomic information are grouped together in a Member
          with the description 'Unknown taxonomy'.
          Note that summarizing by taxonomy level takes place before grouping by
          relative abundance, by_rel_ab(). Also, since each community member
          represents the combination of multiple members, they have to be given
          a new weight, that is specific to the community they belong to.
Usage   : $summarizer->by_tax_level(2);
Args    : a positive integer
Returns : a positive integer

by_rel_ab

Function: Get/set the relative abundance threshold to group members together.
          Example: You provide a metacommunity containing multiple communities
          and you specify to group members with a relative abundance less than
          1%. If the abundance of member A is less than 1% in all the
          communities, it is removed from the communities and added as a new
          member with the desciption 'Other < 1%' along with all other members
          that are less than 1% in all the communities.
          Note that when community members are weighted, the 'Other' group also
          has to be weighted differently for each community.
Usage   : $summarizer->by_rel_ab('<', 1);
Args    : * the type of numeric comparison, '<', '<=', '>=', '>'
          * the relative abundance threshold (in %)
Returns : * the type of numeric comparison, '<', '<=', '>=', '>'
          * the relative abundance threshold (in %)

get_summary

Function: Summarize the communities and return an arrayref of fresh communities.
Usage   : my $summary = $summarizer->get_summary;
Args    : None
Returns : A Bio::Community::Meta object