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

NAME

Bio::Community - A biological community

SYNOPSIS

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";
}

DESCRIPTION

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.

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 object
Usage   : my $community = Bio::Community->new( ... );
Args    : -name and -use_weights, see below...
Returns : a new Bio::Community object

name

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

use_weights

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

get_average_weights

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

get_members_count

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

add_member

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

remove_member

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

next_member

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

get_all_members

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

get_member_by_id

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

get_member_by_rank

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

get_richness

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

get_count

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.

get_rel_ab

Function: Determine the relative abundance (in percent) of a member in the
          community.
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

get_abs_ab

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

get_rank

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