Document a few dependencies more clearly in the README, and also work…

… on fixing the build (#555)

* DOC: document xcode / binutils deps

Closes #550 and closes #553.

* DOC: shift shooting thing around, add support info

* DOC: linky link

* DOC: be better

* TST: fix one of the newly-breaking tests

* BLD: Pin iow to 0.1.3

* BLD: equals equals

README.md

@@ -34,6 +34,13 @@ and barplots).
 
 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`.
 
+**If you encounter problems while trying to install Empress**, please check
+out [the "Installation Troubleshooting" section](#installation-troubleshooting)
+further on in this document.
+(And if this information isn't sufficient, please feel free to
+[open an issue](https://github.com/biocore/empress/issues) in this repository or
+post a question on the [QIIME 2 Forum](https://forum.qiime2.org)!)
+
 ### Standalone Version
 
 Empress is available through [PyPI](https://PyPI.org/project/empress/). We recommend installing Empress into an environment (e.g. a [conda](https://docs.conda.io/) environment) using a Python version of at least 3.6.
@@ -149,6 +156,44 @@ qiime empress community-plot \
     --o-visualization community-tree-viz.qzv
 ```
 
+### Installation Troubleshooting
+
+This is not a comprehensive list of problems that can happen during
+installation -- it's just the ones we've seen so far. If you run
+into other problems while installing Empress, please
+let us know so we can add a solution here!
+
+#### Troubleshooting for Windows Subsystem for Linux (WSL) users
+
+**Problem:** Empress' installation process depends on the
+[`binutils`](https://en.wikipedia.org/wiki/GNU_Binutils) package already being
+installed. Although most Unix operating systems come with `binutils` installed
+by default, we've noticed that some Linux distributions / setups (including
+WSL) do not have `binutils` installed.
+
+- **Solution:** if, when installing Empress, you encounter long errors
+that include something
+like `ld: cannot find -lbitarr`,
+try installing `binutils` (e.g. `sudo apt-get install binutils`)
+and then try installing Empress again.
+
+- **More information:** See [this issue](https://github.com/biocore/empress/issues/552).
+
+#### Troubleshooting for macOS users
+
+**Problem:** On macOS systems, we've found that not having
+[Xcode](https://en.wikipedia.org/wiki/Xcode) installed can cause problems with
+Empress' installation process.
+
+- **Solution:** If you are using macOS and you run into an error
+that includes something like
+`command 'x86_64-apple-darwin13.4.0-clang' failed with exit status 1`, try
+installing Xcode (e.g. through the [app
+store](https://apps.apple.com/us/app/xcode/id497799835)) and then try
+installing Empress again.
+
+- **More information:** See [this issue](https://github.com/biocore/empress/issues/549).
+
 ## Tutorial: Using Empress in QIIME 2
 
 In this tutorial, we'll use Empress through QIIME 2 and demonstrate its basic usage with the [Moving Pictures tutorial](https://docs.qiime2.org/2020.8/tutorials/moving-pictures/) dataset. This dataset contains human microbiome samples from
@@ -553,6 +598,13 @@ The commands in this README use the *raw dataset*. The Empire plot command remov
 
 One unique feature that makes Empress useful for exploring time-series data or making exciting presentations is its animation capability, which allows us to stratify and view our data at each time point rather than all at once. To set up the animation sequence, click on the Animation section from the main menu. From the *Gradient* drop-down menu, select `days-since-experiment-start`, the number of unique values in this column will be equal to the number of sequences we see in the final animation. From the *Trajectory* drop-down menu, select `body-site`, this will be the grouping factor by which the branch colors will be set to. Remember that colors on the plot represent branches unique to that group, branches that are shared between groups are not colored. Click on the `Start` button to initiate the animation and minimize the menu to view the full plot. You will begin to see a sequence of plots (automatically changing every few seconds) that represent the data at each time point found in the *days-since-experiment-start* column. At any point you can pause the animation by clicking on the `Pause` button and manually browse through the time points using the `Next Frame`, `Previous Frame`, or `Resume` buttons. Click `Stop` to terminate the animations. --->
 
+#### Further questions?
+
+If you have any questions, comments, concerns, etc. that aren't covered here,
+please feel free to
+[open an issue](https://github.com/biocore/empress/issues) in this repository or
+post a question on the [QIIME 2 Forum](https://forum.qiime2.org)!
+
 ## Publication and Citation
 
 An open-access publication describing Empress is available in _mSystems_

setup.py

@@ -38,8 +38,11 @@
 with open('README.md') as f:
     long_description = f.read()
 
+# NOTE: Pinning iow due to issue described in
+# https://github.com/biocore/improved-octo-waddle/pull/48 and
+# https://github.com/biocore/empress/pull/555
 base = ["numpy", "scipy", "pandas", "click",
-        "jinja2", "scikit-bio", "biom-format", "iow",
+        "jinja2", "scikit-bio", "biom-format", "iow==0.1.3",
         "emperor>=1.0.2"]
 test = ["flake8", "nose"]
 all_deps = base + test

tests/python/test_tools.py

@@ -140,7 +140,11 @@ def test_match_inputs_only_1_feature_in_table(self):
 
     def test_match_inputs_no_tips_in_table(self):
         bad_table = self.table.copy()
-        bad_table.update_ids({i: idx for idx, i in
+        # This swaps the original feature names with 0-based indices, causing a
+        # complete mismatch between tree tips and feature names.
+        # (The 0-based indices are stored as strings, since keeping them as
+        # integers would cause biom to yell at us.)
+        bad_table.update_ids({i: str(idx) for idx, i in
                               enumerate(bad_table.ids(axis='observation'))},
                              axis='observation', inplace=True)
         with self.assertRaisesRegex(