NOSE is a scalable bioinformatics pipeline designed to identify and characterize novel microbial species. By integrating quality assessment, phylogenomics, and functional mapping into a unified Snakemake workflow, NOSE ensures research is reproducible, automated, and ready for HPC environments.

---

Table of Contents

• Overview
• Pipeline Structure
• Installation
  • Step 1 - pip install
  • Step 2 - conda setup
  • Step 3 - Databases
  • Step 4 - Run
  • Controlling the web UI
  • Reports, results, and config tracking
• Docker
• Modules
  • Module 1: Genome Summary & Classification
  • Module 2: Overall Genome-Relatedness (OGRI)
  • Module 3: Phylogenetic Tree Workflow
  • Module 4: Metagenome Mapping Workflow
  • Module 5: Functional Characterization
  • Module 6: Metabolic Modeling Workflow
• Authors
• License

---

Overview

The vast majority of microbial life remains uncultured and uncharacterized, and confirming that a genome represents a genuinely novel species has traditionally meant coordinating a dozen separate tools by hand - a process prone to inconsistency and difficult to reproduce. NOSE automates that entire judgment call: point it at a directory of genome FASTA files, and it returns, with full multi-metric evidence (ANI, AAI, POCP, and phylogenetic placement), whether each genome belongs to an already-described species or is a candidate for a new one - then characterizes what that novel organism can actually do.

Every module is an independent Snakemake workflow with its own conda environments, config file, and output directory, so the pipeline scales from a laptop to an HPC cluster without any code changes.

Why NOSE:

• End-to-end - from raw assemblies to phylogenetic placement, environmental prevalence, functional annotation, and metabolic models, in one run
• Evidence-based - the novelty call rests on three independent genomic distance metrics (ANI, AAI, POCP) plus a maximum-likelihood phylogenetic tree, not a single threshold
• Reproducible - every tool runs in its own version-pinned conda environment via Snakemake's --use-conda, with checkpointing and automatic resume on interrupted runs
• No command line required - the built-in web UI configures and runs every module from a browser; pip install nose-pipeline is the only setup step

FASTA Files  →  M1: Quality Check  →  M2: Novelty Screen  →  Novel / Known
                                                                    ↓
                                                     · M3: Phylogenetic Tree Workflow
                                                     · M4: Metagenome Mapping
                                                     · M5: Functional Characterization
                                                     · M6: Metabolic Modeling

---

Pipeline Structure

Module	Name	Trigger	Key Output
M1	Genome Summary & Classification	All input genomes	genome_summary.csv
M2	Overall Genome-Relatedness (OGRI)	M1 output	compiled_results.csv · potential_novel.csv · genome_summary_for_tree.csv
M3	Phylogenetic ML Tree	M2 output	ML tree + iTOL annotation
M4	Metagenome Mapping	M2 output	final_report.csv
M5	Functional Characterization	M2 output	functional_summary.csv
M6	Metabolic Modeling	M2 output	SBML models + model_summary.csv

How to read the figure: FASTA files enter at the top. M1 and M2 run on all genomes. The ANI < 95% gate separates known species (right branch) from novel candidates (green path). All four characterization modules (M3–M6) run only on novel candidates.

---

Installation

System requirement: The bioinformatics tools themselves need Linux or macOS. On Windows, pip install and the web UI (nose-ui) work natively in PowerShell - the dashboard automatically routes actual module runs through WSL2 (a distro named Ubuntu must be installed). nose-setup and nose-db need a real bash on PATH (WSL2 or Git Bash), so run those two specifically inside WSL2. All bioinformatics tools are installed automatically via conda.

---

Step 1 - Install the Python package

pip install nose-pipeline

Latest release: nose-pipeline on PyPI - see the badge at the top of this page for the exact version actually published.

This is the only setup step - no git clone needed. The package carries its own copy of the pipeline code and unpacks it to ~/nose-pipeline the first time you run any command below, refreshing that copy on every launch so it always matches whatever version you have installed. Gives you four CLI commands: nose-ui · nose-setup · nose-db · nose-info.

Windows users: this step and nose-ui work fine directly in PowerShell. nose-setup and nose-db (next two steps) need WSL2, since they run bash scripts.

