interactive

A DISPLAY-type anvi’o artifact. This artifact is typically generated, used, and/or exported by anvi’o (and not provided by the user)..

🔙 To the main page of anvi’o programs and artifacts.

Provided by

anvi-display-contigs-stats anvi-display-codon-frequencies anvi-display-functions anvi-display-metabolism anvi-display-pan anvi-display-structure anvi-inspect anvi-interactive anvi-script-checkm-tree-to-interactive anvi-script-gen-functions-per-group-stats-output anvi-script-snvs-to-interactive

Required or used by

There are no anvi’o tools that use or require this artifact directly, which means it is most likely an end-product for the user.

Description

This page describes general properties of anvi’o interactive displays and programs that offer anvi’o interactive artifacts.

Terminology

Anvi’o uses a simple terminology to address various aspects of interactive displays it produces. The same terminology applies regardless of which program initiated the interface – whether it is anvi-interactive, anvi-display-pan, or any other display program. Here is a quick-reference table:

Term	Definition
Items	The individual elements displayed in the central tree/dendrogram. Depending on the context, items can be contigs, gene clusters, genes, samples, or any other unit of data. Items are the rows of your data matrix.
Layers	The concentric rings of data that surround the central tree. Each layer represents a different data dimension – for instance, a sample’s coverage, a genome in a pangenome, or a categorical annotation. Layers are the columns of your data matrix.
View	A specific representation of your data. Different views show different aspects of the same dataset (e.g., mean coverage vs. detection in a metagenomic context). Views are stored in the database and can be extended with --additional-view.
Items order	The tree or dendrogram at the center of the display that organizes items. It can be a phylogenetic/phylogenomic tree, a hierarchical clustering dendrogram, or a linear order. Users can provide custom orders through misc-data-items-order.
Layer order	The tree or dendrogram that organizes layers around the display. Users can extend available layer orders through misc-data-layer-orders.
Bins	User-defined selections (groups) of items. You can create bins by clicking on branches of the tree. Bins are central to tasks like genome binning in metagenomics or selecting gene clusters in pangenomics.
Collection	A named set of bins that can be stored in the database and recalled later.
State	A saved configuration of all visual settings – layer order, colors, normalization, drawing type, etc. States are stored in the database and can be exported/imported with anvi-export-state and anvi-import-state.
Additional data	Extra information associated with items or layers that is not part of the core data matrix. Managed with anvi-import-misc-data, anvi-export-misc-data, and anvi-delete-misc-data.

Now let’s see where each of these concepts lives in an actual display.

Items and layers

Items are the units arranged around the center of the display. What they represent depends entirely on the context: contigs in a metagenomic analysis, gene clusters in a pangenome, genomes in a phylogenomic tree, or anything else. Layers are the concentric rings of data surrounding the items tree. Each layer shows a data value for every item, like coverage of a contig in a given sample, or presence/absence of a gene cluster in a given genome.

Together, items and layers form a data matrix: items are the rows, layers are the columns.

Items order and layer order (dendrograms)

The items order is the tree or dendrogram at the center of the display. It determines how items are organized: it can be a phylogenetic tree, a hierarchical clustering dendrogram, or a simple linear order. The layer order is the smaller tree on the outside of the display that organizes layers. Anvi’o computes layer orders automatically, but you can provide your own through misc-data-layer-orders.

Views

A view defines what numerical values are displayed in the layers. For instance, in a metagenomics dataset, the data that can be viewed are mean coverage, detection, or variability; and with pangenome, the options are presence/absence or frequencies of gene clusters. Views are stored in the database and can be switched using the Data dropdown in the settings panel. You can also add custom views with the --additional-view flag.

Bins

Bins are user-defined groups of items. You create them by clicking on branches of the dendrogram. In a metagenomic context, bins typically represent metagenome-assembled genomes (MAGs). In a pangenomic context, they can represent groups of gene clusters (core genome, accessory genome, etc.). Bins are organized into collections that can be stored in the database and used by downstream programs like anvi-summarize.

Additional data for items and layers

Beyond the core view data, you can decorate your display with additional data for both items and layers. Additional data for items appears as extra layers on the outside of the display (e.g., taxonomy assignments, GC content, bin colors). Additional data for layers appears next to the layer order dendrogram (e.g., sample metadata like body site, or genome metadata like species name). These are managed through anvi-import-misc-data.

See this article for a detailed guide on extending anvi’o displays with additional data tables.

Programs that give interactive access

Several anvi’o programs produce an interactive display. The most commonly used ones are:

• anvi-interactive is the main interactive interface. It displays information from a profile-db and contigs-db, and supports manual binning, gene mode, collection mode, and a fully flexible manual mode for visualizing any data.

• anvi-display-pan displays pangenomic data from a pan-db. It shows gene cluster distributions across genomes and supports gene cluster inspection and binning.

• anvi-inspect provides a detailed, nucleotide-level view of a single contig across samples, including coverage, SNVs, and gene calls.

• anvi-display-contigs-stats shows summary statistics for contigs in a contigs-db.

• anvi-display-functions lets you browse the functional pool for a set of genomes or metagenomes.

• anvi-display-metabolism provides an interactive view of metabolism estimation data.

• anvi-display-structure lets you examine protein structures along with SCVs and SAAVs.

And a few others, including anvi-script-snvs-to-interactive.

Artifacts that give interactive access

• contig-inspection shows detailed contig information (coverage, SNVs, gene calls).

• gene-cluster-inspection lets you examine individual gene clusters (alignments, genomic context, functional annotations).

An overview of the display

The interactive interface has two major areas of interaction:

• The space for visualization in the middle area,
• The Settings panel on the left of the screen,

We will spend most of our time in the Settings panel.

