# whodevrajverma/toxinpred3 architecture

> Architecture diagram of the GitHub repository whodevrajverma/toxinpred3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whodevrajverma/toxinpred3
- Repository: https://github.com/whodevrajverma/toxinpred3

## Overview

1. **Repository purpose**
   - This is a standalone peptide toxicity prediction package, centered on a single command-line entry point: `toxinpred3.py`.
   - It predicts whether an input peptide is toxic or non-toxic and can also scan/map toxic motifs.

2. **Top-level runtime architecture**
   - The runtime is local and file-based, not service-based.
   - Main dependencies are Python 3 plus `numpy`, `pandas`, and `scikit-learn`.
   - A Perl-based MERCI component is bundled under `merci/` and is invoked as part of the hybrid mode.

3. **Primary user interface**
   - Inputs are accepted either as:
     - FASTA-formatted peptide sequences (`peptide.fa` is the example), or
     - one sequence per line in plain text (`peptide.seq` is the example).
   - Results are written to CSV, typically `outfile.csv` unless the user provides `-o`.

4. **Core inference pipeline**
   - The script reads sequences, normalizes them, and extracts composition-based features.
   - The documented feature set for the machine-learning model is amino-acid composition (AAC) plus dipeptide composition (DPC).
   - These features feed a pre-trained Extra Trees classifier stored in `model/toxinpred3.0_model.pkl.zip`.

5. **Model 1: machine-learning only**
   - This mode uses only the Extra Trees model.
   - The output is a toxicity score and a binary classification derived from the user threshold.
   - This is the simpler boundary: sequence input → composition features → trained classifier → prediction.

6. **Model 2: hybrid prediction**
   - The default mode is the hybrid model.
   - It combines the machine-learning score with motif evidence from MERCI.
   - The final decision is based on a hybrid score, not just the classifier output.

7. **Motif subsystem**
   - `motifs/pos_motif.txt` and `motifs/neg_motif.txt` provide motif definitions used by the MERCI step.
   - `merci/MERCI_motif_locator.pl` is the motif-scanning engine.
   - This subsystem acts as an external rule-based signal layered on top of the statistical model.

8. **Data flow between subsystems**
   - Sequence input enters the Python driver.
   - The driver computes composition features and runs the serialized ML model.
   - In hybrid mode, the same sequence is also passed to the MERCI motif scanner.
   - The two signals are fused into a final score/classification, then written to CSV.

9. **Thresholding and display behavior**
   - The `-t` threshold controls the toxic/non-toxic cutoff and defaults to `0.38`.
   - `-d` controls whether only toxic peptides or all peptides are shown in the output.
   - This means the model produces a score first, then the CLI layer applies reporting rules.

10. **Packaged artifacts vs. runtime artifacts**
   - `dataset/` contains labeled positive/negative training/test CSVs, likely for model development, evaluation, or reproducibility.
   - `model/` holds the serialized inference artifact.
   - `motifs/` holds motif libraries for the hybrid layer.
   - This separation cleanly distinguishes training/reference data from deployable prediction assets.

11. **External execution boundary**
   - The main cross-language boundary is Python calling Perl for MERCI.
   - That makes the hybrid path dependent on a Perl runtime and the bundled motif locator script.
   - The pure ML path stays entirely within Python/scikit-learn.

12. **Operational characteristics**
   - The repository is designed for offline batch prediction of peptide files rather than interactive use.
   - It supports both single-sequence and multi-sequence inputs, so the architecture is sequence-oriented and file-driven.
   - The output is a tabular CSV suitable for downstream analysis or integration.

13. **What to show in an architecture diagram**
   - One input node for peptide files/lines.
   - A Python orchestration layer (`toxinpred3.py`).
   - Two branches:
     - ML feature extraction + Extra Trees model
     - MERCI motif scanning via Perl + motif files
   - A fusion stage for hybrid scoring.
   - A CSV output sink.
   - Separate asset stores for model pickle, motif lists, and dataset files.

