NOSE

NOSE — NOvel SpEcies Identification Pipeline

An automated, end-to-end Snakemake pipeline for novel microbial species identification and characterization from genomic assemblies, integrating fragmented manual workflows into a single, reproducible six-module pipeline.

What NOSE does

  • Polyphasic novelty assessment — computes ANI (Average Nucleotide Identity), AAI (Average Amino Acid Identity), and POCP (Percentage of Conserved Proteins) against programmatically retrieved, validly published reference type strains, rather than relying on a single marker gene like 16S rRNA.
  • Six-module Snakemake pipeline
    • M1 – Quality & Identity Check: Genome quality assessment and taxonomic identification.
    • M2 – Novelty Screening: ANI , AAI , POCP, and 16S analysis against reference type strains.
    • M3 – Evolutionary Placement: Phylogenomic tree construction and evolutionary analysis.
    • M4 – Metagenomic Mapping: Detects the prevalence and distribution of genomes across metagenomic datasets.
    • M5 – Functional Profiling: Biosynthetic gene clusters, antimicrobial resistance genes, mobile genetic elements, and functional annotation.
    • M6 – Metabolic Modeling: Genome-scale metabolic model reconstruction and pathway analysis.
  • Browser-based GUI — a local browser-based interface (nose-ui) for uploading genome assemblies, configuring module parameters, monitoring real-time logs, and running the pipeline with ease.

NOSE - Novel species boundary

A genome pair is generally considered the novel species when whole-genome ANI is below ~95%. NOSE flags genomes below that boundary as potential novel species (M1 & M2) and carries them forward into phylogenomic and functional validation (M3 to M6).

100 95 90 85 ANI (%) 0 50 100 Alignment fraction (%) Same species (ANI ≥ 95%) Different species Novel candidate
Example ANI comparison. Genomes with ANI values ≥95% are classified as known reference species, whereas those with ANI values <95% are identified as potential novel species candidates.
Installation →

Installation

NOSE is distributed as a Python package on PyPI and installed with pip. Each of its six modules runs in its own isolated Conda environment, deployed automatically by Snakemake at runtime — so you need a working Conda/Mamba installation on your system even though NOSE itself is a pip package.

System requirements

  • Python 3.9
  • A Conda distribution (Miniconda, Anaconda, or Micromamba) — required so Snakemake can build each module's environment with --use-conda
  • git, for cloning the repository (optional, if not installing from PyPI)

Note

Miniconda is the setup verified to work reliably on our lab HPC/server environment. If you hit solver or dependency conflicts with full Anaconda, switch to Miniconda.

Step 1 — Install Python (If Needed)

Every command on this page is typed into a terminal window, one line at a time: that's Command Prompt or PowerShell on Windows (search for either in the Start menu), Terminal on macOS (Cmd+Space, then type "Terminal"), or your Linux distribution's terminal application.

Linux — most distributions already ship Python. Check first, and only install it if this fails:

$ python3 --version
$ sudo apt update && sudo apt install python3 python3-pip

macOS — download the installer from python.org/downloads and run it, or install via Homebrew:

$ brew install python

Windows — download the installer from python.org/downloads, run it, and check "Add python.exe to PATH" on the first screen before clicking Install.

Verify it worked in a new terminal window:

$ python3 --version

Note

This system Python is only needed to run the Conda installer in Step 2. NOSE itself always runs inside a dedicated Conda environment (created in Step 3 with Python 3.9) — you won't develop against this Python directly, and if you already have Conda installed, you can skip this step entirely since Conda bundles its own.

Step 2 — Install a Conda distribution

Select your platform, then a Conda distribution.

Verified working setup on our Linux HPC/server environment. Recommended if you have run into solver or dependency conflicts with full Anaconda.

# download and install Miniconda
$ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
$ bash Miniconda3-latest-Linux-x86_64.sh
$ source ~/.bashrc

On a shared server, pin to the exact version we've verified against NOSE instead of "latest" (which changes over time and can shift behavior underneath you):