Settings panel

If closed, the settings panel can be opened by clicking on the little button on the left-middle part of your browser. When opened, you will see multiple tabs:

But before we start talking about these tabs, it is worthwhile to mention that at the bottom of the settings panel you will find a section with tiny controls that are available in all tabs:

Through these controls you can,

• Create or refresh the display when necessary using the Draw button (or just press D),

• Load or Save the current state of the display using the buttons below the State section,

• Download your display as an SVG file (or just press E),

• Center the display.

💡 Before talking about Tabs, here’s a useful tip: you can conveniently switch between tabs using your keypad. For instance, pressing 1 will navigate you to the Main tab, 2 to the Options tab, and so forth.

For more tips you can check out the Tips + Tricks section at the end of this page.

OK. Let’s talk about each tab you will find in the settings panel.

Main Tab

This is one of the most frequently used tabs in the interface, and there are multiple sections in it (keeps growing over time, so things may be missing here).

• Items subsection

  • Provides high level options for adjusting drawing type, items order and data type.
  • Display part of the interface is where you can adjust individual layer attributes like color, display type, height and min/max values. Click + drag each layer to rearrange how layers are ordered. Or edit attributes for multiple lpngayers as well.

• Layers subsection

  • Change general settings for the tree (i.e., switching between circle or rectangular displays, changing tree radius or width), and layers (i.e., editing layer margins, or activating custom layer margins).
  • Load or save states to store all visual settings, or load a previously saved state.
  • Display usage is same as Items subsection.
  • Change the order of layers using automatically-generated or user-provided orders of layers using the Sample order combo box.
  • Customize individual samples information entries. Changes in this tab can be reflected to the current display without re-drawing the entire tree unless the sample order is changed.

• Legends subsection

  • This subsection enables users to easily change individual or batch legend colors for any of their additional data items.d

Options tab

In the Options tab, just like in the Main tab, we have two sections: Items and Layers, providing a separation for these components.,

• Bins Selection subsection. Allows us to customize the bins.
• Cosmetics subsection. Margin and Background Opacity adjustments on the chart.
• Dendrogram subsection. Radius and Angle , and Edge length normalization adjustments for the dendrogram.
• Branch support subsection. Settings for displaying bootstrap values on the dendrogram.
• Selections subsection. To adjust height, grid and/or shade display, as well as selection name settings.
• Performance subsection. Whether the SVG output is optimized for performance or granularity (very advanced stuff).

• Tree/Dendogram subsection. Height and Edge length normalization adjustments on the Tree.
• Label subsection. Settings for maximum font size on the Layer.

Mastering these in the Options Tab will minimize the post-processing of your anvi’o figures for high-quality and good-looking publication ready images.

Bins tab

Anvi’o allows you to create selections of items shown in the display (whether they are contigs, gene clusters, or any other type of data shown in the display). Bins tab allow you to maintain these selections. Any selection on the tree will be added to active bin in this tab (the state radio button next to a bin defines its activity). Through this tab you can,

• Create or delete bins, set bin names, change the color of a given bin, or sort bins based on their name, the number of units they carry, or completion and contamination estimates (completion / contamination estimates are only computed for genomic or metagenomic analyses).

• View the number of selected units in a given bin, and see the list of names in the selection by clicking the button that shows the number of units described in the bin.

• Store a collection of bins, or load a previously stored collection.

Data tab

The data tab displays the value of items underneath the mouse pointer while the user browse the tree.

Displaying the numerical or categorical value of an item shown on the tree is not an easy task. We originally thought that displaying pop-up windows would solve it, but besides the great overhead, it often became a nuisance while browsing parts of the tree. We could show those pop-up displays only when use clicks on the tree, however click-behavior is much more appropriate to add or remove individual items from a bin, hence, it wasn’t the best solution either. So we came up with the ‘data tab’. You have a better idea? I am not surprised! We would love to try improve your experience: please enter an issue, and let’s discuss.

Search tab

It does what the name suggests. Using this tab you can,

• Build expressions to search items visualized in the main display.

• Highlight matches, and append them to, or remove them from the selected bin in the Bins tab.

News tab

The news panel provides information and external links tracking major Anvi’o releases and development updates.

Notes tab

• The notes tab is a flexible, multipurpose space where users can,
• Store notes, comments, and any other stray items related to their project, in a feature-rich markdown environment.
• Display context, references, reproducibility instructions, and any other salient details for published figures.
• This section moved under Settings panel. Settings > Notes

Interactive interface tips + tricks

Here are some small conveniences that may help the interface serve you better (we are happy to expand these little tricks with your suggestions).

• You can zoom to a section of the display by making a rectangular selection of the area while the pressing the shift button.

• You can click an entire branch to add items into the selected bin, and remove them by right-clicking a branch.

• If you click a branch while pressing the Command or CTRL button, it will create a new bin, and add the content of the selection into that bin.

• Tired of selecting items for binning one by one? right-click on an item and select Mark item as ‘range start’ to set an ‘in point’, then right-click on another item and select Add items in range to active bin or Remove items in range from any bin to manipulate many items with few clicks. Nice!

• By pressing 1,2,3,4,5,6,7 and 8 you can go between Main, Options, Bins, Data, Notes, Search, News and Anvi’o tabs!

Keyboard shortcuts

The interactive interface recognizes a handful of keyboard shortcuts to help speed up your workflow

• The S key toggles the Settings panel
• The D key triggers a redraw of your visualization
• The T key toggles showing the Title panel
• Keys 1 through 8 will toggle between tabs within the Settings panel, granted the Settings panel is currently shown.
• CTRL+Z and CTRL+SHIFT+Z will undo or redo bin actions, respectively.

Edit this file to update this information.