Main entry points: [`merci/MERCI_motif_locator.pl`](https://github.com/whodevrajverma/toxinpred3/blob/main/merci/MERCI_motif_locator.pl) (MERCI runner), [`model/toxinpred3.0_model.pkl.zip`](https://github.com/whodevrajverma/toxinpred3/blob/main/model/toxinpred3.0_model.pkl.zip) (Extra Trees), [`toxinpred3.py`](https://github.com/whodevrajverma/toxinpred3/blob/main/toxinpred3.py) (toxinpred3.py), [`peptide.fa`](https://github.com/whodevrajverma/toxinpred3/blob/main/peptide.fa) (Peptide input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_input_files["Peptide input<br/>[peptide.fa]"]
  node_cli["toxinpred3.py<br/>Python CLI<br/>[toxinpred3.py]"]
  node_normalize["Normalize seqs<br/>parser"]
  node_features["AAC + DPC<br/>feature extraction"]
  node_ml_score["ML score<br/>prediction"]
  node_merci_call["MERCI runner<br/>Perl bridge"]
  node_motif_hits["Motif hits<br/>rule signal"]
  node_hybrid_fuse(("Hybrid fuse<br/>score fusion"))
  node_threshold{{"Threshold<br/>cli policy"}}
  node_output_csv["CSV output<br/>report"]
end

subgraph group_assets["Assets"]
  node_ml_model[("Extra Trees<br/>sklearn model")]
  node_pos_motifs["Pos motifs<br/>motif library<br/>[pos_motif.txt]"]
  node_neg_motifs["Neg motifs<br/>motif library<br/>[neg_motif.txt]"]
end

subgraph group_data["Data"]
  node_train_data["Train sets<br/>labeled data<br/>[train_pos.csv]"]
  node_test_data["Test sets<br/>labeled data<br/>[test_pos.csv]"]
end

node_input_files -->|"load"| node_cli
node_cli -->|"parse"| node_normalize
node_normalize -->|"extract"| node_features
node_features -->|"score"| node_ml_model
node_ml_model -->|"predict"| node_ml_score
node_cli -->|"hybrid mode"| node_merci_call
node_merci_call -->|"use"| node_pos_motifs
node_merci_call -->|"use"| node_neg_motifs
node_merci_call -->|"emit"| node_motif_hits
node_ml_score -->|"combine"| node_hybrid_fuse
node_motif_hits -->|"combine"| node_hybrid_fuse
node_ml_score -->|"apply"| node_threshold
node_hybrid_fuse -->|"apply"| node_threshold
node_threshold -->|"write"| node_output_csv
node_train_data -.->|"develop"| node_ml_model
node_test_data -.->|"validate"| node_ml_model

click node_input_files "https://github.com/whodevrajverma/toxinpred3/blob/main/peptide.fa"
click node_cli "https://github.com/whodevrajverma/toxinpred3/blob/main/toxinpred3.py"
click node_ml_model "https://github.com/whodevrajverma/toxinpred3/blob/main/model/toxinpred3.0_model.pkl.zip"
click node_merci_call "https://github.com/whodevrajverma/toxinpred3/blob/main/merci/MERCI_motif_locator.pl"
click node_pos_motifs "https://github.com/whodevrajverma/toxinpred3/blob/main/motifs/pos_motif.txt"
click node_neg_motifs "https://github.com/whodevrajverma/toxinpred3/blob/main/motifs/neg_motif.txt"
click node_train_data "https://github.com/whodevrajverma/toxinpred3/blob/main/dataset/train_pos.csv"
click node_test_data "https://github.com/whodevrajverma/toxinpred3/blob/main/dataset/test_pos.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_input_files,node_cli,node_normalize,node_features,node_ml_score,node_merci_call,node_motif_hits,node_hybrid_fuse,node_threshold,node_output_csv toneBlue
class node_ml_model,node_pos_motifs,node_neg_motifs toneAmber
class node_train_data,node_test_data toneMint
```

## Components

### Runtime

Local Python inference path and cross-language motif scanning.

- [Peptide input](https://github.com/whodevrajverma/toxinpred3/blob/main/peptide.fa): input · FASTA or plain-text peptide sequences provided by the user. · `peptide.fa`
- [toxinpred3.py](https://github.com/whodevrajverma/toxinpred3/blob/main/toxinpred3.py): Python CLI · Main command-line driver that reads input, orchestrates scoring, and writes results. · `toxinpred3.py`
- **Normalize seqs**: parser · Loads and normalizes peptide sequences before feature extraction.
- **AAC + DPC**: feature extraction · Builds amino-acid and dipeptide composition features for the classifier.
- **ML score**: prediction · Per-sequence toxicity score and class derived from the trained model and threshold.
- [MERCI runner](https://github.com/whodevrajverma/toxinpred3/blob/main/merci/MERCI_motif_locator.pl): Perl bridge · Python invokes the bundled Perl motif locator in hybrid mode. · `merci/MERCI_motif_locator.pl`
- **Motif hits**: rule signal · Motif evidence returned from MERCI for hybrid scoring.
- **Hybrid fuse**: score fusion · Combines ML and motif evidence into the final hybrid toxicity decision.
- **Threshold**: cli policy · Applies the user cutoff for toxic versus non-toxic reporting.
- **CSV output**: report · Tabular prediction output written to outfile.csv or a user-specified path.

### Assets

Packaged model, motif libraries, and example inputs.

- [Extra Trees](https://github.com/whodevrajverma/toxinpred3/blob/main/model/toxinpred3.0_model.pkl.zip): sklearn model · Serialized classifier used for machine-learning-only toxicity scoring. · `model/toxinpred3.0_model.pkl.zip`
- [Pos motifs](https://github.com/whodevrajverma/toxinpred3/blob/main/motifs/pos_motif.txt): motif library · Positive motif definitions used by the MERCI scanner. · `motifs/pos_motif.txt`
- [Neg motifs](https://github.com/whodevrajverma/toxinpred3/blob/main/motifs/neg_motif.txt): motif library · Negative motif definitions used by the MERCI scanner. · `motifs/neg_motif.txt`

### Data

Labeled datasets for development and evaluation.

- [Train sets](https://github.com/whodevrajverma/toxinpred3/blob/main/dataset/train_pos.csv): labeled data · Positive and negative training CSVs used for model development. · `dataset/train_pos.csv`
- [Test sets](https://github.com/whodevrajverma/toxinpred3/blob/main/dataset/test_pos.csv): labeled data · Positive and negative test CSVs used for evaluation and reproducibility. · `dataset/test_pos.csv`

## Connections

- Peptide input → toxinpred3.py: load · User-provided peptide files are passed to the main driver.
- toxinpred3.py → Normalize seqs: parse · The driver reads and normalizes incoming sequences.
- Normalize seqs → AAC + DPC: extract · Normalized sequences are converted into composition features.
- AAC + DPC → Extra Trees: score · AAC/DPC features are evaluated by the trained Extra Trees model.
- Extra Trees → ML score: predict · Model output becomes a per-sequence toxicity score and class.
- toxinpred3.py → MERCI runner: hybrid mode · The driver dispatches the same sequence to the motif scanner in hybrid mode.
- MERCI runner → Pos motifs: use · MERCI consults positive motif definitions.
- MERCI runner → Neg motifs: use · MERCI consults negative motif definitions.
- MERCI runner → Motif hits: emit · The Perl scanner returns motif-based evidence.
- ML score → Hybrid fuse: combine · ML confidence contributes to the final hybrid score.
- Motif hits → Hybrid fuse: combine · Motif evidence is fused with the machine-learning signal.
- ML score → Threshold: apply · The CLI threshold converts scores into toxic/non-toxic reporting.
- Hybrid fuse → Threshold: apply · Hybrid scores are also filtered by the configured cutoff.
- Threshold → CSV output: write · Final predictions are written as CSV output.
- Train sets → Extra Trees: develop · Labeled training data underpins the serialized inference artifact.
- Test sets → Extra Trees: validate · Labeled test data supports evaluation and reproducibility.
