Usage modes

A software suite

microbetag is a comprehensive software suite composed of several modules, each tailored to different analytical tasks. It includes:

• a Python library:

which provides functionality for key preprocessing steps and powers the core annotation pipeline; it supports microbetag analyses using local or custom genome sets

• a database (microbetagDB):

containing precomputed annotations for GTDB reference genomes

• 🌐 a web server:

  • enables on-the-fly network annotation by mapping taxonomies from abundance data or network node names to their closest GTDB genomes

  • offers an API for programmatic access to microbetagDB content

• a Cytoscape app (MGG)

offering a user-friendly interface for running microbetag, parsing annotated networks, and performing enrichment analyses directly within Cytoscape

• a pre-process independent module

designed for 16S rRNA amplicon data, which performs taxonomic assignment using a GTDB-specific reference database to prepare the data for optimal downstream microbetag analyses

If you plan to use the on-the-fly version of microbetag, simply follow these steps:

• make sure Cytoscape is installed on your system; if not, download and install it from the Cytoscape Install page

• launch Cytoscape, then visit the MGG Cytoscape Appstore page, then click the Install button to add the MGG app to your Cytoscape environment

To make use of other microbetag modules, follow their corresponding instructions on the Installation page.

Running microbetag..

To use microbetag, you can choose between two main modes depending on your data and analysis goals:

🚀 On-the-fly

This mode runs entirely within the Cytoscape environment via the MGG Cytoscape App.

You begin by loading your data into Cytoscape, then use MGG to submit a microbetag job to the web server. Once submitted:

Taxa in your data are mapped to their closest GTDB representative genomes (if possible). Precomputed information from microbetagDB is used to annotate your network.

Note

If your abundance table contains more than 1000 taxa, providing a corresponding network is required. Also, the use of a fixed taxonomy scheme.

To support large-scale 16S rRNA datasets and ensure compatibility with GTDB (when your taxonomy is not already in Silva or GTDB format), we provide a containerized preparation tool: microbetag_prep. Details on how to use this can be found in the preparation tutorial. microbetag_prep is also available as a Docker image.

💻 Local

In this mode, you use the microbetag Python library directly to annotate your data using your own genome bins or MAGs. This option allows for complete customization and offline execution. See the local usage tutorial for instructions.

To simplify the setup, we provide a containerized version that bundles all dependencies. For further instructions on how to set microbeag locally, have a look at the installation page.

❗ Running microbetag locally can take several hours depending on the number of genomes. For this reason, local execution is required for large-scale datasets.

Note

Once the annotation is complete, you can import and explore the annotated network (.cx2 format) on Cytoscape using the MGG App; just like in the on-the-fly version.

How to

We provide tutorials to help you get started with microbetag, whether you’re using the on-the-fly web-enabled version or running it locally with custom genome sets.

📌 Core Topics (Common to All Modes)

These tutorials introduce key concepts that apply to all usage modes of microbetag:

• Required input files and expected formats

• Mandatory parameters that you may provide either through the MGG parameters panel on the on-the-fly version, or as part of your configuration YAML file for the local case.

• Features in the MGG Cytoscape app for browsing annotated networks

• Performing enrichment analysis on network features

🚀 Using microbetag On-the-Fly

These tutorials guide you through using microbetag directly via Cytoscape and the MGG app, including:

• Firing microbetag with or without a network file as input

• Providing metadata for the network inference

• Using the pre-process module for 16S rRNA data (to enable use of large datasets in on-the-fly mode)

💻 Using microbetag Locally

These tutorials demonstrate how to run microbetag on your own system:

• Filling in the YAML configuration file based on your data and the specific tasks you want microbetag to perform.

• Running the Python-based annotation pipeline with custom genome collections

🧑‍💻 Access programmatically and/or contribute

For coding-familiar users, we also provide instructions about:

• how to use microbetag’s API to get either species specific annotations or potential complementarities for species pairs from microbetagDB

• the code base of microbetag