:py:mod:`biotaphy.analyses.phylo_beta_diversity`
================================================

.. py:module:: biotaphy.analyses.phylo_beta_diversity

.. autoapi-nested-parse::

   Module containing code for calculating phylogenetic beta diversity.

   .. note::

      * Numpy and Scipy may have the methods needed for these computations.  Feel
          free to take advantage of those to libraries as they are already
          dependencies.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   biotaphy.analyses.phylo_beta_diversity.calculate_phylo_beta_diversity_jaccard
   biotaphy.analyses.phylo_beta_diversity.calculate_phylo_beta_diversity_sorensen
   biotaphy.analyses.phylo_beta_diversity.core_Beta_calc
   biotaphy.analyses.phylo_beta_diversity.core_PD_calc
   biotaphy.analyses.phylo_beta_diversity.pdnew



.. py:function:: calculate_phylo_beta_diversity_jaccard(pam, tree)

   Calculates phylogenetic beta diversity for the jaccard index family.

   :param pam: A Lifemapper Matrix object with presence absence
               values (site rows by species columns).
   :type pam: :obj:`Matrix`
   :param tree: A TreeWrapper object for a wrapped Dendropy
                phylogenetic tree.
   :type tree: :obj:`TreeWrapper`

   :returns:

             Phylogenetic beta diversity matrics (species by species)
                 * beta_jtu: ADD DESCRIPTION
                 * phylo_beta_jtu: ADD DESCRIPTION
                 * beta_jne: ADD DESCRIPTION
                 * phylo_beta_jne: ADD DESCRIPTION
                 * beta_jac: ADD DESCRIPTION
                 * phylo_beta_jac: ADD DESCRIPTION

   .. note::

      * It looks like the scipy.spatial.distance.jaccard method may be useful
          here.

   .. todo::

      * Fill in method documentation
      * Fill in method


.. py:function:: calculate_phylo_beta_diversity_sorensen(pam, tree)

   Calculates phylogenetic beta diversity for the sorensen index family.

   :param pam: A Lifemapper Matrix object with presence absence
               values.
   :type pam: :obj:`Matrix`
   :param tree: A TreeWrapper object for a wrapped Dendropy
                phylogenetic tree.
   :type tree: :obj:`TreeWrapper`

   :returns:

             Phylogenetic beta diversity matrics (species by species)
                 * beta_sim: ADD DESCRIPTION
                 * phylo_beta_sim: ADD DESCRIPTION
                 * beta_sne: ADD DESCRIPTION
                 * phylo_beta_sne: ADD DESCRIPTION
                 * beta_sor: ADD DESCRIPTION
                 * phylo_beta_sor: ADD DESCRIPTION

   .. todo::

      * Fill in method documentation
      * Fill in method


.. py:function:: core_Beta_calc(pam, tree)

   Creates an array of core metrics to asses beta diversity components.

   :param pam (: obj:'Matrix'): A Lifemapper Matrix object with presence absence values.
   :param tree (: obj:'TreeWrapper'): A TreeWrapper object for a wrapped Dendropy
                  phylogenetic tree.

   :returns: List of arrays, see Details.

   Details:
       In general, the metrics returned represent different contributions
       to beta diversity arising from how communities are combined together.
       Metrics:
           shared_array: spp shared in each pairwise comm. combinations.
           not_shared_array: spp. not shared btwn pairwise comm. combinations.
           sum_not_shared:
           max_not_shared:
           min_not_shared:


.. py:function:: core_PD_calc(pam, tree)

   Creates array of core metrics to asses components of beta diversity.

   :param pam (: obj:'Matrix'): A Lifemapper Matrix object with presence absence values.
   :param tree (: obj:'TreeWrapper'): A TreeWrapper object for a wrapped Dendropy
                  phylogenetic tree.

   :returns: Matrix object. Cols=core metrics; Rows=Pairwise comparisons.

   Details:
       In general, the metrics returned represent different contributions to
       PD arising from how communities are combined together.
       Metrics:
           min_not_shared: smallest dist. from ind. samples to their combo.
           max_not_shared: largest dist. from ind. samples to their combo.
           sum_not_shared: total addition to PD from both comm.
           shared: combined contribution to PD that comm. make jointly.


.. py:function:: pdnew(pam, tree)

   Creates a lookup dictionary for PD of sites in a matrix.

   :param pam: A Lifemapper Matrix object with presence absence values.
   :type pam: :obj:`Matrix`
   :param tree: A TreeWrapper object for a wrapped Dendropy
                phylogenetic tree.
   :type tree: :obj:`TreeWrapper`

   :returns: Matrix object w/ PD values & spp. rch for each community in sample.
             Col1 = PD; Col2 = SR; Rows = Indvidual samples from pam.