Contributing to NOSE instead of just running it? Clone the repo directly - git clone https://github.com/RamanLab/NOSE.git - and run everything from inside that checkout (pip install -e .) instead of a plain pip install. cli.py prefers a real git checkout over its own bundled copy whenever one is available, so you get git log/git pull/git blame on the actual pipeline code you're editing.

---

Step 2 - Set up your environment

nose-setup

Works with whichever of conda, mamba, or micromamba you already have installed - it doesn't require conda specifically. If none of the three are found, it asks before installing Miniconda3 (never silently).

It then asks what to call the environment (Enter for the default, nose), confirms before creating anything, and - unlike earlier versions - verifies the environment actually exists afterward instead of just trusting a zero exit code, so a partial/failed create can't silently report success.

nose-setup                     # asks for a name, confirms, then creates it
nose-setup --env-name myenv    # skip the name prompt
nose-setup --yes               # no prompts at all -- scripts/CI

Windows users: run this inside WSL2 - it shells out to a bash script directly, unlike nose-ui.

Or set it up manually with any of the three tools, e.g.:

conda config --add channels conda-forge
conda config --add channels bioconda
conda config --set channel_priority strict
conda create -n nose snakemake -y
conda activate nose

---

Step 3 - Download databases

nose-db

Asks "Download now? [y/N]" before each one (unless you pass --all), and checks free disk space at the destination first so you're not surprised partway through a 70 GB download.

Database	Size	Required by
CheckM2	~2 GB	Module 1 (prokaryotic)
GTDB-Tk	~66 GB	Module 1 (prokaryotic)
EukCC	~4 GB	Module 1 (eukaryotic)
CAT	~70 GB	Module 1 (eukaryotic)

GTDB-Tk is required for Module 1 prokaryotic path - skipping it means M1 will not run for prokaryotic genomes. Only use --skip-gtdbtk if you are running eukaryotic genomes exclusively.

---

Step 4 - Run the pipeline

Option A - Web UI (Recommended)

nose-ui

Opens a browser at http://localhost:5050. Fill in your genome directory, configure each module, and click Run Module.

Windows users: nose-ui (or double-clicking run_ui.bat) runs directly in PowerShell - no WSL2 needed just to launch the dashboard. When you click Run on a module, it automatically routes execution through WSL2 (requires a WSL distro named Ubuntu to be installed).

Large input sets: if you're processing a large number of genomes (or very large assemblies), prefer Option B - Command line below. Running directly in a terminal avoids keeping a browser tab open for long runs and makes it easier to monitor resource usage and pick up where you left off if a step is interrupted.

Option B - Command line

conda activate snakemake
cd Module1

# Edit config.yaml with your input/output paths, then:
bash Nose_Module1.sh

Repeat for each module in order: M1 → M2 → M3–M6 (M3–M6 require ANI < 95% candidates from M2).

---

Controlling the web UI

nose-ui --port 8080          # use a specific port instead of the interactive prompt
nose-ui --no-browser --yes   # headless start -- no browser tab, no prompts

Checking whether it's already running, and stopping it, are OS-level operations - see the Controlling the UI section of the docs for the exact PowerShell / lsof / ps commands, including a couple of real gotchas (killing a dashboard PID via Ctrl+C also stops an in-progress module, since it's a child process).

---

Reports, results, and config tracking

Every module writes a self-contained final_report.html with a "Download Excel" button and a full sortable/searchable results table - no digging through raw CSVs required. Every chart in every report also has publication-quality export buttons: PNG, SVG, TIFF, EPS, and PDF, all rendered at a 300-DPI-equivalent scale, so a figure goes straight from a NOSE run into a manuscript.

config_sync.py also writes Output/CONFIG_SNAPSHOT.md automatically at the start of every run - every path and setting actually in use, in plain language, with credentials shown only as "set" / "not set", never their actual value.

---

Full setup reference

Detailed Setup Guide - Anaconda installation, channel configuration, WSL2 setup for Windows

Quick Start - One-page cheat sheet for running all six modules

---

Docker

NOSE provides a multi-stage Docker image that bundles Miniconda3, Snakemake, and all module conda environments into a single container. The web UI is exposed on port 5050.

Note: Reference databases (GTDB-Tk ~66 GB, CheckM2 ~2 GB) are not included in the image - they must be downloaded separately and mounted at runtime.

