NAME

Bio::Community::Meta::Beta - Beta diversity or distance separating communities

SYNOPSIS

  use Bio::Community::Meta;
  use Bio::Community::Meta::Beta;

  # Beta diversity of two communities
  my $beta = Bio::Community::Meta::Beta->new(
     -metacommunity => Bio::Community::Meta->new(-communities => [$community1, $community2] ),
     -type          => 'euclidean',
  );
  my $value = $beta->get_beta;

  # Beta diversity between all pairs of communities in the given metacommunity
  $beta = Bio::Community::Meta::Beta->new(
     -metacommunity => $meta,
     -type          => 'hellinger',
  );
  my ($average_value, $value_hashref) = $beta->get_all_beta;

DESCRIPTION

Calculate how dissimilar communities are by calculating their beta diversity. The more different communities are, the larger their beta diversity. Often, beta diversity metrics are actually a distance measurement.

Several types of beta diversity metrics are available: 1-norm, 2-norm (euclidean), and infinity-norm, Hellinger distance, Bray-Curtis dissimilarity, Jaccard distance, Sørensen dissimilarity and MaxiPhi index.

Since the relative abundance of community members is not always proportional to member counts (see weights() in Bio::Community::Member and use_weights() in Bio::Community), the beta diversity measured here are always based on relative abundance (as a fractional number between 0 and 1, not as a percentage), even for beta diversity metrics that are usually based on number of observations (counts).

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::Beta object
 Usage   : my $beta = Bio::Community::Meta::Beta->new(
              -metacommunity => $meta,
              -type          => 'euclidean',
           );
 Args    : -metacommunity : See metacommunity(). This is required!
           -type          : See type().
 Returns : a Bio::Community::Meta::Beta object

metacommunity

 Function: Get or set the communities to process, given as a metacommunity.
 Usage   : my $meta = $beta->metacommunity;
 Args    : A Bio::Community::Meta object
 Returns : A Bio::Community::Meta object

type

 Function: Get or set the beta diversity metric to calculate.
 Usage   : my $type = $beta->type;
 Args    : String for the desired type of beta diversity.

           Qualitative (presence/absence):
            * jaccard: the Jaccard distance (between 0 and 1), i.e. the
                fraction of non-shared species relative to the overall richness
                of the metacommunity.
            * sorensen: the Sørensen dissimilarity, or Whittaker's species
                turnover (between 0 and 1), i.e. the fraction of non-shared
                species relative to the average richness in the metacommunity.
            * shared: percentage of species shared (between 0 and 100), relative
                to the least rich community. Note: this is the opposite
                of a beta diversity measure since the higher the percent of
                species shared, the smaller the beta diversity.

           Quantitative:
            * 1-norm: the 1-norm, or Manhattan distance, i.e. the sum of
                 difference in abundance for all species.
            * 2-norm (euclidean): the 2-norm, or euclidean distance.
            * infinity-norm: the infinity-norm, i.e. the maximum difference in
                 abundance over all species.
            * hellinger: like the euclidean distance, but constrained between 0
                and 1.
            * bray-curtis: the Bray-Curtis dissimilarity (or Sørensen
                quantitative index), which varies between 0 and 1.
            * morisita-horn: the Morisita-Horn dissimilarity, which varies
                between 0 and 1. Affected strongly by the abundance of the most
                abundant species, but not by sample size or richness.
            * permuted: a beta diversity measure between 0 and 100, representing
                the percentage of the dominant species in the first community
                with a permuted abundance rank in the second community. As a
                special case, when no species are shared (and the percentage
                permuted is meaningless), undef is returned.
            * maxiphi: a beta diversity measure between 0 and 1, based on the 
                percentage of species shared and the percentage of top species
                permuted (that have had a change in abundance rank).

 Returns : String for the desired type of beta diversity

get_beta

 Function: Calculate the beta diversity between two communities. The input
           metacommunity should contain exactly two communities. The distance is
           calculated based on the relative abundance (in %) of the members (not
           their counts).
 Usage   : my $value = $beta->get_beta;
 Args    : None
 Returns : A number for the beta diversity value

get_all_beta

 Function: Similar to get_beta(), but return the beta diversity between all pairs
           of communities in the given metacommunity and also return their
           average beta diversity.
 Usage   : my ($average, $betas) = $beta->get_all_beta;
 Args    : None
 Returns : * A number for the average beta diversity
           * A hashref of hashref with the value of all pairwise beta diversities,
             keyed by the community names. To get the beta diversity of a specific
             pair of communities, do:
                my $value = $betas->{$name1}->{$name2};
             or:
                my $value = $betas->{$name2}->{$name1};