Add optional abbreviated parameters for the standalone CLI; add some more context to the README

README.md

@@ -24,7 +24,7 @@ and barplots).
 
 # Installation & Basic Usage
 
-Empress is available as either a standalone program or a QIIME 2 plugin. The standalone version will generate a folder with HTML/JS/CSS files necessary to view the plot while the QIIME 2 version will generate a `.qzv` Visualization that can be viewed on [https://view.qiime2.org/](https://view.qiime2.org/) or by using `qiime tools view`.
+Empress is available as either a standalone program or a QIIME 2 plugin. The standalone version will generate a folder with the HTML/JS/CSS files necessary to view the plot while the QIIME 2 version will generate a `.qzv` Visualization that can be viewed on [https://view.qiime2.org/](https://view.qiime2.org/) or by using `qiime tools view`.
 
 ## Standalone Version
 
@@ -52,25 +52,44 @@ The standalone version of Empress takes the following filetypes as inputs. (Note
 
 ### Example standalone usage
 
-```
+#### `empress tree-plot`
+
+```bash
+# Option 1: Using "long" parameter names
 empress tree-plot \
     --tree tree.nwk \
-    --feature-metadata feature_metadata.tsv \
-    --output-dir tree_viz
-```
+    --feature-metadata feature-metadata.tsv \
+    --output-dir tree-viz
 
+# Option 2: Using "short" parameter names
+empress tree-plot -t tree.nwk -fm feature-metadata.tsv -o tree-viz
 ```
+
+#### `empress community-plot`
+
+```bash
+# Option 1: Using "long" parameter names
 empress community-plot \
     --tree tree.nwk \
     --table feature-table.biom \
-    --sample-metadata sample_metadata.tsv \
-    --feature-metadata feature_metadata.tsv \
+    --sample-metadata sample-metadata.tsv \
+    --feature-metadata feature-metadata.tsv \
     --pcoa ordination.txt \
     --filter-extra-samples \
-    --output-dir community_tree_viz
+    --output-dir community-tree-viz
+
+# Option 2: Using "short" parameter names
+empress community-plot \
+    -t tree.nwk \
+    -tbl feature-table.biom \
+    -sm sample-metadata.tsv \
+    -fm feature-metadata.tsv \
+    -p ordination.txt \
+    --filter-extra-samples \
+    -o community-tree-viz
 ```
 
-You can view the details of the command line arguments with `empress tree-plot --help` and `empress community-plot --help`. Note that the path provided to `--output-dir` must not exist as it will be created by Empress upon successful execution of the command. It is also worth noting that the standalone version of the Empress commands does not support providing multiple sample/feature metadata files. If you have, for example, multiple feature metadata files, you should combine them all into one file that you pass to Empress.
+You can view the details of the command line arguments with `empress tree-plot --help` and `empress community-plot --help`. Note that the path provided to `-o`/`--output-dir` must not exist, as it will be created by Empress upon successful execution of the command. It is also worth noting that the standalone version of the Empress commands does not support providing multiple sample/feature metadata files. If you have, for example, multiple feature metadata files, you should combine them all into one file that you pass to Empress.
 
 The output will be a directory containing an `empress.html` file and a `support_files` directory containing the JS/CSS files required to view the plot in your browser. If you provided a PCoA to the `community-plot` command there will also be an `emperor-resources` subdirectory containing the files required to view the Emperor plot alongside the tree. You can view the `empress.html` file in any modern browser to interact with it the same way you would the QIIME 2 Visualization.
 
@@ -95,22 +114,26 @@ qiime empress --help
 
 ### Example QIIME 2 usage
 
-```
+#### `qiime empress tree-plot`
+
+```bash
 qiime empress tree-plot \
     --i-tree tree.qza \
     --m-feature-metadata-file taxonomy.qza \
-    --o-visualization tree_viz.qzv
+    --o-visualization tree-viz.qzv
 ```
 
-```
+#### `qiime empress community-plot`
+
+```bash
 qiime empress community-plot \
     --i-tree tree.qza \
     --i-feature-table feature-table.qza \
-    --m-sample-metadata-file sample_metadata.tsv \
+    --m-sample-metadata-file sample-metadata.tsv \
     --m-feature-metadata-file taxonomy.qza \
     --i-pcoa ordination.qza \
     --p-filter-extra-samples \
-    --o-visualization community_tree_viz.qzv
+    --o-visualization community-tree-viz.qzv
 ```
 
 # Tutorial: Using Empress in QIIME 2

empress/scripts/_cli.py

@@ -15,11 +15,16 @@ def empress():
     """Generates an interactive visualization of a phylogenetic tree."""
     pass
 
+# Allow using -h to show help information
+# https://click.palletsprojects.com/en/7.x/documentation/#help-parameter-customization
+CTXSETS = {"help_option_names": ["-h", "--help"]}
 
-@empress.command("tree-plot", short_help=desc.TREE_PLOT_DESC)
-@click.option("--tree", required=True, help=desc.TREE_DESC)
-@click.option("--output-dir", required=True, help=desc.OUTPUT_DIR)
-@click.option("--feature-metadata", required=False, default=None,
+@empress.command(
+    "tree-plot", short_help=desc.TREE_PLOT_DESC, context_settings=CTXSETS
+)
+@click.option("-t", "--tree", required=True, help=desc.TREE_DESC)
+@click.option("-o", "--output-dir", required=True, help=desc.OUTPUT_DIR)
+@click.option("-fm", "--feature-metadata", required=False, default=None,
               help=desc.FM_DESC)
 @click.option("--shear-to-feature-metadata", required=False, default=False,
               help=desc.SHEAR_TO_FM, is_flag=True)
@@ -41,13 +46,15 @@ def tree_plot(
     save_viz(viz, output_dir, q2=False)
 
 
-@empress.command("community-plot", short_help=desc.COMM_PLOT_DESC)
-@click.option("--tree", required=True, help=desc.TREE_DESC)
-@click.option("--table", required=True, help=desc.TBL)
-@click.option("--sample-metadata", required=True, help=desc.SM_DESC)
-@click.option("--output-dir", required=True, help=desc.OUTPUT_DIR)
-@click.option("--pcoa", required=False, default=None, help=desc.PCOA)
-@click.option("--feature-metadata", required=False, default=None,
+@empress.command(
+    "community-plot", short_help=desc.COMM_PLOT_DESC, context_settings=CTXSETS
+)
+@click.option("-t", "--tree", required=True, help=desc.TREE_DESC)
+@click.option("-tbl", "--table", required=True, help=desc.TBL)
+@click.option("-sm", "--sample-metadata", required=True, help=desc.SM_DESC)
+@click.option("-o", "--output-dir", required=True, help=desc.OUTPUT_DIR)
+@click.option("-p", "--pcoa", required=False, default=None, help=desc.PCOA)
+@click.option("-fm", "--feature-metadata", required=False, default=None,
               help=desc.FM_DESC)
 @click.option("--ignore-missing-samples", required=False, default=False,
               help=desc.IGNORE_MISS_SAMP, is_flag=True)

tests/python/test_cli.py

@@ -115,3 +115,12 @@ def test_existing_directory(cls):
         assert str(value) == "Output directory already exists!"
         assert not os.path.isdir(f"{output_dir}/support_files")
         assert "empress.html" not in os.listdir(output_dir)
+
+    def test_tree_plot_basic_cli_abbrev(cls):
+        output_dir = "tree_plot_basic_cli_abbrev"
+        result = cls.runner.invoke(
+            empress,
+            ["tree-plot", "-t", cls.tree_loc, "-o", output_dir]
+        )
+        assert result.exit_code == 0
+        files_present(output_dir)