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