Merge 7856db6 into 1c98481

q2_diversity/__init__.py

@@ -10,7 +10,8 @@
                      alpha_correlation, alpha_rarefaction)
 from ._beta import (beta, beta_phylogenetic, bioenv,
                     beta_group_significance, mantel, beta_rarefaction,
-                    beta_correlation, adonis)
+                    beta_correlation, adonis,
+                    beta_phylogenetic_meta)
 from ._ordination import pcoa, pcoa_biplot
 from ._procrustes import procrustes_analysis
 from ._core_metrics import core_metrics_phylogenetic, core_metrics
@@ -28,4 +29,4 @@
            'core_metrics_phylogenetic', 'core_metrics',
            'filter_distance_matrix', 'mantel', 'alpha_rarefaction',
            'beta_rarefaction', 'procrustes_analysis', 'beta_correlation',
-           'adonis']
+           'adonis', 'beta_phylogenetic_meta']

q2_diversity/_beta/__init__.py

@@ -8,7 +8,7 @@
 
 from q2_diversity_lib.beta import METRICS
 
-from ._pipeline import beta_phylogenetic, beta
+from ._pipeline import beta_phylogenetic, beta, beta_phylogenetic_meta
 from ._visualizer import bioenv, beta_group_significance, mantel, adonis
 from ._beta_rarefaction import beta_rarefaction
 from ._beta_correlation import beta_correlation
@@ -17,4 +17,5 @@
 __all__ = [
     'beta_phylogenetic', 'beta', 'bioenv', 'beta_group_significance', 'mantel',
     'beta_rarefaction', 'beta_correlation', 'adonis', 'METRICS',
+    'beta_phylogenetic_meta'
 ]

q2_diversity/_beta/_pipeline.py

@@ -9,6 +9,29 @@
 from . import METRICS
 
 
+def beta_phylogenetic_meta(ctx,
+                           table,
+                           phylogeny,
+                           metric,
+                           threads=1,
+                           variance_adjusted=False,
+                           alpha=None,
+                           bypass_tips=False):
+    # TODO: remove when we can handle optional type-mapped parameters
+    if alpha is not None and metric != 'generalized_unifrac':
+        raise ValueError('The alpha parameter is only allowed when the choice'
+                         ' of metric is generalized_unifrac')
+
+    action = ctx.get_action('diversity_lib',
+                            'beta_phylogenetic_meta_passthrough')
+
+    dm, = action(table, phylogeny, metric=metric, threads=threads,
+                 variance_adjusted=variance_adjusted, alpha=alpha,
+                 bypass_tips=bypass_tips)
+
+    return dm
+
+
 def beta_phylogenetic(ctx,
                       table,
                       phylogeny,

q2_diversity/plugin_setup.py

@@ -8,7 +8,7 @@
 
 from qiime2.plugin import (Plugin, Str, Properties, Choices, Int, Bool, Range,
                            Float, Set, Visualization, Metadata, MetadataColumn,
-                           Categorical, Numeric, Citations)
+                           Categorical, Numeric, Citations, List)
 
 import q2_diversity
 from q2_diversity import _alpha as alpha
@@ -103,6 +103,55 @@
                  " for all pairs of samples in a feature table.")
 )
 
+
+plugin.pipelines.register_function(
+    function=q2_diversity.beta_phylogenetic_meta,
+    inputs={'table': List[FeatureTable[Frequency |
+                          RelativeFrequency |
+                          PresenceAbsence]],
+            'phylogeny': List[Phylogeny[Rooted]]},
+    parameters={'metric': Str % Choices(beta.METRICS['PHYLO']['IMPL'] |
+                                        beta.METRICS['PHYLO']['UNIMPL']),
+                'threads': Int % Range(1, None) | Str % Choices(['auto']),
+                'variance_adjusted': Bool,
+                'alpha': Float % Range(0, 1, inclusive_end=True),
+                'bypass_tips': Bool},
+    outputs=[('distance_matrix', DistanceMatrix)],
+    input_descriptions={
+        'table': ('The feature table containing the samples over which beta '
+                  'diversity should be computed.'),
+        'phylogeny': ('Phylogenetic tree containing tip identifiers that '
+                      'correspond to the feature identifiers in the table. '
+                      'This tree can contain tip ids that are not present in '
+                      'the table, but all feature ids in the table must be '
+                      'present in this tree.')
+    },
+    parameter_descriptions={
+        'metric': 'The beta diversity metric to be computed.',
+        'threads': threads_description,
+        'variance_adjusted': ('Perform variance adjustment based on Chang et '
+                              'al. BMC Bioinformatics 2011. Weights distances '
+                              'based on the proportion of the relative '
+                              'abundance represented between the samples at a'
+                              ' given node under evaluation.'),
+        'alpha': ('This parameter is only used when the choice of metric is '
+                  'generalized_unifrac. The value of alpha controls importance'
+                  ' of sample proportions. 1.0 is weighted normalized UniFrac.'
+                  ' 0.0 is close to unweighted UniFrac, but only if the sample'
+                  ' proportions are dichotomized.'),
+        'bypass_tips': ('In a bifurcating tree, the tips make up about 50% of '
+                        'the nodes in a tree. By ignoring them, specificity '
+                        'can be traded for reduced compute time. This has the'
+                        ' effect of collapsing the phylogeny, and is analogous'
+                        ' (in concept) to moving from 99% to 97% OTUs')
+    },
+    output_descriptions={'distance_matrix': 'The resulting distance matrix.'},
+    name='Beta diversity (phylogenetic)',
+    description=("Computes a user-specified phylogenetic beta diversity metric"
+                 " for all pairs of samples in the feature tables.")
+)
+
+
 plugin.pipelines.register_function(
     function=q2_diversity.beta,
     inputs={'table':