DEV: Add make-dev-page.py

.gitignore

@@ -147,3 +147,6 @@ create-plt.bash
 *.swp
 *.swo
 *~
+
+# ignore dev tree file
+development-page.html

.travis.yml

@@ -25,3 +25,8 @@ script:
   - qiime dev refresh-cache
   - make test
   - make stylecheck
+  # check the development script works in the 3 possible modes (no inputs, tree
+  # plot inputs, and tandem plot inputs)
+  - ./tests/python/make-dev-page.py
+  - ./tests/python/make-dev-page.py docs/moving-pictures/rooted-tree.qza docs/moving-pictures/table.qza docs/moving-pictures/sample_metadata.tsv docs/moving-pictures/taxonomy.qza
+  - ./tests/python/make-dev-page.py docs/moving-pictures/rooted-tree.qza docs/moving-pictures/table.qza docs/moving-pictures/sample_metadata.tsv docs/moving-pictures/taxonomy.qza docs/moving-pictures/unweighted_unifrac_pcoa_results.qza --filter-extra-samples

CONTRIBUTING.md

@@ -30,6 +30,23 @@ make test
 If you just want to run the Python or JavaScript tests, you can run
 `make pytest` or `make jstest` respectively.
 
+## Front-end development
+
+For convenience, a utility script `./tests/python/make-dev-page.py` is bundled
+in the test suite. This script works best if you install the package in
+"editable mode" i.e. by running `pip install -e .` from the base directory.
+
+After installing the package, the script can be run without any arguments. This
+will load the moving pictures dataset and create a page
+`development-page.html`. Using this page developers can modify CSS and JS files
+and simply reload the page on the browser to see their changes take effect.
+Alternatively, you can set the input data for development using the various
+options and arguments in the script. For a full list of options and arguments,
+you can run `./tests/python/make-dev-page.py --help`.
+
+Note, modifications to the Python code, or the template code require that you
+re-generate `development-page.html`.
+
 ## Linting and style-checking
 
 Empress' python code is linted/style-checked using `flake8`.

setup.py

@@ -34,7 +34,7 @@
 with open('README.md') as f:
     long_description = f.read()
 
-base = ["numpy", "scipy", "pandas",
+base = ["numpy", "scipy", "pandas", "click",
         "jinja2", "scikit-bio", "biom-format", "iow", "emperor"]
 test = ["pep8", "flake8", "nose"]
 all_deps = base + test

tests/python/make-dev-page.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+
+import click
+import pandas as pd
+import qiime2 as q2
+import pkg_resources
+
+from test_integration import load_mp_data
+
+from bp import parse_newick
+from empress.core import Empress
+from emperor.util import get_emperor_support_files_dir
+from skbio import OrdinationResults
+from q2_types.tree import NewickFormat
+
+ARG_TYPE = click.Path(exists=True, dir_okay=False, file_okay=True)
+
+
+@click.command()
+@click.argument('tree', required=False, type=ARG_TYPE)
+@click.argument('table', required=False, type=ARG_TYPE)
+@click.argument('sample_metadata', required=False, type=ARG_TYPE)
+@click.argument('feature_metadata', required=False, type=ARG_TYPE)
+@click.argument('ordination', required=False, type=ARG_TYPE)
+@click.option('--ignore-missing-samples', is_flag=True)
+@click.option('--filter-extra-samples', is_flag=True)
+@click.option('--filter-missing-features', is_flag=True)
+@click.option('--filter-unobserved-features-from-phylogeny', is_flag=True)
+def main(tree, table, sample_metadata, feature_metadata, ordination,
+         ignore_missing_samples, filter_extra_samples, filter_missing_features,
+         filter_unobserved_features_from_phylogeny):
+    """Generate a development plot
+
+    If no arguments are provided the moving pictures dataset will be loaded,
+    and a tandem plot will be generated. Alternatively, the user can input a
+    new dataset.
+    """
+
+    # by default load the moving pictures data (tandem plot)
+    if tree is None or table is None or sample_metadata is None:
+        tree, table, sample_metadata, feature_metadata, ordination = \
+                load_mp_data()
+        filter_extra_samples = True
+    # otherwise require a tree, table and sample meadata
+    elif (tree is not None and table is not None
+          and sample_metadata is not None):
+        tree = q2.Artifact.load(tree)
+        table = q2.Artifact.load(table)
+        sample_metadata = q2.Metadata.load(sample_metadata)
+
+        if feature_metadata is not None:
+            feature_metadata = q2.Artifact.load(
+                    feature_metadata).view(q2.Metadata)
+
+        if ordination is not None:
+            ordination = q2.Artifact.load(ordination)
+    else:
+        raise ValueError('Tree, table and sample metadata are required!')
+
+    with open(str(tree.view(NewickFormat))) as f:
+        tree = parse_newick(f.readline())
+
+    table = table.view(pd.DataFrame)
+    sample_metadata = sample_metadata.to_dataframe()
+    feature_metadata = feature_metadata.to_dataframe()
+
+    if ordination is not None:
+        ordination = ordination.view(OrdinationResults)
+
+    # These two lines fetch the JS files for both apps directly from the
+    # installation directory - this makes testing/developing easier
+    empress_resources = pkg_resources.resource_filename('empress',
+                                                        'support_files')
+    emperor_resources = get_emperor_support_files_dir()
+
+    # this variable is too long for PEP8
+    unobserved = filter_unobserved_features_from_phylogeny
+    viz = Empress(table=table, tree=tree, ordination=ordination,
+                  feature_metadata=feature_metadata,
+                  sample_metadata=sample_metadata,
+                  resource_path=empress_resources,
+                  ignore_missing_samples=ignore_missing_samples,
+                  filter_extra_samples=filter_extra_samples,
+                  filter_missing_features=filter_missing_features,
+                  filter_unobserved_features_from_phylogeny=unobserved)
+
+    if ordination is not None:
+        viz._emperor.base_url = emperor_resources
+
+    with open('development-page.html', 'w') as f:
+        f.write(viz.make_empress())
+
+
+if __name__ == '__main__':
+    main()