# pinned version verified on our lab server (Python 3.10)
$ curl -O https://repo.anaconda.com/miniconda/Miniconda3-py310_23.5.2-0-Linux-x86_64.sh
$ bash Miniconda3-py310_23.5.2-0-Linux-x86_64.sh
$ source ~/.bashrc
# download and install Anaconda
$ wget https://repo.anaconda.com/archive/Anaconda3-latest-Linux-x86_64.sh
$ bash Anaconda3-latest-Linux-x86_64.sh
$ source ~/.bashrc

Warning

On some Linux HPC / shared-server setups, Anaconda's default channel priority or bundled package versions have caused solver conflicts when Snakemake builds NOSE's per-module environments. If that happens, switch to the Miniconda instructions above.

# install micromamba
$ "${SHELL}" <(curl -L micro.mamba.pm/install.sh)
$ source ~/.bashrc

Micromamba is a good option when you want conda-style environments without the overhead of a full Anaconda/Miniconda install — useful for constrained or containerized environments.

# Apple Silicon (M1/M2/M3)
$ curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
$ bash Miniconda3-latest-MacOSX-arm64.sh

# Intel Mac
$ curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
$ bash Miniconda3-latest-MacOSX-x86_64.sh

$ source ~/.zshrc

Download the Anaconda macOS installer (.pkg) from anaconda.com/download and run it.

$ brew install micromamba

Note

NOSE's module dependencies (Snakemake, FastANI, and the rest of the per-module bioinformatics tools) are Linux/macOS-first and are not reliably installable natively on Windows. We recommend using WSL (see the WSL tab) rather than native Windows for running NOSE.

  1. Download the Miniconda installer for Windows from docs.conda.io/en/latest/miniconda.html.
  2. Run the .exe installer, keeping the default options.
  3. Open Anaconda Prompt from the Start menu for the pip install step below.
  1. Download the Anaconda installer from anaconda.com/download and run it.
  2. Open Anaconda Prompt for the pip install step below.

WSL gives you a real Linux environment on Windows, which is what NOSE's module dependencies expect. This is the recommended path for Windows users.

  1. Open PowerShell as Administrator and run wsl --install, then restart when prompted. This installs Ubuntu by default — no need to pick a distribution.
  2. After restart, an Ubuntu terminal window opens automatically the first time (search "Ubuntu" in the Start menu after that). Follow the Linux → Miniconda instructions above inside it — the commands are identical inside WSL.
# inside the WSL Ubuntu terminal
$ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
$ bash Miniconda3-latest-Linux-x86_64.sh
$ source ~/.bashrc

Step 3 — Install NOSE via pip

# create and activate a Python 3.9 environment
$ conda create -n nose python=3.9
$ conda activate nose

# Install NOSE from PyPI
$ pip install nose-pipeline

Step 4 — Configure environments & download reference databases

These commands are the CLI entry points exposed by the pip install:

# configure the per-module runtime conda environments
$ nose-setup

# bulk-download and index required reference databases
$ nose-db

Step 5 — Get an NCBI API key

Every module resolves organism names from GCA/GCF accessions via the NCBI Entrez API. A free API key raises the request rate limit and avoids throttling on large batches.

  1. Sign in (or create a free account) at ncbi.nlm.nih.gov/account.
  2. Open Account Settings → API Key Management and click Create an API Key.
  3. Copy the generated key.

Enter your NCBI email and API key once in the dashboard's Credentials section (or directly in nose_config.yaml) — it's picked up by all six modules automatically.

Note

The email is required; the API key is optional but strongly recommended — without it, NCBI limits requests to 3/second instead of 10/second, which slows down organism-name lookups on large batches.

Install from source

$ git clone https://github.com/RamanLab/NOSE.git
$ cd NOSE
$ pip install -e .

Verify the installation

$ nose-info

Displays localized installation details and version control logs. If the command isn't found, confirm the environment you installed into is activated, and that its bin directory is on your PATH.

← OverviewUsage & Tutorials →

Usage & Tutorials

