nose-pipeline 1.0.2

NOSE — Novel Species Identification Pipeline (Computational Systems Biology Lab @ IIT Madras)

NOvel SpEcies Identification Pipeline

A Modular Snakemake Toolkit for Novelty Identification and Characterization

Documentation Site  ·  Wiki  ·  Setup Guide  ·  Report an Issue

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
• 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

NOSE takes a directory of genome FASTA files and returns — with full scientific evidence — whether each genome belongs to an already-described species or represents a candidate novel organism. Each module is an independent Snakemake workflow with its own conda environments, config file, and output directory.

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
M3	Phylogenetic ML Tree	ANI < 95% (novel)	ML tree + iTOL annotation
M4	Metagenome Mapping	ANI < 95% (novel)	final_report.csv
M5	Functional Characterization	ANI < 95% (novel)	7 CSV outputs
M6	Metabolic Modeling	ANI < 95% (novel)	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: NOSE runs on Linux or macOS. Windows users must use WSL2 (Windows Subsystem for Linux). All bioinformatics tools are installed automatically via conda.

---

Step 1 — Install the Python package

pip install nose-pipeline

This gives you four CLI commands: nose-ui · nose-setup · nose-db · nose-info

No separate git clone needed — the pipeline itself is bundled inside the package. The first time you run nose-ui, nose-setup, or nose-db, it copies itself into ~/nose-pipeline and runs from there.

Prefer working from source instead? git clone https://github.com/RamanLab/NOSE.git && cd NOSE && pip install -e . uses the cloned copy in place of the bundled one.

Windows users: run this inside WSL2, not PowerShell.

---

Step 2 — Set up conda + Snakemake

nose-setup

This runs automatically:

• Installs Miniconda3 (if not present)
• Adds conda-forge and bioconda channels
• Creates a snakemake conda environment

Or set it up manually:

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

---

Step 3 — Download databases

nose-db

Database	Size	Required by
CheckM2	~2 GB	Module 1 (prokaryotic)
GTDB-Tk	~66 GB	Module 1 (prokaryotic)
EukCC	~4 GB	Module 1 (eukaryotic)
CAT	~12 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: run run_ui.bat by double-clicking it, or run nose-ui inside WSL2.

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).

---

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 · CheckM2 · GTDB-Tk
Eukaryotic	QUAST · EukCC · CAT

Quality thresholds: Completeness ≥ 95% · 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

---

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 · AAI (aai.rb) · POCP (pocp.sh) · Barrnap · BLASTn · 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.

⚠️ Requires manual addition of Outroup (GCF ID) and HMM columns to genome_summary_mod.csv before running.

Tools: GToTree · IQ-TREE · iTOL · 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

---

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 · 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

---

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 · COGclassifier · antiSMASH · ABRICATE · geNomad

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 · COBRApy · 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.

Output: model_summary.csv — sample · n_reactions · n_metabolites · n_genes · growth · memote_score

---

Authors

Developed at Computational 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 · Computational Biology Lab · IIT Madras · Built for Novel Species Identification}