refactor resample action

- removed unused code and associated tests
- added tests of resample action
- removed random_seed parameter (it seems to have not worked when I
  added tests, possibly b/c under the hood the randomization is happening with
  numpy.random, not Python's random) - this should be added back at some
  point, but i don't have time right now - see issue #18
- updated copyright headers
- edited help text, refactored for re-use in related actions
- added usage examples

q2_boots/__init__.py

@@ -1,12 +1,12 @@
 # ----------------------------------------------------------------------------
-# Copyright (c) 2023, QIIME 2 development team.
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
 #
 # Distributed under the terms of the Modified BSD License.
 #
 # The full license is in the file LICENSE, distributed with this software.
 # ----------------------------------------------------------------------------
 
-from ._normalize import _bootstrap_iteration, resample
+from ._resample import resample
 from .alpha import (alpha,
                     alpha_collection,
                     alpha_average)
@@ -15,7 +15,7 @@
 from .core_metrics import (core_metrics)
 from . import _version
 
-__all__ = ['_bootstrap_iteration', 'resample',
+__all__ = ['resample',
            'alpha',
            'alpha_collection',
            'beta',

q2_boots/_examples.py

@@ -0,0 +1,46 @@
+# ----------------------------------------------------------------------------
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file LICENSE, distributed with this software.
+# ----------------------------------------------------------------------------
+
+import pandas as pd
+import qiime2
+
+def table_factory():
+    table = pd.DataFrame(data=[[0, 1, 1],
+                               [10, 10, 9],
+                               [30, 20, 9],
+                               [42, 42, 9]],
+                         columns=['F1', 'F2', 'F3'],
+                         index=['S1', 'S2', 'S3', 'S4'])
+    return qiime2.Artifact.import_data(
+        "FeatureTable[Frequency]", table, view_type=pd.DataFrame)
+
+def _resample_bootstrap_example(use):
+    table = use.init_artifact('table', table_factory)
+
+    resampled_tables, = use.action(
+        use.UsageAction(plugin_id='boots',
+                        action_id='resample'),
+        use.UsageInputs(table=table,
+                        sampling_depth=20,
+                        n=10,
+                        replacement=True),
+        use.UsageOutputNames(resampled_tables='bootstrapped_tables')
+    )
+
+def _resample_rarefaction_example(use):
+    table = use.init_artifact('table', table_factory)
+
+    resampled_tables, = use.action(
+        use.UsageAction(plugin_id='boots',
+                        action_id='resample'),
+        use.UsageInputs(table=table,
+                        sampling_depth=20,
+                        n=10,
+                        replacement=False),
+        use.UsageOutputNames(resampled_tables='rarefaction_tables')
+    )

q2_boots/_resample.py

@@ -0,0 +1,19 @@
+# ----------------------------------------------------------------------------
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file LICENSE, distributed with this software.
+# ----------------------------------------------------------------------------
+
+def resample(ctx, table, sampling_depth, n, replacement):
+    rarefy_action = ctx.get_action('feature_table', 'rarefy')
+    resampled_tables = []
+
+    for i in range(n):
+        resampled_table = rarefy_action(table=table,
+                                        sampling_depth=sampling_depth,
+                                        with_replacement=replacement)[0]
+        resampled_tables.append(resampled_table)
+
+    return {f'resampled-table-{i}': t for i, t in enumerate(resampled_tables)}

q2_boots/alpha.py

@@ -1,5 +1,5 @@
 # ----------------------------------------------------------------------------
-# Copyright (c) 2023, QIIME 2 development team.
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
 #
 # Distributed under the terms of the Modified BSD License.
 #

q2_boots/beta.py

@@ -1,5 +1,5 @@
 # ----------------------------------------------------------------------------
-# Copyright (c) 2023, QIIME 2 development team.
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
 #
 # Distributed under the terms of the Modified BSD License.
 #

q2_boots/core_metrics.py

@@ -1,5 +1,5 @@
 # ----------------------------------------------------------------------------
-# Copyright (c) 2023, QIIME 2 development team.
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
 #
 # Distributed under the terms of the Modified BSD License.
 #

q2_boots/plugin_setup.py

@@ -1,5 +1,5 @@
 # ----------------------------------------------------------------------------
-# Copyright (c) 2023, QIIME 2 development team.
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
 #
 # Distributed under the terms of the Modified BSD License.
 #
@@ -23,6 +23,78 @@
 from q2_types.ordination import PCoAResults
 
 import q2_boots
+from q2_boots._examples import (_resample_bootstrap_example,
+                                _resample_rarefaction_example)
+
+Citations = Citations.load('citations.bib', package='q2_boots')
+
+plugin = Plugin(
+    name='boots',
+    version=q2_boots.__version__,
+    website='https://github.com/caporaso-lab/q2-boots',
+    package='q2_boots',
+    short_description=('Bootstrapped and rarefaction-based diversity '
+                       'analyses.'),
+    description=('A plugin providing bootstrapped and rarefaction-based '
+                 'diversity analyses, designed to mirror the interface of '
+                 'q2-diversity.')
+)
+
+
+_feature_table_description = 'The feature table to be resampled.'
+_sampling_depth_description = (
+    'The total number of observations that each sample in `table` should be '
+    'resampled to. Samples where the total number of observations in `table` '
+    'is less than `sampling_depth` will be not be included in the output '
+    'tables.')
+_n_description = 'The number of resampled tables that should be generated.'
+_replacement_description = (
+    'Resample `table` with replacement (i.e., bootstrap) or resample without '
+    'replacement (i.e., rarefaction).')
+_resampled_tables_description = 'The `n` resampled tables.'
+
+## Resampling
+
+_resample_inputs = {
+    'table': FeatureTable[Frequency]
+}
+_resample_parameters = {
+    'sampling_depth': Int % Range(1, None),
+    'n': Int % Range(1, None),
+    'replacement': Bool
+}
+_resample_outputs = {
+    'resampled_tables': Collection[FeatureTable[Frequency]]
+}
+_resample_input_descriptions = {
+    'table': _feature_table_description
+}
+_resample_parameter_descriptions = {
+    'sampling_depth': _sampling_depth_description,
+    'n': _n_description,
+    'replacement': _replacement_description
+}
+_resample_output_descriptions = {
+    'resampled_tables': _resampled_tables_description
+}
+
+plugin.pipelines.register_function(
+    function=q2_boots.resample,
+    inputs=_resample_inputs,
+    parameters=_resample_parameters,
+    outputs=_resample_outputs,
+    input_descriptions=_resample_input_descriptions,
+    parameter_descriptions=_resample_parameter_descriptions,
+    output_descriptions=_resample_output_descriptions,
+    name='Resample feature table.',
+    description=('Resample `table` to `sampling_depth` total observations with '
+                 'replacement (i.e., bootstrapping) or without replacement '
+                 '(i.e., rarefaction) `n` times, to generate `n` resampled '
+                 'feature tables.'),
+    examples={'Generate 10 bootstrapped tables.': _resample_bootstrap_example,
+              'Generate 10 rarefied tables.': _resample_rarefaction_example}
+)
+
 
 n_jobs_description = (
     'The number of concurrent jobs to use in performing this calculation. '
@@ -49,47 +121,6 @@
     'included'
 )
 
-Citations = Citations.load('citations.bib', package='q2_boots')
-plugin = Plugin(
-    name='boots',
-    version=q2_boots.__version__,
-    website='https://github.com/caporaso-lab/q2-boots',
-    package='q2_boots',
-    short_description=('Bootstrapped and rarefaction-based diversity '
-                       'analyses.'),
-    description=('A plugin providing bootstrapped and rarefaction-based '
-                 'diversity analyses, designed to mirror the interface of '
-                 'q2-diversity.')
-)
-
-plugin.pipelines.register_function(
-    function=q2_boots.resample,
-    inputs={'table': FeatureTable[Frequency]},
-    parameters={'sampling_depth': Int % Range(1, None),
-                'n': Int % Range(1, None),
-                'replacement': Bool,
-                'random_seed': Int},
-    outputs={'subsampled_tables': Collection[FeatureTable[Frequency]]},
-    input_descriptions={'table': 'The table to be subsampled'},
-    parameter_descriptions={
-        'sampling_depth': ('The total frequency that each sample should be '
-                           'subsampled to. Samples where the sum of frequencies '
-                           'is less than the sampling depth will be not be '
-                           'included in the resulting table.'),
-        'n': 'The number of times to subsample the input table.',
-        'replacement': '',
-        'random_seed': random_seed_description
-    },
-    output_descriptions={
-        'subsampled_tables': 'A collection of n tables normalized to the specified '
-                             'sampling depth'
-    },
-    name='Bootstrap',
-    description='This pipeline is a repeated subsampling of a specified input table. '
-                'N tables are produced normalized so the sum of each sample\'s '
-                'frequency is equal to the sampling depth.'
-)
-
 plugin.pipelines.register_function(
     function=q2_boots.alpha_collection,
     inputs={'table': FeatureTable[Frequency | RelativeFrequency | PresenceAbsence],

q2_boots/tests/test_alpha.py

@@ -1,5 +1,5 @@
 # ----------------------------------------------------------------------------
-# Copyright (c) 2023, QIIME 2 development team.
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
 #
 # Distributed under the terms of the Modified BSD License.
 #

q2_boots/tests/test_beta.py

@@ -1,5 +1,5 @@
 # ----------------------------------------------------------------------------
-# Copyright (c) 2023, QIIME 2 development team.
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
 #
 # Distributed under the terms of the Modified BSD License.
 #

q2_boots/tests/test_core_metrics.py

@@ -1,5 +1,5 @@
 # ----------------------------------------------------------------------------
-# Copyright (c) 2023, QIIME 2 development team.
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
 #
 # Distributed under the terms of the Modified BSD License.
 #

q2_boots/tests/test_examples.py

@@ -0,0 +1,16 @@
+# ----------------------------------------------------------------------------
+# Copyright (c) 2024, Caporaso Lab (https://cap-lab.bio).
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file LICENSE, distributed with this software.
+# ----------------------------------------------------------------------------
+
+from qiime2.plugin.testing import TestPluginBase
+
+
+class UsageExampleTests(TestPluginBase):
+    package = 'q2_boots.tests'
+
+    def test_examples(self):
+        self.execute_examples()