NOSE exposes four command-line entry points. Most day-to-day use goes through the browser GUI; the others handle setup and database management.

Command-line entry points

CommandWhat it does
nose-uiLaunches the browser-based GUI locally at http://localhost:5050
nose-setupConfigures the per-module runtime Conda environments
nose-dbBulk-downloads and indexes required reference databases
nose-infoDisplays localized installation details and version control logs

Launching the browser UI

$ nose-ui

Opens a local interface at http://localhost:5050 for uploading a genome assembly and steering each module's runtime parameters through per-module configuration panels. The frontend is plain HTML5/CSS3/vanilla JavaScript with no external framework, and pipeline logs stream to the browser in real time via Server-Sent Events.

How a run flows

A single FASTA upload is passed through all six modules in sequence via a master dispatch script, which chains Snakemake sub-workflows together with custom Python/Bash post-processing. Every module reads its parameters from one centralized config.yaml, and each module's output is parsed into a standardized CSV/TSV that feeds directly into the next module.

Reading the output

Module 2 is the key novelty checkpoint: genomes with whole-genome ANI below 95% against the closest validly published reference are flagged as potential novel species and carried forward into phylogenomics, functional characterization, and metabolic modeling.

Note

Step-by-step tutorials (example dataset, interpreting edge cases near the species boundary, customizing the reference genus lookup) will be added here.

← InstallationPipeline Details →

Pipeline Details

NOSE is a Snakemake-based, six-module pipeline for detecting, classifying, and characterizing novel microbial species directly from genomic assemblies. Modules run sequentially, each in its own Conda environment, orchestrated by a master dispatch script around a centralized config.yaml.

Pipeline architecture

Data flow through all six modules — every tool, intermediate file, and hand-off between stages.

Genomic Assemblies (FASTA) 📄 MODULE 1 - Quality Control & Classification QUAST CheckM2 QC (Prokaryotic) GTDB-tk Classify (Prokaryotic) prok_taxonomy.csv QUAST EukCC QC (Eukaryotic) CAT Classify (Eukaryotic) euk_taxonomy.csv HQ Filter genome_summary.csv unqualified_genome_summary.csv MODULE 2 - Genome Relatedness Indices (OGRI) Barrnap BLASTn NCBI 16S DB 16S Identification (nearest genus) download_genomes.sh NCBI Datasets Reference Retrieval reference_genomes FastANI Prokka aai.rb pocp.sh Genomic Distance Calculation compile_results_WGS.py Results Compilation compiled_results.csv prepare_tree_inputs.py Novel Candidate Staging potential_novel.csv auto_hmm_outgroup.py GTDB API NCBI Entrez HMM & Outgroup Resolution genome_summary_for_tree.csv (HMM set, Outgroup GCF, and citations — all resolved per genus, no manual prep) MODULE 3 - Phylogenomic Validation NCBI Datasets Genome Grouping & Outgroup DL GToTree SCG Extraction & Alignment GToTree Tree IQ-TREE Tree Inference (ML, 1000 UFBoot) IQ-TREE Tree (ML) tree_annotation.py NCBI Entrez iTOL Annotation File Generation iTOL Annotation Files (user uploads tree + annotation files to iTOL manually) MODULE 4 - Metagenome Mapping Metagenome Reads sylph merge_results.py Unconstrained boundary tests at±1000 mmol·gDW⁻¹·h⁻¹ Sketch DB + Profiling final_report.csv MODULE 6 - Metabolic Reconstruction CarveMe GEM Reconstruction Draft GEMs (SBML) generate_model_stats.py MEMOTE compile_model_summary.py Validation & Benchmarking GEMs (SBML) model_summary.csv MODULE 5 - Functional Characterization Prokka Structural Annotation COGclassifier cog_merge.py Functional Core (COG) COG Table antiSMASH MIBiG parserfile.py Secondary Metabolism (BGC) BGC Table geNomad genomad_merge.py Mobile Genetic Elements Viral / Plasmid Table ABRICATE CARD VFDB BacMet2 NCBI Resistance & Virulence AMR / VF Table Legend Input data Tool Script Database Module / Step Output file Intermediate Sequential flow NOSE - Novel Species Identification: Pipeline Architecture HQ filter: Completeness ≥ 90%,Contamination ≤ 5%,axonomy resolved to genus level Novel-species screen: WGS ANI < 95%,AAI ≥ 50 reciprocal hits (20% identity),POCP ≥ 40% identity, 50% coverage, E < 1×10⁻⁵ IQTree : Maximum-Likelihood tree,1000 ultrafast bootstrap replicates Containment threshold c = 100 ,Minimum sequence required 5target k-mers per profile Screening cutoffs: ≥ 80% identity,≥ 80% query coverage (CARD · VFDB · BacMet2 · NCBI) .fasta
View full-size diagram (opens in a new tab) ↗
Figure 2. Full pipeline architecture — inputs, tools, and intermediate files for each module, in the order they run.
Module 1 Genome quality control & classification

