From b8b81080ccdaeda9ff59a7e054cb378a561b4766 Mon Sep 17 00:00:00 2001 From: Liz Gehret Date: Mon, 7 Oct 2024 14:33:49 -0700 Subject: [PATCH] adds param descriptions and README --- README.md | 84 ++++++++++++------- .../plugin_setup.py | 38 ++++++++- 2 files changed, 90 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 7af824e..0029d6d 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,6 @@ A [QIIME 2](https://qiime2.org) plugin [developed](https://develop.qiime2.org) b ## Installation instructions -**The following instructions are intended to be a starting point** and should be replaced when `gut-to-soil-manuscript-figures` is ready to share with others. -They will enable you to install the most recent *development* version of `gut-to-soil-manuscript-figures`. -Remember that *release* versions should be used for all "real" work (i.e., where you're not testing or prototyping) - if there aren't instructions for installing a release version of this plugin, it is probably not yet intended for use in practice. - ### Install Prerequisites [Miniconda](https://conda.io/miniconda.html) provides the `conda` environment and package manager, and is currently the only supported way to install QIIME 2. @@ -22,64 +18,92 @@ conda update conda ### Install development version of `gut-to-soil-manuscript-figures` Next, you need to get into the top-level `gut-to-soil-manuscript-figures` directory. -If you already have this (e.g., because you just created the plugin), this may be as simple as running `cd gut-to-soil-manuscript-figures`. -If not, you'll need the `gut-to-soil-manuscript-figures` directory on your computer. -How you do that will differ based on how the package is shared, and ideally the developer will update these instructions to be more specific (remember, these instructions are intended to be a starting point). -For example, if it's maintained in a GitHub repository, you can achieve this by [cloning the repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository). -Once you have the directory on your computer, change (`cd`) into it. +You can achieve this by [cloning the repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository). +Once you have the repository on your computer, change (`cd gut-to-soil-manuscript-figures`) into the local directory. -If you're in a conda environment, deactivate it by running `conda deactivate`. +If you're in an existing conda environment, deactivate it by running `conda deactivate`. Then, run: ```shell -conda env create -n gut-to-soil-manuscript-figures-dev --file ./environments/gut-to-soil-manuscript-figures-qiime2-tiny-2024.5.yml +conda env create -n gts-manuscript-figs-dev --file ./environments/gut-to-soil-manuscript-figures-qiime2-tiny-2024.5.yml ``` After this completes, activate the new environment you created by running: ```shell -conda activate gut-to-soil-manuscript-figures-dev +conda activate gts-manuscript-figs-dev ``` -Finally, run: +After completing the install steps above, confirm that everything is working as expected by running: ```shell -make install +qiime info ``` -## Testing and using the most recent development version of `gut-to-soil-manuscript-figures` +This will provide you with a sanity check for the expected packages within your conda environment. -After completing the install steps above, confirm that everything is working as expected by running: +You should see the following system info: +``` +Python version: 3.9 +QIIME 2 release: 2024.5 +QIIME 2 version: 2024.5.1 +q2cli version: 2024.5.0 +``` -```shell -make test +Additionally, you should see the following list of plugins present: +``` +diversity +diversity-lib +emperor +feature-table +gut-to-soil-manuscript-figures +metadata +types ``` -You should get a report that tests were run, and you should see that all tests passed and none failed. -It's usually ok if some warnings are reported. +If all of the above matches what you're seeing locally, you're ready to use this plugin! -If all of the tests pass, you're ready to use the plugin. -Start by making QIIME 2's command line interface aware of `gut-to-soil-manuscript-figures` by running: +You should be able to review the help text by running: ```shell -qiime dev refresh-cache +qiime gut-to-soil-manuscript-figures pcoa-2d --help ``` -You should then see the plugin in the list of available plugins if you run: +Here's an example workflow, based on what was used to generate the PCoA figures in Jeff Meilander's manuscript. -```shell -qiime info +Your first step will be filtering the distance matrix you'd like to use for the PCoA plot so that it only contains the sample types of interest. +``` +qiime diversity filter-distance-matrix \ +--i-distance-matrix unweighted-unifrac-distance-matrix.qza \ +--m-metadata-file final-analysis-metadata.tsv \ +--p-where "[SampleType2] IN ('EMP-Soils', 'Food-Compost', 'Self Sample', 'Compost Post-Roll', 'Bulking Material')" \ +--o-filtered-distance-matrix filtered-unweighted-unifrac-distance-matrix.qza ``` -You should be able to review the help text by running: +Next, you'll turn this distance matrix into a two-dimensional PCoAResults object, which will be used as input for the pcoa plot. +``` +qiime diversity pcoa \ +--i-distance-matrix filtered-unweighted-unifrac-distance-matrix.qza \ +--p-number-of-dimensions 2 \ +--o-pcoa filtered-unweighted-unifrac-2d-pcoa.qza +``` -```shell -qiime gut-to-soil-manuscript-figures --help +Now we're ready to generate a pcoa plot! +``` +qiime gut-to-soil-manuscript-figures pcoa-2d \ +--i-ordination filtered-unweighted-unifrac-2d-pcoa.qza \ +--m-metadata-file final-analysis-metadata.tsv \ +--p-measure 'Unweighted Unifrac' \ +--p-average \ +--p-export-legend \ +--p-highlighted-buckets '3, 4' \ +--o-visualization buckets34-pcoa.qzv ``` -Have fun! 😎 +Note that all of the above filenames were used as an example. +Please replace the inputs with your specific distance matrix and metadata files! ## About diff --git a/gut_to_soil_manuscript_figures/plugin_setup.py b/gut_to_soil_manuscript_figures/plugin_setup.py index 50fdf8f..d6657fd 100644 --- a/gut_to_soil_manuscript_figures/plugin_setup.py +++ b/gut_to_soil_manuscript_figures/plugin_setup.py @@ -39,8 +39,42 @@ 'export_legend': Bool, 'highlighted_buckets': Str }, - input_descriptions={}, - parameter_descriptions={}, + input_descriptions={ + 'ordination': 'The two-dimensional `PCoAResults` object that should be' + ' used to generate the plot.' + }, + parameter_descriptions={ + 'metadata': 'The Metadata associated with the `PCoAResults` input.', + 'measure': 'The measure that the `PCoAResults` input was generated' + ' from. Used for plot title and labeling.', + 'average': 'Whether to plot the weekly average for all buckets at each' + ' timepoint.', + 'week_annotations': 'Whether to include numeric labels for each' + ' week timepoint for any highlighted bucket(s).', + 'invert_x': 'Whether to invert the x-axis (based on PCoA axis 1' + ' values). It is recommended to generate the plot once' + ' with both axis inversions disabled to examine the' + ' default orientation (to determine if this is needed).', + 'invert_y': 'Whether to invert the y-axis (based on PCoA axis 2' + ' values). It is recommended to generate the plot once' + ' with both axis inversions disabled to examine the' + ' default orientation (to determine if this is needed).', + 'swap_axes': 'Whether to swap the x&y axes.' + ' It is recommended to generate the plot once' + ' with this parameter disabled to examine the' + ' default orientation (to determine if this is needed).', + 'himalaya': 'Whether to include data from' + ' the external himalaya study.', + 'pit_toilet': 'Whether to include data from' + ' the external pit toilet study.', + 'export_legend': 'Whether to hide the legend in the plot and' + ' export it as a separate `.png` file within the' + ' `data` directory. If disabled, the legend will be' + ' present in the plot.', + 'highlighted_buckets': 'The bucket(s) that should be highlighted in' + ' the plot. If including multiple buckets,' + ' please use the following format: "2, 3, 4".' + }, name='', description=('') )