Build the image

git clone https://github.com/RamanLab/NOSE.git
cd NOSE
docker build -t nose-pipeline .

Run with docker-compose (recommended)

# Set your local paths, then:
GENOMES_DIR=/path/to/genomes \
OUTPUT_DIR=/path/to/output \
DB_DIR=/path/to/databases \
docker-compose up

Open http://localhost:5050 in your browser.

Run with docker directly

docker run -p 5050:5050 \
  -v /path/to/genomes:/data/genomes \
  -v /path/to/output:/data/output \
  -v /path/to/databases:/data/databases \
  nose-pipeline

Path convention inside the container

Host path	Container path	Used by
Your genome folder	/data/genomes	All modules - set as Genome Directory in UI
Your output folder	/data/output	All modules - set as Output Directory in UI
Your databases folder	/data/databases	Module 1 (CheckM2, GTDB-Tk)

When running inside Docker, always use /data/genomes, /data/output, and /data/databases as your paths in the web UI - not local machine paths.

---

Modules

Module 1: Genome Summary & Classification

Module 1  |  Script: Nose_Module1.sh

Automated Snakemake workflow for assembly quality assessment and full taxonomic classification. A single is_euk flag in config.yaml selects the prokaryotic or eukaryotic path. Genomes passing the HQ filter are written to genome_summary.csv for downstream use.

Tools:

Path	Tools
Prokaryotic	QUAST v5.0.2 · CheckM2 v1.0.1 · GTDB-Tk v2.3.2
Eukaryotic	QUAST v5.0.2 · EukCC v2.1.0 · CAT v5.2.2

Quality thresholds: Completeness ≥ 90% · Contamination ≤ 5% · Classified to genus level minimum

Outputs:

• genome_summary.csv - genomes passing QC thresholds → input for Module 2
• unqualified_genome_summary.csv - genomes that did not meet thresholds

.fasta, .fa, and .fna genome files are all accepted interchangeably across every module - no need to rename files to match. Each module symlinks a .fasta-named entry alongside whichever extension your genomes actually use before processing starts.

Organism names are resolved directly from accessions - not filenames - via a shared NCBI lookup that recognizes GCA/GCF assembly, BioProject, BioSample, SRA, and RefSeq/GenBank accessions across every module's reports. A non-accession input (e.g. your own lab naming) correctly shows a blank Organism Name rather than a guessed one.

---

Module 2: Overall Genome-Relatedness (OGRI)

Module 2  |  Script: Nose_Module2.sh

Computes three complementary genomic distance metrics against all RefSeq type strains in the genome's genus, downloaded automatically via the NCBI Datasets API. Supports both WGS and 16S-only input modes. Genomes with ANI < 95% are flagged as candidate novel species.

An NCBI API key must be set in config.yaml. Without it, reference genome downloads will be rate-limited. How to get an NCBI API key: NCBI API Integration Guide

Tools: FastANI v1.34 · AAI (aai.rb) · POCP (pocp.sh) · Barrnap v0.9 · BLASTn v2.17.0+ · NCBI Datasets API

Three OGRI metrics:

Metric	Boundary	Significance
ANI	< 95% = novel	Primary species-level boundary (IJSEM standard)
AAI	-	Broader evolutionary distances at proteome level
POCP	< 50% = new genus	Genus-level delineation

Outputs:

• compiled_results.csv - all genomes with ANI / AAI / POCP / 16S identity
• potential_novel.csv - ANI < 95% candidates, staged for M3–M6

---

Module 3: Phylogenetic Tree Workflow

Module 3  |  Script: Nose_Module3.sh

Validates taxonomic novelty via genus-specific Maximum Likelihood (ML) trees built from concatenated Single-Copy Genes (SCGs). GToTree identifies SCGs using HMMs; IQ-TREE infers the ML tree with 1000 ultrafast bootstrap replicates; tree_annotation.py generates iTOL-ready annotation files.

Genus, outgroup accession, and HMM set are all resolved automatically by Module 2 - no manual file preparation required. See Module 3's README for how it works, or to override a genus's automatic pick.

Tools: GToTree v1.8.16 · IQ-TREE v3.0.1 · iTOL v7 · tree_annotation.py

IQ-TREE command:

