comparison groups visualizer, docstrings, plugin setup help text

q2_qsip2/plugin_setup.py

@@ -8,14 +8,15 @@
 
 import importlib
 
-from qiime2.plugin import Bool, Citations, Metadata, Plugin, Str
+from qiime2.plugin import Bool, Citations, List, Metadata, Plugin, Str
 from q2_types.feature_table import FeatureTable, Frequency
 
 from q2_qsip2 import __version__
 from q2_qsip2.workflow import standard_workflow, create_qsip_data
 from q2_qsip2.types import QSIP2Data
 from q2_qsip2.visualizers._visualizers import (
-    plot_weighted_average_density, plot_sample_curves, plot_density_outliers
+    plot_weighted_average_densities, plot_sample_curves, plot_density_outliers,
+    show_comparison_groups
 )
 
 
@@ -91,14 +92,14 @@
     output_descriptions={
         'qsip_data': 'Placeholder.'
     },
-    name='Bundle qSIP metadata and feature table.',
+    name='Bundle your qSIP metadata and feature table.',
     description=(
         'Placeholder.'
     )
 )
 
 plugin.visualizers.register_function(
-    function=plot_weighted_average_density,
+    function=plot_weighted_average_densities,
     inputs={
         'qsip_data': QSIP2Data
     },
@@ -107,14 +108,16 @@
     },
     input_descriptions={
         'qsip_data': 'The qSIP data for which to plot the weighted average '
-                       'densities.'
+                     'densities.'
     },
     parameter_descriptions={
-        'group': 'A source-level metadata column used to facet the '
-                 'plot of weighted average densities.'
+        'group': 'A source-level metadata column used to facet the plot.'
     },
     name='Plot weighted average densities.',
-    description=('Placeholder'),
+    description=(
+        'Plots the per-source weighted average density, colored by isotope '
+        'and optionally faceted by the source-level metadata column `group`.'
+    ),
     citations=[],
 )
 
@@ -125,12 +128,13 @@
     },
     parameters={},
     input_descriptions={
-        'qsip_data': 'The qSIP data for which to plot the per-source density '
-                       'curves.'
+        'qsip_data': 'The qsip data artifact.'
     },
     parameter_descriptions={},
     name='Plot per-source density curves.',
-    description=('Placeholder'),
+    description=(
+        'Plots gradient position by relative amount of DNA, faceted by source.'
+    ),
     citations=[],
 )
 
@@ -141,12 +145,37 @@
     },
     parameters={},
     input_descriptions={
-        'qsip_data': 'The qSIP data for which to plot the per-source density '
-                       'outliers.'
+        'qsip_data': 'The qsip data artifact.'
     },
     parameter_descriptions={},
     name='Plot per-source density outliers.',
-    description=('Placeholder'),
+    description=(
+        'Plots gradient position by density, faceted by source, and performs '
+        'Cook\'s outlier detection.'
+    ),
+    citations=[],
+)
+
+plugin.visualizers.register_function(
+    function=show_comparison_groups,
+    inputs={
+        'qsip_data': QSIP2Data
+    },
+    parameters={
+        'groups': List[Str]
+    },
+    input_descriptions={
+        'qsip_data': 'The qsip data artifact.'
+    },
+    parameter_descriptions={
+        'groups': 'The names of one or more source-level metadata columns used '
+                  'to further subdivide the labeled and unlabeled samples.'
+    },
+    name='Show available comparison groupings.',
+    description=(
+        'Displays a table of source-level ids grouped in columns by isotope '
+        'and in rows by the given groups.'
+    ),
     citations=[],
 )
 

q2_qsip2/visualizers/_helpers.py

@@ -30,5 +30,4 @@ def _ggplot2_object_to_visualization(
         device='svg',
         width=width,
         height=height,
-        # units='px'
     )

q2_qsip2/visualizers/_visualizers.py

@@ -9,6 +9,7 @@
 import rpy2.robjects as ro
 from rpy2.robjects.methods import RS4
 from rpy2.robjects.packages import importr
+from rpy2.robjects import pandas2ri
 
 from typing import Optional
 from pathlib import Path
@@ -17,12 +18,27 @@
 
 qsip2 = importr('qSIP2')
 
-def plot_weighted_average_density(
+def plot_weighted_average_densities(
     output_dir: str, qsip_data: RS4, group: Optional[str] = None
 ) -> None:
     '''
+    Plots the per-source weighted average density, colored by isotope and
+    optionally faceted by a source-level metadata column in `group`.
+
+    Parameters
+    ----------
+    output_dir : str
+        The root directory of the visualization loaded into the browser.
+    qsip_data : RS4
+        The "qsip_data" object.
+    group : str | None
+        An optional source-level metadata column used to facet the plot of
+        weighted average densities.
     '''
-    plot = qsip2.plot_source_wads(qsip_data, group=group)
+    if group:
+        plot = qsip2.plot_source_wads(qsip_data, group=group)
+    else:
+        plot = qsip2.plot_source_wads(qsip_data)
 
     _ggplot2_object_to_visualization(
         plot, Path(output_dir), width=10, height=4
@@ -31,6 +47,14 @@ def plot_weighted_average_density(
 
 def plot_sample_curves(output_dir: str, qsip_data: RS4) -> None:
     '''
+    Plots gradient position by relative amount of DNA, faceted by source.
+
+    Parameters
+    ----------
+    output_dir : str
+        The root directory of the visualization loaded into the browser.
+    qsip_data : RS4
+        The "qsip_data" object.
     '''
     plot = qsip2.plot_sample_curves(qsip_data)
 
@@ -41,9 +65,43 @@ def plot_sample_curves(output_dir: str, qsip_data: RS4) -> None:
 
 def plot_density_outliers(output_dir: str, qsip_data: RS4) -> None:
     '''
+    Plots gradient position by density, faceted by source, and performs
+    Cook's outlier detection.
+
+    Parameters
+    ----------
+    output_dir : str
+        The root directory of the visualization loaded into the browser.
+    qsip_data : RS4
+        The "qsip_data" object.
     '''
     plot = qsip2.plot_density_outliers(qsip_data)
 
     _ggplot2_object_to_visualization(
         plot, Path(output_dir), width=10, height=10
     )
+
+
+def show_comparison_groups(
+    output_dir: str, qsip_data: RS4, groups: list
+) -> None:
+    '''
+    Displays a table of ids grouped in columns by isotope, and in rows by the
+    given groups.
+
+    Parameters
+    ----------
+    output_dir : str
+        The root directory of the visualization loaded into the browser.
+    qsip_data : RS4
+        The "qsip_data" object.
+    groups : list[str]
+        The names of one or more source-level metadata columns used to further
+        subdivide the labeled and unlabeled samples.
+    '''
+    groups_vector = ro.vectors.StrVector(groups)
+
+    with (ro.default_converter + pandas2ri.converter).context():
+        df = qsip2.show_comparison_groups(qsip_data, groups_vector)
+
+    df.to_html(Path(output_dir) / 'index.html')

q2_qsip2/workflow.py

@@ -35,6 +35,7 @@ def standard_workflow(
     return table
 
 
+
 def create_qsip_data(
     table: biom.Table,
     sample_metadata: qiime2.Metadata,
@@ -106,7 +107,7 @@ def create_qsip_data(
     table_df.index.name = 'ASV'
     table_df.reset_index(inplace=True)
 
-    # construct R objects
+    # construct qsip object
     with (ro.default_converter + pandas2ri.converter).context():
         R_source_obj = qsip2.qsip_source_data(
             source_df, source_mat_id=source_index_name