Empress

New features
- Add optional "abbreviated" parameters for EMPress' standalone CLI (481)
- Add more detailed options for choosing when to show node circles; the new default is showing circles just for internal nodes with exactly one child (486, 527)
- Add a new color map, `Green-LightOrange-Purple` (483)
- Add the ability to dynamically shear the tree based on feature metadata (490, 492, 505)
- Adjust the way taxonomy feature metadata is handled so that more specific levels of the taxonomy (e.g. `c__Bacilli`) include all ancestral levels of the taxonomy (e.g. `k__Bacteria; p__Firmicutes; c__Bacilli`) (487)
- This makes it easier to distinguish general metadata values like `g__`, and matches the behavior in [q2-taxa](https://github.com/qiime2/q2-taxa/)'s taxonomy barplots.
- Automatically adjust the main legend's size when changing tree coloring (512)
- Limit the speed of zooming slightly to make navigation easier on certain computers (516)
- Use the excellent [toastr](https://codeseven.github.io/toastr/) library to support showing multiple (now color-coded by error, warning, etc.!) toast messages at once (#519)

Documentation
- Fix some broken image links in the README when viewed on PyPI (478)
- Add citation for EMPress' [recent publication](https://msystems.asm.org/content/6/2/e01216-20) in _mSystems_ (#493, 494)
- Add important details to standalone EMPress installation instructions (495)
- Adjust the levels of headers used in the README (507)
- Update screenshots and README text (535)

Bug fixes
- Fix an error that was thrown when creating an EMPire plot using a biplot ordination without providing feature metadata (485)
- Fix a bug that occurred when running EMPress outside of QIIME 2 (495)
- Fix a bug that was thrown when running `tree-plot` with the `--shear-to-feature-metadata` parameter but without passing feature metadata (525)

Performance improvements
- Speed up tree coloring (505)
- Cache parent nodes to speed up various functionality (505)

Development improvements
- Add a new GitHub Actions workflow for specifically testing running EMPress outside of QIIME 2 (499)
- Various updates to the GitHub Actions workflows (498, 502, 523)
- Simplify iteration over the tree in the code (492)

:palm_tree: :scissors: :oncoming_taxi: :bread: :beetle: :books:


Acknowledgements

This work is supported by IBM Research AI through the AI Horizons Network. For more information, visit the [IBM AI Horizons Network website](https://www.research.ibm.com/artificial-intelligence/horizons-network/).

New features
- Add a standalone command-line interface (CLI) for EMPress ([425](https://github.com/biocore/empress/issues/425), [#449](https://github.com/biocore/empress/pull/449))
- The visualizations generated from this interface are stored as directories containing the HTML/JS/CSS code needed for a visualization.
- This interface makes it possible to easily use EMPress without installing QIIME 2, if desired!
- Add an option that adjusts the distance between the farthest tip of the tree and the start of the first barplot layer ([453](https://github.com/biocore/empress/issues/453), [#464](https://github.com/biocore/empress/pull/464))
- Warn the user when a branch length method does not actually adjust the branch lengths in the tree, approximately ([447](https://github.com/biocore/empress/issues/447), [#456](https://github.com/biocore/empress/pull/456))
- This is a common use case when, for example, the tree is already ultrametric: in this case, the "Make ultrametric" option will not do anything, and warning the user will help explain why nothing has changed.

Documentation
- Update installation documentation to reflect the simpler instructions for installing EMPeror ([455](https://github.com/biocore/empress/pull/455))
- Add a "short description" field for the tool's setup file ([458](https://github.com/biocore/empress/pull/458))

Performance improvements
- Speed up the way node names are processed when starting an EMPress visualization ([462](https://github.com/biocore/empress/issues/462), [#466](https://github.com/biocore/empress/pull/466))

Development improvements
- Transition from using Travis-CI to GitHub Actions ([465](https://github.com/biocore/empress/pull/465), [#468](https://github.com/biocore/empress/pull/468))
- Expose some of the internal code used for creating an EMPress visualization in Python ([470](https://github.com/biocore/empress/issues/470), [#472](https://github.com/biocore/empress/pull/472))

:evergreen_tree: :desktop_computer: :straight_ruler: :warning: :octopus: :rabbit:

Acknowledgements

This work is supported by IBM Research AI through the AI Horizons Network. For more information, visit the [IBM AI Horizons Network website](https://www.research.ibm.com/artificial-intelligence/horizons-network/).

- Update Emperor dependency to `emperor>=1.0.2`.
- Make Empress pip-installable 🎉 (407).
- Disable browser autocomplete in node search menu (445).

:medal_sports: :tanabata_tree: :princess:

New features
- Show legends for barplots, and improve legend formatting. ([299](https://github.com/biocore/empress/issues/299))
- Support drawing barplots in the circular layout. ([297](https://github.com/biocore/empress/issues/297))
- Support ignoring branch lengths during layout. ([271](https://github.com/biocore/empress/issues/271))
- Color root nodes of collapsed clades. ([321](https://github.com/biocore/empress/issues/321))
- In Empire plots: add the ability to double-click on a sample coloring category in Emperor (e.g. `body site`) and color the tree based on the samples in that category. ([370](https://github.com/biocore/empress/pull/370))
- In Empire plots: added the ability to show synchronized animations between Emperor and Empress. ([319](https://github.com/biocore/empress/pull/319))
- When node circles are drawn, they are now drawn for all nodes, regardless of if the node in question has a name given or not. ([348](https://github.com/biocore/empress/issues/348))
- Add basic PNG export functionality. ([330](https://github.com/biocore/empress/issues/330))
- Improve SVG export functionality: support exporting barplots, collapsed clades, all shown legends, etc. ([384](https://github.com/biocore/empress/pull/384), [#392](https://github.com/biocore/empress/pull/392), [#303](https://github.com/biocore/empress/issues/303))
- Add support for drawing borders around each layer of barplots. ([350](https://github.com/biocore/empress/issues/350))
- Add the ability to create visualizations without having a table or sample metadata; this splits `qiime empress plot` into two commands, `qiime empress community-plot` and `qiime empress tree-plot`. ([175](https://github.com/biocore/empress/issues/175))
- Add the ability to use iTOL-style "leaf sorting" in Empress' rectangular and circular layouts, and make this the default. ([170](https://github.com/biocore/empress/issues/170))
- Add a "Tree Statistics" tab to the side panel showing various stats about the tree. ([179](https://github.com/biocore/empress/issues/179))
- Support double-clicking on collapsed clades to uncollapse them. ([406](https://github.com/biocore/empress/pull/406))
- Support reversing color maps. ([418](https://github.com/biocore/empress/issues/418), [#423](https://github.com/biocore/empress/pull/423))
- Support shearing a tree to feature metadata (currently only available for `tree-plot`). ([419](https://github.com/biocore/empress/issues/419))
- Support drawing the tree as ultrametric. ([444](https://github.com/biocore/empress/pull/444))

Documentation
- Document challenges with merging metadata in QIIME 2. ([393](https://github.com/biocore/empress/issues/393))
- Document that Emperor will be re-installed by Empress. ([401](https://github.com/biocore/empress/issues/401))

Bug fixes
- Fix a bug in which length scaling would cause certain types of bars to not show up in barplots. ([309](https://github.com/biocore/empress/pull/309))
- Hide "feature metadata" barplot controls when no feature metadata is available in the visualization. ([316](https://github.com/biocore/empress/issues/316))
- Fix legend formatting -- ensure all category colors are drawn as equal-dimension boxes. ([331](https://github.com/biocore/empress/issues/331))
- Fix a small bug where it was possible for barplot layers' UIs to collide. ([340](https://github.com/biocore/empress/pull/340))
- In Empire plots: Fix timing in Emperor box-selections, allowing multiple repeated selections without strange behavior. ([197](https://github.com/biocore/empress/issues/197))
- Vary the number of lines used to approximate arcs drawn in the circular layout, based on the angle traveled by the arc. Reduces the amount of lines drawn and also makes particularly long arcs look smoother. ([372](https://github.com/biocore/empress/issues/372))
- Fix exported SVG images being flipped upside-down relative to the Empress interface. ([334](https://github.com/biocore/empress/issues/334))
- Fix a small bug in how gradients are drawn. ([421](https://github.com/biocore/empress/issues/421))
- Ignore root lengths, if available, in the unrooted layout. ([374](https://github.com/biocore/empress/issues/374))
- Fix a bug with a dependency's code files not being installed with Empress. ([402](https://github.com/biocore/empress/issues/402), [#399](https://github.com/biocore/empress/issues/399))
- Don't collapse clades that contain just a single tip. ([315](https://github.com/biocore/empress/issues/315))
- Fix a bug where in certain browsers and cases Emperor and Empress' CSS would slightly overlap. ([356](https://github.com/biocore/empress/issues/356))
- Fix bug where single-tip trees would not be visible in the circular layout. ([429](https://github.com/biocore/empress/issues/429))
- Fix problems when clicking on nodes not present in the feature table (due to the tree not being sheared). ([314](https://github.com/biocore/empress/issues/314))
- Hide the `Add` button, etc. after all sample metadata columns have been summarized in the node selection menu. ([272](https://github.com/biocore/empress/issues/272))

Performance improvements
- Use the BIOM table object throughout Empress' Python codebase, and speed up usage of it. ([317](https://github.com/biocore/empress/issues/317), [#328](https://github.com/biocore/empress/pull/328))
- Speed up sample metadata barplot computation. ([298](https://github.com/biocore/empress/issues/298))
- Speed up taxonomy string processing for feature metadata. ([326](https://github.com/biocore/empress/pull/326))
- Compute tree layouts on-the-fly in JavaScript, rather than in Python. Reduces the size of visualizations, and enables many new features that involve laying out the tree dynamically. ([345](https://github.com/biocore/empress/pull/345))
- Uses a balanced parentheses representation of the tree throughout Empress' Python codebase in place of the `skbio.TreeNode` object. ([360](https://github.com/biocore/empress/pull/360), [#155](https://github.com/biocore/empress/issues/155))
- Don't automatically draw barplots when clicking the `Draw barplots?` checkbox, which can be a very slow operation if the default way of drawing barplots would be inefficient (e.g. sample metadata barplots for a quantitative field). ([343](https://github.com/biocore/empress/issues/343))
- By default, don't draw node circles. ([349](https://github.com/biocore/empress/issues/349))
- Compress the way colors are passed to WebGL, saving memory. ([400](https://github.com/biocore/empress/pull/400))
- Improve node searching for large trees -- only show at most 10 results at a time, use binary search, etc. ([364](https://github.com/biocore/empress/issues/364), [#433](https://github.com/biocore/empress/pull/433))

Development enhancements
- Improve the way Empress/Emperor integration is set up internally. ([383](https://github.com/biocore/empress/pull/383))
- Removed the `pep8` testing requirement. ([397](https://github.com/biocore/empress/issues/397))

Miscellaneous
- Rename some options in the command-line interface. ([312](https://github.com/biocore/empress/issues/312))
- Shifted around some controls within the side panel so that things are in more intuitive locations. ([379](https://github.com/biocore/empress/issues/379))
- In Empire plots: highlight the samples containing a node by enlarging them, rather than by highlighting them. ([373](https://github.com/biocore/empress/issues/373))
- The default tree color is now a darker shade of gray/black.
- Adjust default barplot layer thickness. ([442](https://github.com/biocore/empress/pull/442))
- Don't show duplicate names in node searching. ([433](https://github.com/biocore/empress/pull/433))
- Show "Unnamed node" as the name for unnamed nodes in the node selection menu.
- Various other improvements to Empress' CLI, UI, and documentation. It's been a while since the last release!

:medal_sports: :tanabata_tree: :princess:


Acknowledgements

This work is supported by IBM Research AI through the AI Horizons Network. For more information visit the [IBM AI Horizons Network website](https://www.research.ibm.com/artificial-intelligence/horizons-network/).

New features
- Enhance Empress / Emperor integration: now, clicking on a biplot arrow in Emperor reveals the corresponding node in the tree in Empress. In addition, this highlights the samples in the Emperor plot where this feature is found.
- Add the ability to collapse clades of the tree based on sample / feature metadata coloring. For the rectangular and circular layouts two algorithms are supported ("symmetric" and "asymmetric"). For the unrooted layout only the asymmetric mode is supported. Users can select their algorithm of choice in the "Tree Properties" tab.


- Add an option to export the styled tree as an SVG file. This option can be found under the "Export" tab.
- Add the ability to draw barplots that align with the tips of the tree (currently only supported for the rectangular layout). This feature allows users to visualize sample and feature metadata as tip-level annotations.


- Improve line-width setting to be dependent on the number of leaves of the tree being displayed. The input is now relabeled to correctly reflect that this is "added" width as opposed to a scaling factor.
- Add two new settings to ignore absent tips when propagating sample metadata coloring, and to prevent the camera to refocus when a node is selected (via Emperor the search bar). These options can be found in the "Tree Properties" tab.

Documentation
- Improve installation documentation, and setup requirements to install latest [Emperor](https://github.com/biocore/emperor) development version.
- Add a comprehensive tutorial that demonstrates many of the features available in Empress.
- Rebrand integrated Empress+Emperor plots as *Empire plots*.

Bug fixes
- Fix bug that would allow users to enter negative line-widths. All numeric inputs are now validated consistently.
- Various bug fixes

Performance improvements
- Stored tree data in a more efficient way in the visualization (258).

Development enhancements
- Create a utility script for front-end development, `tests/python/make-dev-page.py`. This script creates a standalone HTML document that can be used to update and modify the JS libraries without having to rebuild the page (257).
- Add support to preview built artifacts based on open pull requests. Links to the Q2-View URLs are posted in a comment by emperor-helper.
- Refactored various parts of the code to support direct testing (187).
- Add more comprehensive tests, applied consistent styling for tests, and updated to the latest version of QUnit.
- Miscellaneous code and development documentation improvements.

Miscellaneous
- Previously, sample metadata groups with no unique tips were removed from the legend shown during sample metadata coloring, and were not assigned colors from a color map. To make sample metadata barplots use consistent colors as the sample metadata coloring functionality, these groups are now assigned colors and preserved in the legend.

:deciduous_tree: :bar_chart: :boom:

Acknowledgements

This work is supported by IBM Research AI through the AI Horizons Network. For more information visit the [IBM AI Horizons Network website](https://www.research.ibm.com/artificial-intelligence/horizons-network/).

- Add a `--p-filter-extra-samples` parameter for use with tandem plots that removes samples present in the table but not in the ordination
- Added information to the README about selecting tables for use with tandem plots, and the various tradeoffs of this choice
- Enhance Empress / Emperor integration: now, clicking on a tip node in Empress in a tandem plot highlights samples in Emperor containing the corresponding feature (or, for an internal node, clicking on the node highlights samples that contain at least one of the descendant tips)
- Fix styling issues:
- Add scrollbars when the side panel gets taller than the screen, or when node names get longer than the menu box
- Clean up the tandem plot interface: remove the scrollbar on the side of the screen and add a clear dividing vertical line
- Add a maximum width to certain selection elements
- Add a new "Tree Properties" tab in the side panel with:
- The ability to re-center the camera
- The ability to toggle node circles on and off
- Replace references to "node ID" with "node name", to be consistent with Newick file / scikit-bio conventions
- Alert user if no unique features can be colored (239)
- Position node selection menus more intuitively
- Various performance / storage improvements:
- Encode data for the balanced parentheses structure in a more efficient manner (228)
- Compress feature table and sample / feature metadata information to take up less space in the visualization
- Add more comprehensive tests
- Various bug fixes
- Miscellaneous code improvements


:princess: :penguin: :athletic_shoe: :deciduous_tree:

Acknowledgements

This work is supported by IBM Research AI through the AI Horizons Network. For more information visit the [IBM AI Horizons Network website](https://www.research.ibm.com/artificial-intelligence/horizons-network/).