iqtree \
  -s Aligned_SCGs.faa \   # concatenated SCG alignment
  -spp Partitions.txt \   # per-gene partition model
  -m MFP \                # ModelFinder Plus
  -bb 1000 \              # ultrafast bootstraps
  -nt 4 \                 # CPU threads
  -pre {genus}_iqtree_out

Outputs: Per-genus ML tree files + iTOL annotation CSV files

GToTree excludes any genome recovering less than 50% of the expected marker genes from the tree by default. Module 3 detects this from GToTree's own log, warns per-genus, and writes Annotation/dropped_genomes_summary.csv listing what was excluded and why. Set min_genome_coverage in Module 3's config to change the threshold.

---

Module 4: Metagenome Mapping Workflow

Module 4  |  Script: Nose_Module4.sh

Quantifies isolate prevalence and relative abundance across metagenomic datasets using sylph k-mer containment estimation. No BAM files or read alignment required. Species-level threshold (c=100) with minimum 5 k-mers enforced to suppress false positives.

Tools: sylph v0.1.2 · pandas · merge_results.py

Containment thresholds:

Threshold (c)	Resolution
100	Species-level (default)
95	Genus-level
90	Family-level

Output: final_report.csv - Sample_ID · Genome · Containment · ANI · Reads_Queried · Reads_Matching

The containment threshold is a real config field - set sylph_c in Module 4's config (or its Config tab in the web UI) to 100/95/90 for species/genus/family-level resolution. Optional module: needs raw metagenome reads, which most runs don't have - an "Include in Full Pipeline Run" toggle in the web UI lets you turn it off explicitly for Full Pipeline Run, independent of whether it's configured.

---

Module 5: Functional Characterization

Module 5  |  Script: Nose_Module5.sh

Multi-modal pipeline integrating structural annotation, COG functional classification, biosynthetic gene cluster detection, resistance and virulence screening, and mobile element identification.

Tools: Prokka v1.13 · COGclassifier v1.0.5 · antiSMASH v7.1.0 · ABRICATE v0.4 · geNomad v1.11.2

Workflow steps:

Step	Tool	Output
Gene annotation	Prokka	.gff · .faa · .ffn · .gbk
Functional classification	COGclassifier	merged_classifier_count.csv
BGC detection	antiSMASH	AntiSMASH_results.csv
Resistance & virulence	ABRICATE (CARD · VFDB · BacMet · NCBI)	Per-database tabular reports
Phage & plasmid detection	geNomad	virus_summary.csv · plasmid_summary.csv

geNomad tells you whether resistance or virulence genes reside on mobile elements - meaning they can spread horizontally to other organisms.

---

Module 6: Metabolic Modeling Workflow

Module 6  |  Script: Nose_Module6.sh

Genome-scale metabolic reconstruction using CarveMe (top-down approach). Each GEM is validated with COBRApy unconstrained growth tests and benchmarked with MEMOTE for stoichiometric consistency. Models are exported in SBML/FBC format compatible with COBRA Toolbox, cobrapy, and OptFlux.

Tools: CarveMe v1.6.6 · COBRApy v0.29.1 · MEMOTE · generate_model_stats.py · compile_model_summary.py

Always use the --prodigal flag with CarveMe. Default gene prediction produces incomplete GEM reconstruction for certain isolates.

CPLEX is the configured default solver. Gurobi is also supported as an alternative if you'd rather use a Gurobi license - set solver: gurobi in Module 6's config and point gurobi_license_path at your own installation. Gurobi offers a free Named-User Academic license for eligible students/staff at gurobi.com/academia.

Output: model_summary.csv - sample · n_reactions · n_metabolites · n_genes · growth · memote_score. Each genome's SBML model file is also directly downloadable from the module's HTML report.

Optional module: needs a working CPLEX or Gurobi license. An "Include in Full Pipeline Run" toggle in the web UI lets you turn it off explicitly for Full Pipeline Run, independent of whether it's configured.

---

Authors

Developed at Computational Systems Biology Lab @ IIT Madras

Role	Name
Principal Investigator	Prof. Karthik Raman
Pipeline Authors	Prithvi · Harippriya · Enos · Pratyay Sengupta

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

_{© 2026 NOSE Project Team · Systems Biology Lab · IIT Madras · Built for Novel Species Identification}