Skip to content

Commit

Permalink
adds param descriptions and README
Browse files Browse the repository at this point in the history
  • Loading branch information
@lizgehret
lizgehret committed Oct 7, 2024
1 parent 9d14bcc commit b8b8108
Show file tree
Hide file tree
Showing 2 changed files with 90 additions and 32 deletions.
84 changes: 54 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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

Expand Down
38 changes: 36 additions & 2 deletions gut_to_soil_manuscript_figures/plugin_setup.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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=('')
)

0 comments on commit b8b8108

Please sign in to comment.