Visualizing mass spec data with anvi'o

Jessika Fuessel

Email Twitter Github ORCiD

This is a tutorial to explain how the anvi’o interactive interface can be used to visualize FT-ICR-MS data that relies upon a real-world dataset. Some parts of the tutorial will be very specific to the dataset investigated for the particular reserach qeustion here, but once the input data is ready in an anvi’o compatible form, it will be much easeir for anyone to recognize how their data could also fit into that form.

This tutorial is tailored for anvi’o v8 but will probably work for later versions as well (perhaps with minor command modifications). You can learn the version of your installation by running anvi-interactive -v in your terminal.

Introduction to the Project and Original Data

As part of a recent project with Sinikka Lennartz and Carina Bunse, I was interested in investigating how microbial interactions influence the composition of dissolved organic matter (DOM).

To do this, we selected four bacterial isolates originating from the same North Sea water sample and grew them in a full factorial setup. We grew isolates in every possible combination, ranging from individual strains all by themselves to two-, three-, and one four-member consortia, as shown here:

Full factorial setup of four bacterial isolates, all belonging to the Roseobacter clade. We are using the identifiers given to them by Sarah Hahnke, who originally isolated these strains—which is why they are called SH :)

We knew that each of these strains grew well in minimal artificial seawater medium, and for our experiment, we provided glucose as the source of carbon and energy. The central idea was to survey the fate of compounds produced by pure cultures in the presence of other bacteria.

Using solid-phase extraction with PPL cartridges, we isolated dissolved organic matter from each culture at approximately mid-exponential phase. Some may refer to this microbially produced DOM as the “exometabolome”, though this term is debated, as many of the compounds we observed do not appear to be associated with microbial metabolism (at least as far as we can currently tell). We also generated medium and cartridge blanks and then measured all samples on the FT-ICR-MS. All measurements took place in the Marine Geochemistry Group at the University of Oldenburg.

The FT-ICR-MS provides highly resolved mass measurements that enable us to assign molecular formulas to each mass with high accuracy. That said, unlike the more common LC-MS/MS measurements, FT-ICR-MS data are one-dimensional. This means we obtain very accurate mass values, but no structural information, and therefore cannot assign precise molecular identities. We used the in-house developed software ICBM-OCEAN to assign molecular formulas to each mass, following a set of predefined rules, which you can learn more about here.

This is what the final output looks like:

There is a lot of information here (as this table scrolls to the right quite a bit), and we need to extract the data that we would like to work with.

Our primary interest was to understand what the molecular diversity of DOM produced by the different bacterial cultures and consortia looks like, and whether—based on the distribution across samples—we can draw conclusions about microbial interactions mediated by individual molecular formulas. The usual visualization strategies, such as van Krevelen plots, were going to be too busy to discern the fate of individual molecular formulas. I thought that using anvi’o for this could be a good solution, since the anvi’o interactive interface is quite talented.

But as I mentioned at the beginning, I needed to take this dataset and project speicific data, and turn this into anvi’o-compatible data. Which is not so difficult, but if you have similar problems, you should feel free to reach out to the anvi’o community on to get help or advice. For my own dataset I used a combination of Microsoft EXCEL and R-based solutions to do a few things:

• I removed all features that were present in the medium blanks to ensure I was only looking at compounds produced during the experiment, and I only considered features that occurred in all replicates.

• I was interested in seeing the distribution of formulas across different microbial consortia, thus I disregarded intensities and focused only on the presence or absence of molecular formulas.

• I identified molecular formulas that were produced, remained unchanged, or were consumed, based on their binary presence-absence data.

