Taxonomic profiling of metagenomes from diverse environments with mOTUs4
Project description
mOTUs profiler
The mOTUs profiler is a computational tool that estimates taxonomic abundance of microbial community members from known and currently unknown (uncultured) species using metagenomic shotgun sequencing data.
The current version of the mOTUs profiler is built on top of the mOTUs database (motus-db) which is constructed from 919K isolate and single cell-amplified (SAGs) genomes and 2.98M metagenome-assembled genomes (MAGs) generated from ~120k metagenomic samples spanning diverse microbiomes, which include (in addition to the human and ocean microbiome) soil, freshwater and gastrointestinal tract microbiomes of ruminants and other animals, environments we found to be greatly underrepresented by reference genomes.
In the current version, 124,295 species-level taxonomic units (mOTUs) were constructed using sequences of 10 single-copy marker genes recovered from these genomes. 30,256 mOTUs are represented by an isolate genome, whereas 94,039 mOTUs are represented by MAGs only.
Please cite the paper(s) corresponding to the version(s) you use:
| Version | Journal | Year | DOI | Citations |
|---|---|---|---|---|
| mOTUs v1 | Nature Methods | 2013 | 10.1038/nmeth.2693 | |
| mOTUs v2 | Nature Communications | 2019 | 10.1038/s41467-019-08844-4 | |
| mOTUs v3 (profiler) | Microbiome | 2022 | 10.1186/s40168-022-01410-z | |
| mOTUs v3 (protocol) | Current Protocols | 2022 | 10.1002/cpz1.218 | |
| mOTUs database (v4) | Nucleic Acids Research | 2025 | 10.1093/nar/gkae1004 |
📦 Installation
The mOTUs profiler, written in Python 3 (>=3.12), can be executed on a 64-bit Linux or macOS system. It requires external dependencies (bwa>=0.7.19, vsearch>=2.30.4) which must be available on PATH.
Package managers automate this: they resolve dependency graphs, manage binary versions, and provide isolated environments so mOTUs and its dependencies don't conflict with system packages. Below are the recommended approaches.
Installation with Pixi (Recommended)
Pixi is a fast, dependency-free package manager. Install mOTUs globally:
pixi global install motus
motus profile -h
Or add to an existing workspace:
pixi workspace channel add conda-forge
pixi workspace channel add bioconda
pixi add motus
pixi run motus profile -h
Installation with Conda
mOTUs is available in bioconda:
# First time: add channels
conda config --add channels defaults
conda config --add channels bioconda
conda config --add channels conda-forge
# Create and activate environment
conda create -n mOTUs4 motus
conda activate mOTUs4
# Verify installation
motus profile -h
🚀 Usage
After installation, you can test whether the tool was installed correctly by executing:
motus --help
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Usage:
motus <command> [options]
Commands:
-- Taxonomic profiling
profile Perform taxonomic profiling (map_tax + calc_mgc + calc_motu) in a single step
map_tax Map reads to the marker gene database
calc_mgc Calculate marker gene cluster (MGC) abundance
calc_motu Summarize MGC abundances into a mOTU profile
-- Tool utilities
downloadMGDB Download the mOTUs marker gene database
merge Merge multiple taxonomic profiling results into one table
classify Classify user genomes into mOTUs
prep_long Prepare long reads to be profiled by mOTUs
-- Genome accession
genomes Search the mOTUs-db by keyword (taxonomic, functional)
download Download sequence files from mOTUs-db
Type motus <command> to print the help menu for a specific command
Commands
The profile function in mOTUs is the main function that executes map_tax, calc_mgc, and calc_motu in sequence. It takes short read metagenomic sequencing data as input and generates a taxonomic profile.
Additionally, the tool includes six helper functions:
merge: Combines multiple taxonomic profiles into a single file.classify: Assigns user-submitted genomes to existing mOTUs.genomes: Finds genomes by functional or taxonomic annotation.prep_long: Finds genomes by functional or taxonomic annotation.download: Provides programmatic access to the ~4 million genomes in themotus-db.downloadMGDB: Downloads the mOTUs marker gene database.
Profile
Produces a taxonomic profile from short read metagenomic sequencing data by executing map_tax, calc_mgc, and calc_motu in succession.
motus profile
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The profile command in mOTUs is the main function that executes map_tax, calc_mgc,
and calc_motu in sequence. It takes short read metagenomic sequencing data as input
and generates a taxonomic profile.
Usage:
motus profile -f FILE [FILE ...] -r FILE [FILE ...] -s FILE [FILE ...] -o FILE [options]
motus profile -f FILE [FILE ...] -r FILE [FILE ...] -o FILE [options]
motus profile -s FILE [FILE ...] -o FILE [options]
Input options:
-f, --forward FILE [FILE ...]
Input file(s) for reads in forward orientation, fastQ/A(.gz)-formatted
-r, --reverse FILE [FILE ...]
Input file(s) for reads in reverse orientation, fastQ/A(.gz)-formatted
-s, --single FILE [FILE ...]
Input file(s) for unpaired reads, fastQ/A(.gz)-formatted
-n, --sample-name STR
Sample name (default: 'unnamed sample')
-db PATH
Alternative path for the mOTUs marker gene database
Output options:
-o, --output-file FILE
Output file name [required]
Algorithm options:
-g, --marker-genes INT
Required number of marker genes for a mOTU to be called present:
1=higher recall, 6=higher precision, 10=maximum (default: 3)
-l, --alignment-length INT
Minimum length of the alignment (bp) (default: 75)
-t, --threads INT
Number of threads (default: 1)
-y, --counting-mode STR
Which scale the abundances are reported in (default: INSERT_SCALED)
Choices: [INSERT_RAW, INSERT_NORM, INSERT_SCALED, BASE_RAW, BASE_NORM]
--skip-pair-check
Skip validation that forward and reverse read headers match.
Use when reads are unsorted or contain singletons.
Map Tax
Maps short reads against the mOTUs marker gene database.
motus map_tax
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The map_tax command takes short read metagenomic sequencing data as input and
maps reads to the mOTUs marker gene database.
Usage:
motus map_tax -f FILE [FILE ...] -r FILE [FILE ...] -s FILE [FILE ...] -o FILE [options]
motus map_tax -f FILE [FILE ...] -r FILE [FILE ...] -o FILE [options]
motus map_tax -s FILE [FILE ...] -o FILE [options]
Input options:
-f, --forward FILE [FILE ...]
Input file(s) for reads in forward orientation, fastQ/A(.gz)-formatted
-r, --reverse FILE [FILE ...]
Input file(s) for reads in reverse orientation, fastQ/A(.gz)-formatted
-s, --single FILE [FILE ...]
Input file(s) for unpaired reads, fastQ/A(.gz)-formatted
-db PATH
Alternative path for the mOTUs marker gene database
Output options:
-o, --output-file FILE
Output file name [required]
Algorithm options:
-l, --alignment-length INT
Minimum length of the alignment (bp) (default: 75)
-t, --threads INT
Number of threads (default: 1)
--skip-pair-check
Skip validation that forward and reverse read headers match.
Use when reads are unsorted or contain singletons.
Calc MGC
Calculates the number of inserts mapping to each marker gene cluster within the mOTUs marker gene database.
motus calc_mgc
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The calc_mgc command takes a file storing the alignments of sequencing reads
to the mOTUs marker gene database and calculates marker gene cluster abundances.
Usage:
motus calc_mgc -i FILE -o FILE [options]
Input options:
-i, --input-file FILE
Path to BAM file generated after running the motus map_tax command [required]
-db PATH
Alternative path for the mOTUs marker gene database
Output options:
-o, --output-file FILE
Output file name [required]
Algorithm options:
-l, --alignment-length INT
Minimum length of the alignment (bp) (default: 75)
Calc mOTU
Calculates the taxonomic profile based on the number of inserts mapped to the corresponding marker gene clusters.
motus calc_motu
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The calc_motu command takes a file containing marker gene cluster
abundances and generates a taxonomic profile.
Usage:
motus calc_motu -i FILE -o FILE [options]
Input options:
-i, --input-file FILE
MGC abundance table generated by the calc_mgc command [required]
-n, --sample-name STR
Sample name (default: 'unnamed sample')
-db PATH
Alternative path for the mOTUs marker gene database
Output options:
-o, --output-file FILE
Output file name [required]
Algorithm options:
-g, --marker-genes INT
Required number of marker genes for a mOTU to be called present:
1=higher recall, 6=higher precision, 10=maximum (default: 3)
-y, --counting-mode STR
Which scale the abundances are reported in (default: INSERT_SCALED)
Choices: [INSERT_RAW, INSERT_NORM, INSERT_SCALED, BASE_RAW, BASE_NORM]
merge
Merges taxonomic profiles from multiple samples into one (tab-separated) table.
motus merge
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The merge command takes multiple profiles produced after running the
profile command and combines them into a single table.
Usage:
motus merge -i FILE [FILE ...] -o FILE
Input options:
-i, --input-files FILE [FILE ...]
A list of mOTUs profile files or a text file containing the list of profile
files to be merged, with one line per file [required]
-db PATH
Alternative path for the mOTUs marker gene database
Output options:
-o, --output-file FILE
Output file name [required]
downloadMGDB
Downloads the marker gene reference database required for profiling.
motus downloadMGDB
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The downloadMGDB command downloads the marker gene reference database used
by the profile and map_tax commands.
Usage:
motus downloadMGDB [options]
Options:
-f, --force
Force download even when database is already present
--toy
Download the lightweight toy database (v4.1-toy) instead of the full database.
Useful for testing and development. Note: the genomes and download commands
are not available with the toy database.
-db PATH
Alternative path for the mOTUs marker gene database
classify
Assigns provided genomes to a mOTU if the corresponding taxon is present within the database.
motus classify
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The classify command takes a list of genome sequence files as input and
assigns these genomes to existing mOTUs in the database.
Requires vsearch to be installed and on PATH.
Usage:
motus classify -i FILE -o FILE [options]
Input options:
-i, --input-file FILE
Text file listing genome sequence files in fastA(.gz) format to classify.
One line per genome file [required]
-db PATH
Alternative path for the mOTUs marker gene database
Output options:
-o, --output-file FILE
Output file name [required]
Algorithm options:
-t, --threads INT
Number of threads (default: 1)
prep_long
Prepares long reads for profiling by splitting them into ~300 bp fragments.
motus prep_long
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The prep_long command takes long-read sequencing data and converts it
into the appropriate input format to be used by the profile and map_tax commands.
Usage:
motus prep_long -i FILE -o FILE [options]
Input options:
-i, --input-file FILE
Long-read sequencing file to convert, can be in fastQ/A(.gz) format [required]
Output options:
-o, --output-file FILE
Output file name. This converted file is ready to be used by motus profile [required]
Algorithm options:
-sl, --splitting-length INT
Target fragment length (in bp) for splitting long reads (default: 300)
-ml, --minimum-length INT
Minimum read length after splitting. Shorter reads are discarded (default: 50)
download
Downloads sequences for indicated genomes from the mOTUs genome database.
motus download
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The download command downloads listed genome files from mOTUs-db.
Usage:
motus download -i FILE -o PATH [options]
motus download -i STR [STR ...] -o PATH [options]
Input options:
-i, --input-genomes FILE/STR
Can be either a list of genome identifiers separated by spaces or a text file
listing the identifiers of genomes for download. One line per genome. The output of
the motus genomes command can be used as input for this command [required]
-db PATH
Alternative path for the mOTUs marker gene database
Output options:
-o, --output-folder PATH
Path to output folder where the downloaded sequences will be saved [required]
-r, --representatives
Download only sequences from representative genomes.
-t, --file-type STR
File type to download (default: genome)
Choices: [genome, gene_fna, gene_faa, gene_gff, antismash, pfam, eggnog, kegg, trna, rrna]
genomes
Queries the mOTUs genome database to find genomes matching indicated mOTU identifiers, taxonomic clades, or functional annotations.
motus genomes
Show options
Program: motus - a tool for marker gene-based OTU (mOTU) profiling
Version: 4.1.0
References:
Profiler: Ruscheweyh, Milanese et al. Cultivation-independent genomes greatly expand
taxonomic-profiling capabilities of mOTUs across various environments. Microbiome (2022).
doi: https://doi.org/10.1186/s40168-022-01410-z
Database: Dmitrijeva, Ruscheweyh et al. The mOTUs online database provides web-accessible
genomic context to taxonomic profiling of microbial communities. Nucleic Acids Research (2025).
doi: https://doi.org/10.1093/nar/gkae1004
Summary:
The genomes command queries the mOTUs-db based on identifiers, functional,
or taxonomic annotations and returns a list of genomes matching indicated query.
Usage:
motus genomes -i FILE -o FILE [options]
motus genomes -i STR [STR ...] -o FILE [options]
motus genomes -l GENOME|TAXONOMY|PFAM|KEGG|EGGNOG -o FILE [options]
Input options:
-i, --input-queries FILE/STR
Can be either a list of search queries or a text file listing search queries
with one line per query. Queries can be genome or mOTUs identifiers, PFAM, KEGG, EGGNOG,
or GTDB taxonomy names. If the query does not exactly match any database entry,
alternative queries will be suggested [required unless -l is used]
-l, --list STR
List all searchable entries for a given category and write them to -o.
Choose from [GENOME, TAXONOMY, PFAM, KEGG, EGGNOG]. When used, -i is not required.
-db PATH
Alternative path for the mOTUs database
Output options:
-o, --output-file FILE
Output file containing a list of genome identifiers matching search queries and their
annotations as indicated by the -d parameter. This output file can be used as input
for the motus download command [required]
-d, --details STR [STR ...]
List of annotations to report. Choose any combination of [KEGG, PFAM, EGGNOG, TAXONOMY],
for example, -d KEGG PFAM.
❓ Need Help?
- Report an issue: GitHub Issues — for bugs, feature requests, or technical questions
- Join the community: Discord — chat with other mOTUs users and developers
📋 Changelog
v4.1.0
Database
- Default marker gene database updated to v4.1. Version v4.0 still supported. Clustering didn't change but ~150k MAGs from underexplored environments were added and associated with existing mOTUs.
- Annotation database (used by
genomes) is now version-matched to the installed marker gene DB; v4.0 and v4.1 annotation DBs are downloaded and stored separately - GTDB taxonomy bumped to R226 from R220
- Toy database added (
downloadMGDB --toy): lightweight database for testing; disablesgenomesanddownloadcommands
classify
- Output columns changed to
GENOME,CLOSEST_MOTU,SIMILARITY,ASSIGNED_TO_MOTU,TAXONOMY,#MGs - Reports one best mOTU per genome with GTDB taxonomy;
ASSIGNED_TO_MOTUisTrueif similarity ≥96.5% - Unclassified genomes reported as
no_mOTU(hits found but all below threshold) orno_mOTU_<6MGs(fewer than 6 marker genes extracted)
CLI
-db PATHflag added to all commands to specify a custom database parent folder--skip-pair-checkadded toprofileandmap_taxfor unsorted inputs or inputs containing singletons. Use as last resort!motus genomes -l GENOME|TAXONOMY|PFAM|KEGG|EGGNOGlists all searchable entries of a given type without requiring-i- Tool checks at startup whether
bwais on PATH (hard error if missing) and whethervsearchis on PATH (warning if missing)
Bug fixes
- Database download: incomplete downloads (content-length mismatch) no longer leave a broken DB with a valid completion marker
merge: blank lines in a profile list file no longer cause a crypticFileNotFoundError- Multimapper resolution: replaced non-deterministic
random.choicewithsorted()[0]for reproducible MG selection within an MGC - Edge correction: fixed inaccurate weight distribution in inverse padding
Algorithm
INSERT_NORMandINSERT_SCALEDcalculation corrected.INSERT_NORMnow reports length normalised insert counts without any scaling factor. Full scaling was moved toINSERT_SCALED.
v4.0.4
- Initial public release of mOTUs4 with database v4.0 (124,295 mOTUs)
- Three-stage pipeline:
map_tax→calc_mgc→calc_motu;profileruns all three in sequence classifycommand: genome-to-mOTU assignment via fetchMGs + vsearchgenomesanddownloadcommands for programmatic access to mOTUs-db genome sequencesmergecommand for combining multiple single-sample profiles into one tableprep_longcommand: splits long reads into ~300 bp fragments for profiling- Read name normalisation:
/1//2suffixes stripped and re-appended as BAM qname tags to track orientation through the pipeline
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file motus_tool-4.1.0.tar.gz.
File metadata
- Download URL: motus_tool-4.1.0.tar.gz
- Upload date:
- Size: 92.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1607bc6a2cdd7bf7c119fcea9120133b6f196e5f8ac1fbf4bc36ba60ebd8ccb7
|
|
| MD5 |
5ed348179df7581dc07e6fdabaf284a0
|
|
| BLAKE2b-256 |
b5f3fa654286c57f5b7bf726fed96d16a375229272c4591fb2f4e00874e72310
|
File details
Details for the file motus_tool-4.1.0-py3-none-any.whl.
File metadata
- Download URL: motus_tool-4.1.0-py3-none-any.whl
- Upload date:
- Size: 91.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e29efe6fb0ed65b6dde2fc899a496593a6a492f69acb73ac9a8de865de96b94b
|
|
| MD5 |
3e59666f06af07149e71418eb3172737
|
|
| BLAKE2b-256 |
6734c73956b180eaafeb4e4f4b032bf64439313daa9364ca41076bd72d9f4364
|