Metadata-Version: 2.4
Name: instanexus
Version: 0.3.0
Summary: End-to-end workflow for de novo protein sequencing based on InstaNovo
Author-email: Marco Reverenna <marcor@dtu.dk>
License: MIT
Project-URL: Homepage, https://github.com/Multiomics-Analytics-Group/InstaNexus
Project-URL: Issues, https://github.com/Multiomics-Analytics-Group/InstaNexus/issues
Keywords: proteomics,bioinformatics,protein sequencing,de novo,assembly,mass spectrometry
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython>=1.85
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.3.1
Requires-Dist: tqdm>=4.67.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: plotly>=6.2.0
Requires-Dist: logomaker>=0.8
Requires-Dist: networkx>=3.3
Requires-Dist: scikit-learn>=1.3
Requires-Dist: upsetplot
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-book-theme; extra == "docs"
Requires-Dist: myst-nb; extra == "docs"
Requires-Dist: ipywidgets; extra == "docs"
Requires-Dist: sphinx-new-tab-link!=0.2.2; extra == "docs"
Requires-Dist: jupytext; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Provides-Extra: lint
Requires-Dist: mypy; extra == "lint"
Requires-Dist: ruff; extra == "lint"
Requires-Dist: codespell; extra == "lint"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: jupytext; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: nbconvert; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/Multiomics-Analytics-Group/InstaNexus/main/docs/source/assets/instanexus_logo%202.svg" width="600" alt="InstaNexus logo">
</p>

<p align="center"><em>A de novo protein sequencing workflow</em></p>

<p align="center">
  <a href="https://github.com/pre-commit/pre-commit"><img src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit" alt="pre-commit"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  <img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python">
</p>

---

## Table of Contents
- [Introduction](#introduction)
- [Features](#features)
- [Workflow Diagram](#workflow-diagram)
- [Repository Structure](#repository-structure)
- [Installation](#installation)
- [Command-Line Usage](#command-line-usage)
- [Hyperparameter Optimization](#hyperparameter-optimization)
- [License](#license)
- [Acknowledgments](#acknowledgments)
- [References](#references)
- [Citation](#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](https://github.com/soedinglab/MMseqs2) for fast clustering
  - [Clustal Omega](https://www.ebi.ac.uk/Tools/msa/clustalo/) for high-quality alignment
- 📦 Reproducible environments via [uv](https://docs.astral.sh/uv/) or conda
- 📊 Output-ready for downstream analysis and visualization

---

## Workflow Diagram

<p align="center">
  <img src="https://raw.githubusercontent.com/Multiomics-Analytics-Group/InstaNexus/main/docs/source/assets/instanexus_panel.png" width="900" alt="InstaNexus Workflow">
</p>

---

## Repository Structure


| Folder / File | Description |
|----------------|-------------|
| `docs/` | Sphinx documentation, tutorials, and images |
| `fasta/` | FASTA reference and contaminant sequences |
| `inputs/` | Example input CSV files |
| `json/` | Metadata and parameter configuration files |
| `outputs/` | Generated results (created during execution) |
| `src/instanexus/` | Core InstaNexus package |
| `src/instanexus/main.py` | Runs the full pipeline |
| `src/instanexus/preprocessing.py` | Module for data cleaning |
| `src/instanexus/assembly.py` | Module for sequence assembly |
| `src/instanexus/clustering.py` | Module for clustering (mmseqs2) |
| `src/instanexus/alignment.py` | Module for alignment (clustalo) |
| `src/instanexus/consensus.py` | Module for consensus generation |
| `src/instanexus/optimize.py` | Entry point for the `instanexus-optimize` CLI |
| `scripts/optimization/` | Grid-search and optimization workflows |
| `tests/` | Pytest unit and integration tests |
| `pyproject.toml` | Package metadata, dependencies, and entry point |
| `environment.linux.yml` | Conda environment specification (Linux) |
| `environment.osx-arm64.yaml` | Conda environment specification (macOS, Apple Silicon) |
| `.pre-commit-config.yaml` | Pre-commit hook configuration |

---

## Installation

InstaNexus requires Python 3.10+, **MMseqs2**, and **Clustal Omega**. You can manage the
environment with either [uv](https://docs.astral.sh/uv/) or [conda](https://docs.conda.io/)
(the conda environment files bundle MMseqs2 and Clustal Omega for you).

- [uv](https://docs.astral.sh/uv/) — fast Python package manager
- [conda](https://docs.conda.io/) / [mamba](https://mamba.readthedocs.io/) — cross-platform package and environment manager
- [MMseqs2](https://github.com/soedinglab/MMseqs2)
- [Clustal Omega](https://www.ebi.ac.uk/Tools/msa/clustalo/)

---

## Getting Started

### Option 1: Install from PyPI

```bash
pip install instanexus
```

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

#### Clone the repository:

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

#### Install uv (if not already installed):
```bash
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`.
```bash
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:
```bash
uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
```

#### Verify the installation:
```bash
uv run instanexus --help
```

### Option 3: Install from Source with conda

The conda environment files pin the Python dependencies **and** the external tools
(MMseqs2, Clustal Omega), so they provide a fully self-contained setup.

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

# Linux
conda env create -f environment.linux.yml

# macOS (Apple Silicon)
conda env create -f environment.osx-arm64.yaml

conda activate instanexus

# install InstaNexus itself into the environment
pip install -e .
```

Verify the installation:
```bash
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.

```bash
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.

```bash
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`](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:
```bash
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
```

| Flag | Description |
|---|---|
| `--input-csv` | Raw or cleaned input CSV (preprocessing runs automatically if no cleaned file exists in `--output-dir`) |
| `--metadata-json` | Path to `sample_metadata.json` (required for reference protein lookup) |
| `--grid-json` | Path to `gridsearch_params.json` defining the parameter grid |
| `--mode` | Assembly mode (`greedy`, `dbg_weighted`, `multimodal_dbg`) |
| `--chain` | Chain type for antibodies (`light` / `heavy`); omit for single-chain samples |
| `--workers` | Number of parallel worker processes (default: `8`) |
| `--output-dir` | Directory to save results (default: `outputs/_grid_search`) |

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](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](https://github.com/soedinglab/MMseqs2)
- [Clustal Omega](https://www.ebi.ac.uk/Tools/msa/clustalo/)

---

## 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](https://doi.org/10.1016/j.mcpro.2026.101547).

```bibtex
@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}
}
```
