/ 
Bio-Community-0.001008
River stage zero No dependents
/ Bio::Community::Meta

NAME

Bio::Community::Meta - A metacommunity, or group of communities

SYNOPSIS

use Bio::Community::Meta;

my $meta = Bio::Community::Meta->new( -name => 'alpine' );

# Get communities from somewhere and ...
$meta->add_communities( [$community1, $community2, $community3] );

print "Metacommunity contains:\n";
print "   ".$meta->get_communities_count." communities\n";
print "   ".$meta->get_richness." species\n";
print "   ".$meta->get_members_count." individuals\n";

DESCRIPTION

The Bio::Community::Meta module represent metacommunities, or groups of communities. This object holds several Bio::Community objects, for example tree communities found at different sites of a forest. Random access to any of the communities is provided. However, the communities can also be accessed sequentially, in the order they were given. This makes Bio::Community::Meta capable of representing communities along a natural gradient.

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::Meta object
Usage   : my $meta = Bio::Community::Meta->new( ... );
Args    : -name               : See name()
          -communities        : See add_communities()
          -identify_members_by: See identify_members_by()
Returns : A new Bio::Community::Meta object

name

Function: Get or set the name of the metacommunity
Usage   : $meta->name('estuary_salinity_gradient');
          my $name = $meta->name();
Args    : String for the name
Returns : String for the name

identify_members_by

Function: Get or set how members are handled.
          In the Bio::Community modules, members with the same ID are
          considered identical, no matter what their description or taxonomy is.
          If the communities added to the metacommunity come from different
          sources or files, the IDs of the members are unsafe because the same
          member in different communities will likely have a different ID and
          be interpreted as a different member, whereas different members may
          have the same ID and be counted as the same. To work around this, you
          can specify to look at the desc() of the members and give the same ID
          to members that have the same description.
Usage   : $meta->identify_members_by('desc');
Args    : String, either 'id' or 'desc'
Returns : String, either 'id' (default) or 'desc'

add_communities

Function: Add communities to a metacommunity. Communities have to have distinct
          names. Do not change the name of a community after you have added it!
Usage   : $meta->add_communities([$community1, $community2]);
Args    : An arrayref of Bio::Community objects to add
Returns : 1 on success

remove_community

Function: Remove a community from a metacommunity
Usage   : $meta->remove_community($community);
Args    : A Bio::Community to remove
Returns : 1 on success

next_community

Function: Access the next community in the metacommunity (in the order the
          communities were added). 
Usage   : my $community = $meta->next_community();
Args    : None
Returns : A Bio::Community object

get_all_communities

Function: Generate a list of all communities in the metacommunity.
Usage   : my $communities = $meta->get_all_communities();
Args    : None
Returns : An arrayref of Bio::Community objects

get_metacommunity

Function: Generate a community that is the sum of all the members of the
          communities. If sampling effort was unequal between your communities,
          you may consider using L<Bio::Community::Tools::Rarefier>.
Usage   : my $metacommunity = $meta->get_metacommunity();
Args    : None
Returns : A new Bio::Community object

get_community_by_name

Function: Fetch a community based on its name
Usage   : my $community = $meta->get_community_by_name('prairie');
Args    : String of the community name to look for
Returns : A Bio::Community object or undef if the community was not found

get_communities_count

Function: Get the total number of communities in the metacommunity
Usage   : my $nof_communities = $meta->get_communities_count();
Args    : None
Returns : Integer for the count

get_all_members

Function: Generate a list of all members in the metacommunity. Every member
          appears only once in this list, even if the member is present in
          multiple communities. Remember that members with the same ID are
          considered the same member.
Usage   : my $members = $meta->get_all_members();
Args    : None
Returns : An arrayref of Bio::Community::Member objects

get_members_count

Function: Calculate the total count of members in the metacommunity.
Usage   : my $nof_individuals = $meta->get_members_count;
Args    : None
Returns : Integer for the count

get_richness

Function: Calculate the richness of the metacommunity (number of different
          types of members). This is a form of gamma diversity.
Usage   : my $gamma_richness = $meta->get_richness();
Args    : None
Returns : Integer for the richness