Computes assembly metrics and taxonomic lineage for prokaryotic or eukaryotic input. Prokaryotes: QUAST for assembly stats, CheckM2 for completeness/contamination, GTDB-Tk (classify_wf) for taxonomy. Eukaryotes: QUAST, EukCC for completeness/redundancy, CAT (via MetaEuk-predicted proteins) against NCBI taxonomy. A unified High-Quality (HQ) filter — completeness ≥ 90%, contamination ≤ 5%, taxonomic resolution to at least Genus — gates what proceeds downstream; eukaryotic assemblies stop here and aren't propagated further.

QUASTCheckM2GTDB-TkEukCCCATMetaEuk
Module 2 Genome-relatedness indices (OGRI)

Determines taxonomic position and genomic distance against validly published type strains, dynamically retrieved by genus. Computes three relatedness metrics in parallel — ANI (FastANI), AAI (aai.rb over Prokka-predicted proteomes), and POCP (Qin et al. 2014 method) — plus an optional 16S route via Barrnap + BLASTn. Genomes with WGS ANI < 95% are flagged as potential novel species and isolated for downstream phylogenomic validation.

FastANIaai.rbPOCPBarrnapBLASTnProkka
Module 3 Phylogenetic tree construction

Places genomes flagged as novel in Module 2 within their taxonomic context. Query genomes are partitioned into genus-specific clusters; conserved single-copy genes are extracted via genus-specific HMMs, and Maximum-Likelihood trees are inferred with bootstrap support. Outputs are formatted for interactive visualization.

GToTreeIQ-TREEiTOL
Module 4 Metagenomic Mapping Optional

Quantifies prevalence and relative abundance of novel species across user-provided metagenomic datasets using k-mer-based containment estimation — fast, and without the computational cost of read alignment. Produces a standardized master abundance table across samples.

Optional

Only runs if you provide raw metagenomic reads to screen against your novel genomes. If you don't have any, skip this module — the rest of the pipeline doesn't depend on it.

sylph
Module 5 Functional characterization

Multi-modal profiling of genomic features, metabolic potential, resistance mechanisms, and mobile genetic elements: structural annotation and COG classification, secondary metabolite / biosynthetic gene cluster detection, prophage and plasmid identification, and antibiotic/biocide/metal resistance screening against curated databases. Results compile into summary tables for visualization.

ProkkaCOGclassifierantiSMASHgeNomadABRICATE
Module 6 Genome-scale metabolic model reconstruction Optional

Reconstructs a genome-scale metabolic model for each novel species via a top-down template approach, exported in standardized SBML/FBC format. Network topology and biomass connectivity are validated under unconstrained growth tests, and model quality is benchmarked for stoichiometric consistency.

Optional — requires your own CPLEX license

The default solver is IBM ILOG CPLEX, which needs a license you provide yourself — a free student/academic license works. If you don't have one, skip this module; it doesn't block anything else in the pipeline.

