How whodevrajverma/toxinpred3 works
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_motif_locator.pl MERCI runner · toxinpred3.0_model.pkl.zip Extra Trees · toxinpred3.py toxinpred3.py · peptide.fa Peptide input
Components 15
Runtime
Local Python inference path and cross-language motif scanning.
- Peptide input · FASTA or plain-text peptide sequences provided by the user.
peptide.fa - toxinpred3.py · Main command-line driver that reads input, orchestrates scoring, and writes results.
toxinpred3.py - Normalize seqs · Loads and normalizes peptide sequences before feature extraction.
- AAC + DPC · Builds amino-acid and dipeptide composition features for the classifier.
- ML score · Per-sequence toxicity score and class derived from the trained model and threshold.
- MERCI runner · Python invokes the bundled Perl motif locator in hybrid mode.
merci/MERCI_motif_locator.pl - Motif hits · Motif evidence returned from MERCI for hybrid scoring.
- Hybrid fuse · Combines ML and motif evidence into the final hybrid toxicity decision.
- Threshold · Applies the user cutoff for toxic versus non-toxic reporting.
- CSV output · Tabular prediction output written to outfile.csv or a user-specified path.
Assets
Packaged model, motif libraries, and example inputs.
- Extra Trees · Serialized classifier used for machine-learning-only toxicity scoring.
model/toxinpred3.0_model.pkl.zip - Pos motifs · Positive motif definitions used by the MERCI scanner.
motifs/pos_motif.txt - Neg motifs · Negative motif definitions used by the MERCI scanner.
motifs/neg_motif.txt
Data
Labeled datasets for development and evaluation.
- Train sets · Positive and negative training CSVs used for model development.
dataset/train_pos.csv - Test sets · Positive and negative test CSVs used for evaluation and reproducibility.
dataset/test_pos.csv
Connections 16
- 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.