• Finally, I generated a tabular file (which you will see below0 using specific sample names that would enable me to use anvi’o to visualize and modify it.

The primary data for anvi’o analysis and visualization

This is how my final dataset looked like:

This is the primary form of data that goes into the anvi’o interactive interface, and the only input file format you need to kickstart the entire visualization workflow.

You can obtain the entirety of this file, which I will be using in the following sections, from here. In fact, if you wish to follow this exercise step by step on an anvi’o installed computer, you can do it as it is fully reproducible. All you need to do is to open a terminal and run the following commands to set the stage for the tutorial:

# create a directory for the exercise files
mkdir ~/visualizing-mass-spec-data

# go into the directory
cd ~/visualizing-mass-spec-data

# download the data.txt, items-additional-data.txt, and layers-additional-data.txt
curl -L http://anvio.org/files/visualizing-mass-spec-data/data.txt.gz -o data.txt.gz
curl -L http://anvio.org/files/visualizing-mass-spec-data/files/visualizing-mass-spec-data/items-additional-data.txt.gz -o items-additional-data.txt.gz
curl -L http://anvio.org/files/visualizing-mass-spec-data/files/visualizing-mass-spec-data/layers-additional-data.txt.gz -o layers-additional-data.txt.gz

# uncompress everything
gzip -d *.gz

Visualizing molecular formula across microbial consortia

To organize the molecular formulas based on their distribution patterns across samples, we need to generate a clustering dendrogram, which is exactly what the anvi’o program anvi-matrix-to-newick does. Running this program on our data.txt file as shown below:

anvi-matrix-to-newick data.txt \
                      -o dendrogram.newick

generates the file dendrogram.newick in the working directory. This new file is a Newick-formatted tree that groups together formulas that distribute similarly across samples.

Now we have everything we need in our working directory (data.txt and dendrogram.newick) to visualize these data using anvi-interactive.

But things get just a little bit confusing due to reasons related to anvi’o’s history. There is nothing for you to worry about, as you can simply copy-paste the commands below and everything will work. Still, let me break down the reasons behind the few commands that follow. In a typical scenario, the program anvi-interactive visualizes projects that have their own profile-db and contigs-db files. These are anvi’o artifacts generated by other anvi’o programs such as anvi-gen-contigs-database or anvi-profile, which take FASTA and BAM files as input.

Well, we have none of those input files, but we still want to use the program anvi-interactive. Anvi’o has a way to make that happen, but it requires some cryptic steps to get there—such as generating a ‘blank’ profile and using the --manual-mode flag to run the anvi’o interactive interface in an ad hoc manner using our own tabular input files instead of standard output files generated by anvi’o itself.

Long story short: when we run anvi-interactive for the first time with the --manual-mode flag, it will generate an empty profile-db file for us. This newly generated file will help us store the visual state of the interactive interface so that our color choices and other customizations are not lost. You will see that in the sections below.

Now, when we run anvi-interactive the following way,

anvi-interactive -d data.txt \
                 -t dendrogram.newick \
                 -p profile.db \
                 --manual-mode

it will start a new browser window, and when you click the ‘Draw’ button at the bottom-left corner of the display, you will see something that looks like this:

That looks a bit messy, but we will tame it step by step, and add additional data layers to enrich it with useful information.

First of all, you can change the display from “Circle Phylogram” to “Phylogram” to make it more digestible. You can find that option in the settings panel:

Don’t forget to click the ‘Draw’ button again after every change.

Then, find the ‘Options’ tab in the settings panel:

and increase the width of the dendrogram (which will scale the x-axis of the figure) to an appropriate value. I used 8000, but you will likely need to adjust this based on your dataset.

When you hit Draw again, you will see this display:

Slightly better.

The names of each sample (as we described in the input data file) appear on the left side of each row, and the dendrogram that captures clusters of molecular formulas across these samples (which we generated using the program anvi-matrix-to-newick) appears on top. Each molecular formula is represented by a vertical line within each sample. Because there are so many, they sometimes look like a solid block rather than individual formulas.

As you can already see, the pure culture samples appear several times—this is because we wanted to make it easier to compare the fate of each of those formulas within the microbial consortia. For that purpose, we added consecutive numbers to the sample IDs (i.e., SH4_1, SH4_2, etc.); otherwise, anvi’o would have complained that the input data file contained the same column name multiple times.

This is just the first visualization of the data, but there is more work to be done to make it actually useful and visually appealing—starting with adding additional data layers to enrich the display.

Adding additional data layers for ‘items’ (molecular formula)

This visualization of our data shows that the fate of a molecular formula produced by a given bacterial culture was variable across the different consortia. This differential distribution of molecular formulas across all consortia indicates different kinds and varying degrees of microbial interactions. The figure already conveys a lot of information, but it would be helpful to add additional data layers. In this case, we wanted to show a selection of attributes for each molecular formula (or item). The item-specific data included the mass, the H/C and O/C ratios, double bond equivalents (DBE), and the modified aromaticity index. These data need to be displayed for each molecular formula and therefore must be added as an additional data layer below (or above).

First of all, we need to go back to our terminal, where we can store further information in our profile.db. To make sure that the next time I open anvi-interactive, the display looks the same and doesn’t revert to the default circular phylogram, we need to save the current state of the display. To do this, under the main menu, choose the “Save” option under “State”. anvi-interactive will open a pop-up window like the one below, where we can store the current settings under the “default” state, which will be automatically loaded the next time we run anvi-interactive. Alternatively, you can give the state a different name and use the “Load” option later when needed.

For now, I will close the anvi-interactive tab and return to my terminal, where I press CTRL+C to terminate the runnig server (so we can get our command prompt back).

To add further for our items information, we use the program anvi-import-misc-data, which allows us to add all kinds of additional data to a given profile.db. In this case, we will use the parameter --target-table with the value items to tell anvi’o that these data are associated with each item, representing each molecular formula in our dataset. This is an example input data file for the items additional data:

Essentially it should be a TAB-delmited file where the left-most column should match exactly with the item identifiers in our “molecular formula distribution spreadsheet”, so that anvi’o can associate the information across both tables.

If you are following this tutorial with the example datasets I provided at the beginning, you already have the items-additional-data.txt file in your work directory, and you can import it into the profile.db using the program anvi-import-misc-data with this command:

anvi-import-misc-data items-additional-data.txt \
                      -p profile.db \
                      --target-table items

And use the same command as before to start anvi-interactive, this time including the new data:

anvi-interactive -d data.txt \
                 -t dendrogram.newick \
                 -p profile.db \
                 --manual

And this is what our figure looks like now:

At the bottom, we now have five additional layers of information for each molecular formula. At least in this specific case, no clear pattern becomes apparent. This is probably because we clustered the molecular formulas based on their distribution across samples and not their specific fate (production, consumption, preservation), which might reveal clearer patterns. Maybe we can use this information in another analysis :)

