Using MARTi for taxonomic classification and visualisation of metagenomic data

After extracting the downloaded file, the next step is to set up the configuration file. This file defines how MARTi processes your data and specifies which tools and databases are used.

The simplest way to set up a configuration file is to generate a template by running the following command, and then edit the file to suit your analysis:

marti -writeconfig config.txt

Run this command to create a default configuration file named config.txt in your marti_example/config directory. Now open this file in your favourite text editor so that we can modify the settings according to our mock microbiome data, reference database, and analysis goals.

First, let’s give the analysis run a name. I’m using “mock_microbiome” for this example. Then, set the RawDataDir path to your unzipped marti_example/reads/mock_communities directory. 

Set the SampleDir (Output location for MARTi) to the full path to the new output directory you want MARTi to create in your marti_example/output directory. 

As we have used barcodes, we need to tell MARTi which barcodes to process and we can give each barcode a name. Add this barcode information under where you have set the paths. The top section of your config file should now looks something like this:

RunName:mock_microbiome
RawDataDir:/usr/reads/mock_communities
SampleDir:/usr/output/mock_microbiome
ProcessBarcodes:01,02,03,04
BarcodeId1:mix1_original
BarcodeId2:mix2_bact_prev
BarcodeId3:mix3_bif_lacto
BarcodeId4:mix4_pathogen

Set MaxJobs to 1. This is the maximum number of parallel jobs (e.g. BLAST) MARTi will initiate. 

MARTi requires NCBI taxonomy files, which provide the hierarchical structure of the NCBI taxonomic tree, to assign reads to the correct taxonomic levels and to apply its Lowest Common Ancestor (LCA) algorithm. 

The latest NCBI taxonomy files can be downloaded from the NCBI taxonomy archive. After downloading, extract the archive and provide the path to this directory in your configuration file under the TaxonomyDir setting.

TaxonomyDir:/Path/To/taxdmp_2025-11-01

Remove the BlastProcess section of the configuration and replace it with a Kraken2Process.

Kraken2Process
	Name:pluspf-8
	Database:/Path/To/Databases/kraken2/k2_pluspf_08_GB_20251015/
	options:--confidence 0.01
	UseToClassify

Update the “Database” path to point to your extracted k2 database directory.

After you’ve made all these changes you should have a config file that looks something like this (but with your paths).
 

Tip when using a large database:

When running MARTi with a large database, consider using the “TaxaFilter” parameter in the BlastProcess to exclude certain taxa to minimise wasted computational effort and improve the classification results. For example, the nt database contains entries from the “Other” category (including synthetic constructs, cloning vectors and unclassified environmental sequences). 

If a read aligns both to a genuine taxonomic group and to a sequence within “Other,” then MARTi’s lowest common ancestor (LCA) algorithm will assign the read at the root node of the tree, losing any meaningful classification. 

By excluding these unwanted taxa upfront you reduce noise, improve the specificity of downstream results and make real-time analysis more efficient.

Once your configuration file is ready you can start MARTi. There are two ways to launch a new analysis: from within the MARTi graphical interface (GUI) or directly from the command line.

In this example, we will run MARTi from the command line. This approach is the same one you would use on a high-performance computing (HPC) system or when running MARTi remotely, and it provides more control over job scheduling and resource use.

To start MARTi from the command line, navigate to your MARTi example directory and run:

marti -config config/config.txt

MARTi will begin processing your reads immediately. Progress messages will appear in the terminal as data are analysed. The output directory you defined in your configuration file will be created automatically, containing subdirectories for logs, intermediate files, and final results.

This tutorial has introduced the core steps involved in using MARTi for real-time taxonomic classification and visualisation of metagenomic data. 

We have explored how to install MARTi, prepare a configuration file, and run an analysis from the command line. We have also demonstrated how the MARTi GUI can be used to monitor analyses in real time, inspect individual samples in detail, and compare multiple samples side by side.

Our aim in developing MARTi is to help researchers make the most of real-time nanopore sequencing by providing an accessible, flexible, and open-source framework for metagenomic analysis. 

Real-time insight into community composition can guide experimental decisions, highlight contamination or unexpected organisms, and support faster responses in time-critical settings such as environmental monitoring or pathogen detection.

We hope this walkthrough helps new users gain confidence in setting up and running MARTi with their own data. We plan to build on MARTi’s capabilities by adding additional features, visualisations, and reporting options. 

Feedback, suggestions, and contributions from the community are always welcome.

MARTi was developed with support from the Biotechnology and Biological Sciences Research Council (BBSRC) through the Norwich Research Park Biosciences Doctoral Training Partnership (NRPDTP), Earlham Institute Decoding Biodiversity Institute Strategic Programme, and cross-institute Delivering Sustainable Wheat programme.

• The latest version of the MARTi software is available from Github under the MIT License. 

• Documentation can be found on Read the docs.io. 

• Additionally, an installation-free demo of the MARTi GUI is available at Cyverseuk.

If you have any questions or feedback about the content in this article, please contact: communications@earlham.ac.uk.