instanexus 0.3.1

A de novo protein sequencing workflow

Table of Contents

• Introduction
• Features
• Workflow Diagram
• Repository Structure
• Installation
• Command-Line Usage
• Hyperparameter Optimization
• License
• Acknowledgments
• References
• Citation

Introduction

InstaNexus is a generalizable, end-to-end workflow for direct protein sequencing, tailored to reconstruct full-length protein therapeutics such as antibodies and nanobodies. It integrates AI-driven de novo peptide sequencing with optimized assembly and scoring strategies to maximize accuracy, coverage, and functional relevance.

This pipeline enables robust reconstruction of critical protein regions, advancing applications in therapeutic discovery, immune profiling, and protein engineering.

Features

• 🧬 Supports De Bruijn Graph and Greedy-based assembly
• ⚗️ Handles multiple protease digestions (Trypsin, LysC, GluC, etc.)
• 🧹 Integrated contaminant removal and confidence filtering
• 🧩 Clustering, alignment, and consensus sequence reconstruction
• 🎛️ Parallel hyperparameter optimization via the instanexus-optimize grid-search CLI
• 🔗 Integrates with external tools:
  • MMseqs2 for fast clustering
  • Clustal Omega for high-quality alignment
• 📦 Reproducible environments via uv or conda
• 📊 Output-ready for downstream analysis and visualization

Workflow Diagram

Repository Structure

Installation

InstaNexus requires Python 3.10+, MMseqs2, and Clustal Omega. You can manage the environment with either uv or conda (the conda environment bundles MMseqs2 and Clustal Omega for you).

• uv — fast Python package manager
• conda / mamba — cross-platform package and environment manager
• MMseqs2
• Clustal Omega

Getting Started

Option 1: Install from PyPI

pip install instanexus

Option 2: Install from Source with uv (for Developers)

Clone the repository:

git clone git@github.com:Multiomics-Analytics-Group/InstaNexus.git
cd InstaNexus

Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

Sync the environment:

uv sync --all-extras creates a .venv/ and installs the runtime plus all optional (docs, lint, dev) dependencies from pyproject.toml/uv.lock.

uv sync --all-extras

Note: MMseqs2 and Clustal Omega are not Python packages. With uv, install them separately (e.g. via your system package manager) or use the conda option below, which bundles them.

Set up pre-commit hooks:

uv run pre-commit install --hook-type pre-commit --hook-type commit-msg

Verify the installation:

uv run instanexus --help

Option 3: Install from Source with conda

environment.yml provides Python and the external tools (MMseqs2 and Clustal Omega from bioconda); pip then installs InstaNexus and its Python dependencies from pyproject.toml. The same file works on Linux and macOS, on both x86_64 and arm64 (Apple Silicon). bioconda has no Windows builds, so on Windows use WSL.

git clone git@github.com:Multiomics-Analytics-Group/InstaNexus.git
cd InstaNexus

conda env create -f environment.yml
conda activate instanexus

# install InstaNexus and its Python dependencies into the environment
pip install -e .

# optional: development, linting, and docs tools
pip install -e ".[dev,lint,docs]"

Verify the installation:

instanexus --help

Command-line usage

After installation (and adding the [project.scripts] entry point), you can run the entire InstaNexus pipeline using the instanexus command.

All parameters for preprocessing, assembly, clustering, and consensus are provided in a single call. The pipeline will automatically create a unique, timestamped output folder for that specific combination of parameters.

instanexus --help

Example: Run the full pipeline This command runs the complete workflow:

Preprocesses the input CSV.

Assembles using dbg (De Bruijn graph).

Clusters the resulting scaffolds.

Aligns the clusters.

Generates consensus sequences.

instanexus \
    --input-csv inputs/bsa.csv \
    --folder-outputs outputs \
    --metadata-json-path json/sample_metadata.json \
    --contaminants-fasta-path fasta/contaminants.fasta \
    --assembly-mode dbg \
    --conf 0.9 \
    --kmer-size 7 \
    --size-threshold 12 \
    --min-overlap 3 \
    --min-seq-id 0.85 \
    --coverage 0.8

The results for this specific run will be saved in a unique directory, such as:outputs/bsa/dbg_c0.9_ks7_mo3_ts12/

Hyperparameter Optimization

InstaNexus ships with a parallel grid-search optimizer, exposed as the instanexus-optimize command (entry point for scripts/optimization/grid_search.py). It sweeps assembly parameters across a grid, evaluates each combination against a reference, and ranks them with a normalized Composite Score combining Coverage, N50, scaffold count, and maximum contig length (see scripts/optimization/README.md for the exact formula).

The search space for each assembly mode (greedy, dbg_weighted, multimodal_dbg) is defined in json/gridsearch_params.json.

Run a grid search:

instanexus-optimize \
    --input-csv inputs/ma1_cleaned.csv \
    --metadata-json json/sample_metadata.json \
    --grid-json json/gridsearch_params.json \
    --mode dbg_weighted \
    --chain light \
    --workers 16

To sweep multiple samples and modes at once, see scripts/optimization/run_all_gridsearch.sh. Results can be summarized and visualized with scripts/optimization/analyze_optimization.py.

License

This project is licensed under the MIT License.

Acknowledgments

InstaNexus was developed at DTU Biosustain and DTU Bioengineering.

We are grateful to the DTU Bioengineering Proteomics Core Facility for maintenance and operation of mass spectrometry instrumentation.

We also thank the Informatics Platform at DTU Biosustain for their support during the development and optimization of InstaNexus.

Special thanks to the users and developers of:

• MMseqs2
• Clustal Omega

References

1. Hauser, M., et al. MMseqs2: ultra fast and sensitive sequence searching. Nature Biotechnology 35, 1026–1028 (2016). https://doi.org/10.1038/nbt.3988
2. Sievers, F., et al. Fast, scalable generation of high-quality protein multiple sequence alignments using Clustal Omega. Molecular Systems Biology 7, 539 (2011). https://doi.org/10.1038/msb.2011.75
3. Eloff, K., Kalogeropoulos, K., Mabona, A., Morell, O., Catzel, R., Rivera-de-Torre, E., ... & Jenkins, T. P. (2025). InstaNovo enables diffusion-powered de novo peptide sequencing in large-scale proteomics experiments. Nature Machine Intelligence, 1-15.

Citation

If you find this project useful in your research or work, please cite our publication in Molecular & Cellular Proteomics: Generalizable direct protein sequencing with InstaNexus.

@article{reverenna2026generalizable,
  title={Generalizable direct protein sequencing with InstaNexus},
  author={Reverenna, Marco and Nielsen, Maike Wennekers and Wolff, Darian Stephan and Daniel, Jemma and Lytra, Elpida and 
          Thumtecho, Suthimon and Colaianni, Pasquale D and Ljungars, Anne and Laustsen, Andreas H and Schoof, Erwin M and
          Van Goey, Jeroen and Jenkins, Timothy P and Lukassen, Marie V and Santos, Alberto and Kalogeropoulos, Konstantinos},
  journal={Molecular \& Cellular Proteomics},
  volume={25},
  number={4},
  pages={101547},
  year={2026},
  doi={10.1016/j.mcpro.2026.101547},
  publisher={Elsevier}
}