instanexus 0.1.0__tar.gz

instanexus-0.1.0/.github/workflows/cdci.yml

@@ -0,0 +1,33 @@
+name: Python application
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+permissions:
+  contents: read
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: psf/black@stable
+      - uses: isort/isort-action@v1
+  lint:
+    name: Lint with ruff
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install ruff
+        run: |
+          pip install ruff
+      - name: Lint with ruff
+        run: |
+          # stop the build if there are Python syntax errors or undefined names
+          ruff check src unittests

instanexus-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# data 
+outputs/
+figures/
+logs/
+
+# ignore compiled python files
+*.pyc
+__pycache__/
+.DS_Store
+environment.yml
+
+# files
+inputs/BIND15.csv
+inputs/BIND16.csv
+inputs/ma2.csv
+inputs/ma3.csv
+inputs/NB1.csv
+inputs/NB2.csv
+inputs/NB3.csv
+inputs/NB4.csv
+inputs/NB5.csv
+inputs/NB8.csv
+inputs/NB12.csv
+inputs/NB13.csv
+inputs/pa.csv
+inputs/pb.csv

instanexus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Multi-omics Network Analytics Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

instanexus-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: instanexus
+Version: 0.1.0
+Summary: End-to-end workflow for de novo protein sequencing based on InstaNovo
+Project-URL: Homepage, https://github.com/Multiomics-Analytics-Group/InstaNexus
+Project-URL: Issues, https://github.com/Multiomics-Analytics-Group/InstaNexus/issues
+Author-email: Marco Reverenna <marcor@dtu.dk>
+License: MIT
+License-File: LICENSE
+Keywords: assembly,bioinformatics,de novo,mass spectrometry,protein sequencing,proteomics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: biopython>=1.85
+Requires-Dist: logomaker>=0.8
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: networkx>=3.3
+Requires-Dist: pandas>=2.3.1
+Requires-Dist: plotly>=6.2.0
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: tqdm>=4.67.1
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="images/instanexus_logo 2.svg" width="600" alt="InstaNexus logo">
+</p>
+
+<p align="center"><em>A de novo protein sequencing workflow</em></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/environment-conda-blue" alt="Conda">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+  <img src="https://img.shields.io/badge/python-3.9+-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
+- 🔗 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
+- 📊 Output-ready for downstream analysis and visualization
+
+---
+
+## Workflow Diagram
+
+<p align="center">
+  <img src="images/instanexus_panel.png" width="900" alt="InstaNexus Workflow">
+</p>
+
+---
+
+## Repository Structure
+
+
+| Folder / File | Description |
+|----------------|-------------|
+| `environment.linux.yml` | Conda environment for Linux systems |
+| `environment.osx-arm64.yaml` | Conda environment for macOS (Apple Silicon) |
+| `src/instanexus/` | Core InstaNexus package (modules + CLI) |
+| `src/instanexus/__main__.py` | Entry point for CLI (`instanexus` command) |
+| `src/instanexus/script_dbg.py` | De Bruijn Graph-based assembly |
+| `src/instanexus/script_greedy.py` | Greedy-based peptide assembly |
+| `src/opt/` | Grid search and optimization workflows |
+| `fasta/` | FASTA reference and contaminant sequences |
+| `inputs/` | Example input CSV files |
+| `json/` | Metadata and parameter configuration files |
+| `notebooks/` | Jupyter notebooks for analysis and visualization |
+| `images/` | Logos and workflow figures |
+| `outputs/` | Generated results (created during execution) |
+
+---
+
+## Installation
+
+- [Conda](https://docs.conda.io/en/latest/)
+- [MMseqs2](https://github.com/soedinglab/MMseqs2)
+- [Clustal Omega](https://www.ebi.ac.uk/Tools/msa/clustalo/)
+
+> [!IMPORTANT]
+> MMseqs2 and Clustal Omega are available through Conda, but compatibility depends on your system architecture.
+> - 🔍 [Clustal Omega on Anaconda.org](https://anaconda.org/search?q=clustalo)   
+
+---
+
+## Getting Started
+
+Follow these steps to clone the repository and set up the environment using Conda:
+
+### 1. Clone the repository
+
+To clone and set up the environment:
+
+```bash
+git clone git@github.com:Multiomics-Analytics-Group/InstaNexus.git
+cd instanexus
+```
+
+### 2. Create and activate the Conda environment
+
+Create instanexus conda environment for linux.
+
+```bash
+conda env create -f environment.linux.yml
+```
+
+Create instanexus conda environment for OS.
+
+```bash
+conda env create -f environment.osx-arm64.yaml
+```
+
+Activate:
+
+```bash
+conda activate instanexus
+```
+
+---
+
+### 3. Install InstaNexus as a local package
+
+```
+pip install -e .
+```
+
+Then verify the CLI installation:
+
+```
+instanexus --version
+```
+
+---
+
+## Command-line usage
+
+After activating the environment, you can run InstaNexus directly from the terminal:
+```bash
+instanexus --help
+```
+
+### Run De Bruijn graph assembly
+
+```
+instanexus dbg --input_csv inputs/sample.csv --chain light --folder_outputs outputs --reference
+```
+
+### Run greedy assembly
+
+```
+instanexus greedy --input_csv inputs/sample.csv --folder_outputs outputs
+```
+
+
+
+
+---
+
+## Hyperparameter Optimization
+
+To launch the hyperparameter grid search, run the following command from the project root (the folder containing ```src/``` and ```json/```):
+
+```bash
+python -m src.opt.gridsearch
+```
+**Adjusting Parameters**
+
+Grid search parameters for both the De Bruijn graph (dbg) and Greedy (greedy) assembly methods are defined in:
+
+```bash
+json/gridsearch_params.json
+```
+
+To test more (or fewer) combinations, edit the arrays for each parameter in this file.
+
+## 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 it as:
+
+Reverenna M., Nielsen M. W., Wolff D. S., Lytra E., Colaianni P. D., Ljungars A., Laustsen A. H., Schoof E. M., Van Goey J., Jenkins T. P., Lukassen M. V., Santos A., Kalogeropoulos K. (2025). *Generalizable direct protein sequencing with InstaNexus* [Preprint]. bioRxiv. https://doi.org/10.1101/2025.07.25.666861

instanexus-0.1.0/README.md

@@ -0,0 +1,214 @@
+<p align="center">
+  <img src="images/instanexus_logo 2.svg" width="600" alt="InstaNexus logo">
+</p>
+
+<p align="center"><em>A de novo protein sequencing workflow</em></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/environment-conda-blue" alt="Conda">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+  <img src="https://img.shields.io/badge/python-3.9+-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
+- 🔗 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
+- 📊 Output-ready for downstream analysis and visualization
+
+---
+
+## Workflow Diagram
+
+<p align="center">
+  <img src="images/instanexus_panel.png" width="900" alt="InstaNexus Workflow">
+</p>
+
+---
+
+## Repository Structure
+
+
+| Folder / File | Description |
+|----------------|-------------|
+| `environment.linux.yml` | Conda environment for Linux systems |
+| `environment.osx-arm64.yaml` | Conda environment for macOS (Apple Silicon) |
+| `src/instanexus/` | Core InstaNexus package (modules + CLI) |
+| `src/instanexus/__main__.py` | Entry point for CLI (`instanexus` command) |
+| `src/instanexus/script_dbg.py` | De Bruijn Graph-based assembly |
+| `src/instanexus/script_greedy.py` | Greedy-based peptide assembly |
+| `src/opt/` | Grid search and optimization workflows |
+| `fasta/` | FASTA reference and contaminant sequences |
+| `inputs/` | Example input CSV files |
+| `json/` | Metadata and parameter configuration files |
+| `notebooks/` | Jupyter notebooks for analysis and visualization |
+| `images/` | Logos and workflow figures |
+| `outputs/` | Generated results (created during execution) |
+
+---
+
+## Installation
+
+- [Conda](https://docs.conda.io/en/latest/)
+- [MMseqs2](https://github.com/soedinglab/MMseqs2)
+- [Clustal Omega](https://www.ebi.ac.uk/Tools/msa/clustalo/)
+
+> [!IMPORTANT]
+> MMseqs2 and Clustal Omega are available through Conda, but compatibility depends on your system architecture.
+> - 🔍 [Clustal Omega on Anaconda.org](https://anaconda.org/search?q=clustalo)   
+
+---
+
+## Getting Started
+
+Follow these steps to clone the repository and set up the environment using Conda:
+
+### 1. Clone the repository
+
+To clone and set up the environment:
+
+```bash
+git clone git@github.com:Multiomics-Analytics-Group/InstaNexus.git
+cd instanexus
+```
+
+### 2. Create and activate the Conda environment
+
+Create instanexus conda environment for linux.
+
+```bash
+conda env create -f environment.linux.yml
+```
+
+Create instanexus conda environment for OS.
+
+```bash
+conda env create -f environment.osx-arm64.yaml
+```
+
+Activate:
+
+```bash
+conda activate instanexus
+```
+
+---
+
+### 3. Install InstaNexus as a local package
+
+```
+pip install -e .
+```
+
+Then verify the CLI installation:
+
+```
+instanexus --version
+```
+
+---
+
+## Command-line usage
+
+After activating the environment, you can run InstaNexus directly from the terminal:
+```bash
+instanexus --help
+```
+
+### Run De Bruijn graph assembly
+
+```
+instanexus dbg --input_csv inputs/sample.csv --chain light --folder_outputs outputs --reference
+```
+
+### Run greedy assembly
+
+```
+instanexus greedy --input_csv inputs/sample.csv --folder_outputs outputs
+```
+
+
+
+
+---
+
+## Hyperparameter Optimization
+
+To launch the hyperparameter grid search, run the following command from the project root (the folder containing ```src/``` and ```json/```):
+
+```bash
+python -m src.opt.gridsearch
+```
+**Adjusting Parameters**
+
+Grid search parameters for both the De Bruijn graph (dbg) and Greedy (greedy) assembly methods are defined in:
+
+```bash
+json/gridsearch_params.json
+```
+
+To test more (or fewer) combinations, edit the arrays for each parameter in this file.
+
+## 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 it as:
+
+Reverenna M., Nielsen M. W., Wolff D. S., Lytra E., Colaianni P. D., Ljungars A., Laustsen A. H., Schoof E. M., Van Goey J., Jenkins T. P., Lukassen M. V., Santos A., Kalogeropoulos K. (2025). *Generalizable direct protein sequencing with InstaNexus* [Preprint]. bioRxiv. https://doi.org/10.1101/2025.07.25.666861

instanexus-0.1.0/environment.linux.yml

@@ -0,0 +1,45 @@
+name: instanexus
+channels:
+  - bioconda
+  - conda-forge
+  - defaults
+dependencies:
+  - biopython=1.85
+  - pcre2=10.42
+  - bzip2=1.0.8
+  - zlib=1.2.13
+  - wheel=0.45.1
+  - ncurses=6.5
+  - readline=8.2
+  - xz=5.6.4
+  - gettext=0.21.0
+  - ca-certificates=2025.2.25
+  - wget=1.25.0
+  - llvm-openmp=17.0.6
+  - openssl==3.0.17
+  - libxml2=2.13.8
+  - python=3.9.21
+  - libexpat=2.7.0
+  - setuptools=80.9.0
+  - icu=73.1
+  - libffi=3.4.6
+  - libiconv=1.16
+  - pandas=2.3.1
+  - pip=25.1.1
+  - gawk=5.3.1
+  - tk=8.6.14
+  - libcxx=17.0.6
+  - sqlite=3.45.3
+  - tqdm=4.67.1
+  - libidn2=2.3.4
+  - libunistring=0.9.10
+  - clustalo=1.2.4
+  - matplotlib-base
+  - seaborn=0.13.2
+  - plotly=6.2.0
+  - logomaker=0.8
+  - networkx
+  - mmseqs2
+  - pip
+  - pip:
+      - kaleido==0.2.1

instanexus-0.1.0/environment.osx-arm64.yaml

@@ -0,0 +1,42 @@
+name: instanexus
+channels:
+  - conda-forge
+  - bioconda
+  - defaults
+
+dependencies:
+  # core runtime dependencies
+  - python=3.11
+  - biopython=1.85
+  - pandas=2.3.1
+  - upsetplot
+  - tqdm=4.67.1
+  - seaborn=0.13.2
+  - matplotlib-base
+  - plotly=6.2.0
+  - logomaker=0.8
+  - networkx
+  - mmseqs2
+  - sbl::clustalomega
+  - gawk
+  - wget
+
+  # notebook
+  - ipykernel
+  - nbformat
+
+  # development tools
+  - black
+  - pytest
+  - coverage
+  - mypy
+  - pre-commit
+
+  # packaging
+  - pip
+  - pip:
+      - kaleido==0.2.1
+      - build
+      - twine
+      - hatchling
+      - wheel

instanexus-0.1.0/examples/README.md

@@ -0,0 +1 @@
+In these notebooks we provide examples for greedy and DBG methods, with and without plots.