Getting CPLEX (student/academic license)

  1. Create an IBMid using your university/academic email address.
  2. Go to the IBM Academic Initiative downloads page and sign in.
  3. Select IBM ILOG CPLEX Optimization Studio.
  4. Search for "CPLEX 22.1.1" specifically — NOSE is verified against this version, not the older ones most generic install guides walk through.
  5. Choose the HTTP download option, then check the box for the installer matching your OS (e.g. "...CPLEX Optimization Studio V22.1.1 for Linux x86-64").
  6. Accept the license agreement — the Download button only appears once you do.
  7. Click Download. The installer file (e.g. cplex_studio2211.linux-x86-64.bin) starts downloading.

Linux / macOS — make the installer executable and run it as superuser, accepting the default install path unless you have a reason to change it:

$ chmod +x cplex_studio2211.linux-x86-64.bin
$ sudo ./cplex_studio2211.linux-x86-64.bin

Windows — run the downloaded .exe installer as Administrator, keeping the default install path.

NOSE only needs the Python bindings

Unlike tools built against CPLEX's MATLAB bindings, NOSE calls CPLEX through its Python API. Once installed, that lives under the install directory at cplex/python/<python-version>/<platform> — for example:

/opt/ibm/ILOG/CPLEX_Studio2211/cplex/python/3.9/x86-64_linux

Copy that path into module6.cplex_lib_path in nose_config.yaml, or the CPLEX Library Path field on Module 6's Config tab (or the Full Pipeline Run page, under M6 settings). No environment variables or .bashrc edits needed — NOSE reads the path directly from config.

CarveMeCOBRApyMEMOTE

Configuration & thresholds

ModuleKey threshold
1 — Quality controlCompleteness ≥ 90%, contamination ≤ 5%, taxonomy resolved to ≥ Genus
2 — RelatednessNovel candidate: WGS ANI < 95%; AAI ≥ 50 reciprocal hits at 20% identity; POCP ≥ 40% identity / 50% coverage / E-value < 1×10⁻⁵
3 — PhylogenomicsMaximum-Likelihood tree, 1,000 ultrafast bootstrap replicates
4 — MappingContainment threshold (c) = 100, minimum 5 target k-mers per detection
5 — AnnotationDatabase matches ≥ 80% identity, ≥ 80% query coverage (CARD, VFDB, BacMet2, NCBI)
6 — Metabolic modelsUnconstrained growth test at ±1000 mmol·gDW⁻¹·h⁻¹

Orchestration

Each module is a Snakemake sub-workflow running in its own Conda environment, deployed at runtime and chained together by a master dispatch script alongside custom Python/Bash connectors that standardize tool outputs into CSV/TSV between modules. A centralized config.yaml is the single point of control for analysis paths, parameter thresholds, and compute allocation.

← Usage & TutorialsTeam & Credits →

Team & Credits

NOSE is developed at the Centre for Integrative Biology and Systems mEdicine (IBSE), Wadhwani School of Data Science and AI, IIT Madras.

  • Prithvi S Prabhu
  • Harippriya Sivakumar
  • Enos Jadlin
  • Pratyay Sengupta
  • Karthik Raman — Principal Investigator

Acknowledgements

NOSE builds on open-source tools including FastANI, Snakemake, GTDB-Tk, CheckM2, and the other tools listed under Pipeline Details. See the repository for a full list of dependencies and licenses.

← Pipeline DetailsFAQ →

FAQ

Common questions about installing and running NOSE.

What counts as a "novel" species?

NOSE flags a genome as a novel candidate when its ANI to the closest reference genome falls below the species boundary threshold, given sufficient alignment coverage. A flagged result is a candidate for further taxonomic review, not a final classification.

Do I need my own reference database?

NOSE compares against whatever reference database you point it to. You can supply a custom set of reference genomes relevant to your organism group, or use a general-purpose reference set.

Can I run NOSE on a cluster?

Yes — since the pipeline is a Snakemake workflow underneath, it can be submitted to cluster or HPC schedulers using Snakemake's standard execution profiles.

Where do I report a bug or request a feature?

Open an issue on the NOSE GitHub repository.

← Team & Credits