Florent Angly
and 1 contributors


Bio::Community - A biological community


  use Bio::Community;
  my $community = Bio::Community->new( -name => 'soil_1' );
  $community->add_member( $member1 );    # add 1 such Bio::Community::Member
  $community->add_member( $member2, 3 ); # add 3 such members

  print "There are ".$community->get_members_count." members in the community\n";
  print "The total diversity is ".$community->get_richness." species\n";

  while (my $member = $community->next_member) {
     my $member_id     = $member->id;
     my $member_count  = $community->get_count($member);
     my $member_rel_ab = $community->get_rel_ab($member);
     print "The relative abundance of member $member_id is $member_rel_ab % ($member_count counts)\n";


The Bio::Community module represents communities of biological organisms. It is composed of Bio::Community::Member objects at a specified abundance. Each member can represent a species (e.g. an elephant, a bacterium), taxon, OTU, or any proxy for a species.


Florent Angly florent.angly@gmail.com


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


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


 Function: Create a new Bio::Community object
 Usage   : my $community = Bio::Community->new( ... );
 Args    : -name and -use_weights, see below...
 Returns : a new Bio::Community object


 Function: Get or set the name of the community
 Usage   : $community->name('ocean sample 3');
           my $name = $community->name();
 Args    : string for the name
 Returns : string for the name


 Function: Set whether or not relative abundance should be normalized by taking
           into accout the weights of the different members (e.g. genome length,
           gene copy number). Refer to the C<Bio::Community::Member->weights()>
           method for more details. The default is to use the weights that have
           given to community members.
 Usage   : $community->use_weights(1);
 Args    : boolean
 Returns : boolean


 Function: If any weights have been set using Bio::Community::IO, return their
 Usage   : my $averages = $community->get_average_weights;
 Args    : none
 Returns : Arrayref of averages (one average for each file of weights)


 Function: Get the total count of members sampled from the community.
 Usage   : my $total_count = $community->get_members_count();
 Args    : none
 Returns : integer

get_members_abundance, set_members_abundance

 Function: Get or set the total abundance of members in the community. Setting
           this option implies that you know the total abundance of the members
           in the community, even though you have not have sampled them all. If
           this value has not been set explicitly, this method returns
           C<get_members_count> by default.
 Usage   : $community->set_members_abundance( 1.63e6 );
           # or
           my $total_abundance = $community->get_members_abundance();
 Args    : number
 Returns : number


 Function: Add members to a community
 Usage   : $community->add_member($member, 3);
 Args    : * a Bio::Community::Member to add
           * how many of this member to add (positive number, default: 1)
 Returns : 1 on success


 Function: Remove members from a community
 Usage   : $community->remove_member($member, 3);
 Args    : * A Bio::Community::Member to remove
           * Optional: how many of this member to remove. If no value is
             provided, all such members are removed.
 Returns : Number of this member removed


 Function: Access the next member in a community (in no specific order). Be
           warned that each time you change the community, this iterator has to
           start again from the beginning! By default, a single iterator is
           created. However, if you need several independent iterators, simply
           provide an arbitrary iterator name.
 Usage   : # Get members through the default iterator
           my $member = $community->next_member();
           # Get members through an independent, named iterator
           my $member = $community->next_member('other_ite');           
 Args    : an optional name to give to the iterator (must not start with '_')
 Returns : a Bio::Community::Member object


 Function: Generate a list of all members in the community.
 Usage   : my $members = $community->get_all_members();
 Args    : An arrayref of Bio::Community objects
 Returns : An arrayref of Bio::Community::Member objects


 Function: Fetch a member based on its ID.
 Usage   : my $member = $community->get_member_by_id(3);
 Args    : integer for the member ID
 Returns : a Bio::Community::Member object or undef if member was not found


 Function: Fetch a member based on its abundance rank. A smaller rank corresponds
           to a larger relative abundance.
 Usage   : my $member = $community->get_member_by_rank(1);
 Args    : strictly positive integer for the member rank
 Returns : a Bio::Community::Member object or undef if member was not found


 Function: Report the community richness or number of different types of members.
           This is a form of alpha diversity.
 Usage   : my $alpha_richness = $community->get_richness();
 Args    : none
 Returns : integer for the richness


 Function: Fetch the abundance or count of a member
 Usage   : my $count = $community->get_count($member);
 Args    : a Bio::Community::Member object
 Returns : An integer for the count of this member, including zero if the member
           was not present in the community.


 Function: Determine the relative abundance (in percent) of a member in the
 Usage   : my $rel_ab = $community->get_rel_ab($member);
 Args    : a Bio::Community::Member object
 Returns : an integer between 0 and 100 for the relative abundance of this member


 Function: Determine the absolute abundance of a member in the community, i.e.,
           its C<get_rel_ab()> multiplied by its C<get_members_abundance()>.
 Usage   : my $abs_ab = $community->get_abs_ab($member);
 Args    : a Bio::Community::Member object
 Returns : a number for the absolute abundance of this member


 Function: Determine the abundance rank of a member in the community. The
           organism with the highest relative abundance has rank 1, the second-
           most abundant has rank 2, etc.
 Usage   : my $rank = $community->get_rank($member);
 Args    : a Bio::Community::Member object
 Returns : integer for the abundance rank of this member or undef if the member 
           was not found