Peptide_Guardian is an industrial-grade, containerized bioinformatics suite engineered for the high-throughput characterization, biophysical profiling, and discovery of bioactive peptides.
Initially conceived as a proof-of-concept under the repository name silva-test, the project has been heavily refactored, renamed, and promoted to a production-ready framework optimized for the Silva March 2026 Challenge. The pipeline utilizes a decoupled, four-node Directed Acyclic Graph (DAG) architecture to transform uncharacterized FASTA sequences into a prioritized, multi-parameter-scored lead list, with a specialized focus on identifying Cyclic Peptide Scaffolds.
In peptide drug discovery, the primary bottleneck is the transition from biological activity to chemical stability (developability). Peptide_Guardian addresses this by:
- Structural Stability Identification: The pipeline specifically evaluates Cysteine density to flag sequences capable of disulfide-bridge cyclization, hitting a critical theme of modern peptidomimetics.
- Ensemble Machine Learning: By utilizing a soft-voting ensemble of Random Forest and Extra Trees, the engine achieves higher robustness than single-model architectures, particularly on the diverse datasets typical of Antimicrobial Peptides (AMPs).
- Biophysical ADMET Audit: Leads are ranked not just on prediction confidence, but on their physiological suitability (Isoelectric point, Net Charge at pH 7.4, and GRAVY solubility scores).
- Robust Data Sanitization (Node 1): The ingestion engine features an aggressive regex-based scrubber (
[^A-Z]) that gracefully handles dirty FASTA inputs (e.g., hidden tabs, numbers, special characters) while perfectly extracting sequence labels and metadata for downstream tracking.
The pipeline is managed by the Silva Engine, enforcing strict data hermeticity. Each job operates in an isolated container. Data is passed between nodes via the Silva Relay System:
- Staging: The engine mounts the previous node's
outputs/as the current node'sinputs/. - Execution: The node processes data and writes artifacts to its root workspace.
- Harvesting: Upon successful exit, the engine harvests artifacts and persists them in the global
outputs/directory.
- Base Image:
python:3.11-slim - System Packages:
build-essential(required for C-extensions during Scipy/Scikit-learn compilation). - Execution Protocol: All nodes implement
pre_run.sh(dependency validation) andrun.sh(unbuffered Python execution viapython -ufor real-time Silva TUI telemetry).
- Objective: Sequence normalization, sanitation, and metadata tracking.
- Input 1:
inputs/input.fasta- Standard FASTA format file containing raw peptide sequences. - Input 2:
global_params.json- Dictates the target input filename and global parameters. - Processing: Sanitizes sequences (stripping regex
[^A-Z]), standardizes to uppercase, and assigns a persistent tracking code. - Output 1:
cleaned_sequences.csv- Structured data matrix containingPeptide_ID(e.g., P-0001),Original_Header,Sequence, andSequence_Length.
- Objective: Feature Engineering and ADMET (Absorption, Distribution, Metabolism, Excretion, and Toxicity) Landscape Mapping.
- Input 1:
inputs/cleaned_sequences.csv- Relayed automatically from Node 1. - Processing: Calculates Isoelectric Point (Bjellqvist method), GRAVY (hydropathy/solubility), Net Charge at pH 7.4, and a Boolean Cyclizability score (Cysteine count >= 2).
- Output 1:
peptide_features.csv- Expanded data matrix ready for machine learning (addsMW,pI,GRAVY,Charge,Cys_Count,Cyclizable). - Output 2:
screening_report.html- Standalone Plotly dashboard visualizing the Charge vs. Hydrophobicity landscape.
- Objective: Predictive Classification via Soft-Voting Ensemble Learning.
- Algorithm: Combines a Random Forest Classifier and an Extra Trees Classifier (200 estimators each,
max_depth=10,random_state=42). - Input 1:
inputs/peptide_features.csv- Relayed automatically from Node 2. - Output 1:
peptide_guardian_model.pkl- Serialized Scikit-learnVotingClassifierobject. - Output 2:
label_encoder.pkl- SerializedLabelEncoderfor inverse-transforming predictions back to biological classes. - Output 3:
classification_report.html- Model performance audit containing Validation Accuracy, AUC scores, and Feature Importance metrics.
- Objective: High-Confidence Lead Ranking and Final Reporting.
- Input 1:
inputs/peptide_features.csv- Features relayed from Node 2. - Input 2:
inputs/peptide_guardian_model.pkl&label_encoder.pkl- Model artifacts relayed from Node 3. - Input 3:
global_params.json- Parsed for dynamic confidence thresholding. - Processing: Applies the trained ensemble to the feature matrix. Filters leads strictly exceeding the user-defined
confidence_threshold. - Output 1:
guardian_leads.csv- Final target list for in-vitro synthesis containingPeptide_ID,Sequence,Predicted_Class,Confidence_Score, andCyclizable. - Output 2:
final_discovery_report.html- CSS-grid dashboard with integrated SheetJS logic, allowing client-side Excel (.xlsx) export of the final lead list.
Execution thresholds are controlled without touching source code via global_params.json located in the root directory:
{
"input_file": "input.fasta",
"confidence_threshold": 0.85
}
This project does not rely on local Python virtual environments or a requirements.txt file. All dependencies (Pandas, Biopython, Scikit-learn, Plotly, etc.) are packaged directly into the node execution container.
Before running the pipeline locally, you must compile the execution environment from the provided Dockerfile:
podman build -t chiral-guardian:v1 .(Note: If your system uses Docker, substitute podman with docker in the command above).
1. Verify Workspace Path: Ensure your orchestrator is pointing to the correct directory:
export SILVA_WORKFLOW_HOME=/path/to/Peptide_Guardian2. Run Pipeline:
PODMAN_USERNS=keep-id silva .(The user namespace flag ensures rootless Podman maps container write-permissions accurately to your local host).
This pipeline is optimized for seamless execution within GitHub Codespaces. Codespaces utilizes a Docker daemon that natively maps the container's internal root user to the workspace user, allowing frictionless volume mounting and file generation.
If you are executing the pipeline locally on a Linux machine using rootless Podman, you may encounter strict user namespace isolation errors. Reference the solutions below to resolve local execution blocks.
- Cause: The project was renamed from
silva-testtoPeptide_Guardian, but shell environment variables or bash aliases are still pointing to the old directory path. Furthermore, the Silva orchestrator requires a base.tmpdirectory to exist before spawning execution workspaces. - Solution: 1. Update your shell alias (e.g., in
~/.bashrc) to:alias silva="TMPDIR=/home/$USER/Peptide_Guardian/.tmp silva"2. Create the missing temporary directory manually:mkdir -p .tmp
- Cause: The pipeline is attempting to pull the
chiral-guardian:v1image from a remote registry, but the image is designed to be built locally from the provided Dockerfile. - Solution: Build the image locally before running the orchestrator:
podman build -t chiral-guardian:v1 .
- Cause: Rootless Podman maps the internal container user to a restricted sub-UID on your host machine. When the Python scripts (e.g.,
node1_ingest.py) attempt to write output CSVs back to the host-mounted workspace, your local OS blocks the write operation. This does not happen in Codespaces due to unified UID mapping. - Solution: Pass the user namespace override flag to Podman via the Silva orchestrator. This maps your local user ID directly to the container environment, granting it the same write permissions as your host profile:
PODMAN_USERNS=keep-id silva .
Peptide_Guardian has been rigorously stress-tested against "notorious" datasets. The ensemble model successfully navigates biophysical trickery, such as:
- Poly-Cysteine Traps: Rejecting sequences that pass the structural cyclizability gate but lack true AMP biophysical properties.
- Poly-Lysine Traps: Filtering out sequences with artificially inflated physiological Net Charge and pI scores. By learning the true feature importance of combined ADMET descriptors (Charge, GRAVY, pI), the soft-voting ensemble maintains high accuracy and successfully isolates true bioactive leads from biological decoys.
- Cock, P. J., et al. (2009). Biopython: freely available Python tools for computational molecular biology and bioinformatics.
- Pedregosa, F., et al. (2011). Scikit-learn: Machine Learning in Python.
- Kyte, J., & Doolittle, R. F. (1982). A simple method for displaying the hydropathic character of a protein.
- Silva Architecture Documentation (2026). Standardized Orchestration for Peptide Blueprinting.
Lead Developer: @Saadalishah107
Submission Date: March 2026
Theme Focus: Cyclic Peptides | Multi-Step Discovery Workflows