For now, we decided to remove these layers from the display again. To do that, we can simply set the height of each layer to 0 under the “DISPLAY” menu, which is the easy way :)

You can also remove any data layer you no longer wish to see in the interface using the program anvi-delete-misc-data. But I chose the lazy option, and after hitting “DRAW”, I was left with the same display I started with.

While additional item data wasn’t useful for this particular analysis, other analyses may benefit from this kind of additional information, so I decided to explain how to add it nevertheless.

Adding additional data layers for ‘layers’ (samples)

We haven’t run out of interesting data to show yet, though. However, the kind of data we want to include in the display now is not specifically associated with each molecular formula, but with each sample. For example: the observed molecular formula count, the predicted molecular formula count, the relative fraction of consumed, produced, and unchanged molecular formulas, and the relative abundances of the different bacterial isolates within each of the consortia.

To do this, we first need to generate a spreadsheet where the first column contains the sample identifier. The sample identifier must be identical to the sample identifier in our original dataset so that anvi’o can correctly match the information. The following columns can contain any data we wish to add, with each column’s first row containing a data identifier. For example, our first data column contains MF_Count_Total, which represents the overall molecular formula count in each sample.

Again, if you are following this tutorial with the example datasets I provided at the beginning, you already have the layers-additional-data.txt file in your work directory, and it looks like this:

To add data as stacked bars (such as relative abundances based on 16S rRNA gene amplicon data) we need to let anvi’o know our intention by naming the corresponding columns and values in a particular way. You can find more information about the formatting here. But I will seimply use a prefix, stacked_bar, followed by a mandatory ! character, followed by a specific sample identifier. For example, in this case, the first column that contains stacked bar data is called stacked_bar_2!SH22, and the next column would be stacked_bar_2!SH24. This way, anvi’o knows that these columns belong together.

We again use anvi-import-misc-data, but this time we use the flag --target-table layers to indicate that this information is sample-specific and should be matched to each sample.

Before we proceed, we need to save the current state and terminate the server using CTRL+C. Then, we can add the data using the following command:

anvi-import-misc-data layers-additional-data.txt \
                      -p profile.db \
                      --target-table layers

And run anvi-interactive again to see its effect:

anvi-interactive -d data.txt \
                 -t dendrogram.newick \
                 -p profile.db \
                 --manual

Now, the additional data are visible and aligned with each sample on the right side of the figure! :)

Fine-tuning the display aesthetics for better structure and clarity

Aside from the annotations—which we will later change outside of anvi-interactive—we can use colors to structure the visualization more clearly. We have 11 different microbial consortia. To discern which data belong to which microbial consortium, I generated a color palette using this tool (which only allows a 10-color palette, so I added another hue manually):

In the main menu of anvi-interactive, under “DISPLAY,” we can manually change the color used for each sample by clicking on the (currently black) square next to “color” and pasting the HEX code for each color into the small window in the lower right:

At some point my display lookedlike this, pretty colorful, and containing all the information:

Then it evolved further with the removal of some layers that didn’t seem to contribute much to the story we wished to tell, changing colors to make it easier for people to follow in a paper format, etc.

Then I exported the display that I was comfortable with, and brought it to Inkscape to continue working with it. Inkscape is an open-source and free SVG editor, but you can edit anvi’o interactive interface exports in any vector graphics editor.

The final figure looks like this:

The figure shows the distribution of molecular formulas that are clustered based on their occurrence across pure cultures and microbial consortia. For each co-culture, rows in black show the molecular formulas produced by the respective bacterial isolate, rows in red show the molecular formulas observed in the respective co-culture and rows in light grey highlight novel and consumed molecular formulas. The dark grey bars on the right side show the molecular formula count for each culture and co-culture along with the predicted molecular formula count in dark blue and the number of preserved, produced and consumed molecular formulas in dark grey. The green stacked bars show the relative abundance of each isolate in the co-cultures, with SH4 in green, SH22 in light blue-green, SH24 in turquoise and SH40 in dark green. The orange stacked bars below show the relative contribution of novel (orange), consumed (peach) and preserved (dark red) molecular formulas in the respective co-cultures.

Conclusion

For our project, we learned a lot from this visualization that helped us interpret the data. Additionally, this figure contains information that we would have usually split across several individual figures, but bringing everything together in one display made it much easier to describe and discuss the observations.

I hope this tutorial gives you some inspiration as well as practical means to visualize your own mass-spec data in anvi’o. If anything was unclear, please feel free to comment below, reach out to me directly, or write to the anvi’o community on Discord. Thanks for reading!

Questions? Concerns? Find us on