Sovereign 8s.is mirror of standardgalactic/ProSurf
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-02-24 15:50:54 +00:00
deepscf Removed ESM form public release 2026-02-17 16:55:49 +00:00
docs Updated to ProSurf name 2026-02-19 13:15:29 +00:00
models Initial Commit 2025-06-10 13:20:53 +01:00
notebooks Added simha scripts 2026-02-24 15:50:54 +00:00
references Initial Commit 2025-06-10 13:20:53 +01:00
reports Initial Commit 2025-06-10 13:20:53 +01:00
scripts Added simha scripts 2026-02-24 15:50:54 +00:00
.gitignore Added simha scripts 2026-02-24 15:50:54 +00:00
LICENSE Initial Commit 2025-06-10 13:20:53 +01:00
README.md Added simha scripts 2026-02-24 15:50:54 +00:00
requirements.txt Removed ESM form public release 2026-02-17 16:55:49 +00:00
setup.py Updated to ProSurf name 2026-02-19 13:15:29 +00:00

ProSurf

ProSurf is a research codebase for predicting per-residue SCF values from protein sequences using ProtTrans embeddings and sequence models (LSTM, transformer-style variants, and related regressors).

Associated Paper

This repository accompanies the ChemRxiv paper:

  • Sridharan, S., Ettelaie, R., Sarkar, R., Afzali, M., Dela, H., Murray, B. S., Hazlehurst, T. A., Watson, N. J., & Sarkar, A. (2026). Data-driven pipeline enables discovery of plant protein surfactants. ChemRxiv. https://doi.org/10.26434/chemrxiv.15000208/v1

Paper page:

What This Repo Contains

  • Data preprocessing utilities for SCF datasets
  • Embedding pipelines for ProtTrans
  • Multiple token-level regression model architectures
  • Training and evaluation scripts
  • Visualization and clustering tools for model outputs and learned features

Repository Layout

.
|-- deepscf/
|   |-- data/                # Dataset classes and collate functions
|   |-- models/              # Model definitions
|   |-- training/            # Training utilities/config helpers
|   |-- utils/               # Args, preprocessing, embeddings, misc helpers
|   |-- validation/          # Validation helpers
|   `-- visualization/       # Plotting and clustering helpers
|-- notebooks/               # Main runnable experiment scripts (.py)
|-- scripts/                 # Additional feature extraction and clustering scripts
|-- docs/                    # Sphinx docs scaffold
|-- models/                  # Saved model checkpoints
|-- data/                    # Local raw/processed/cache data (user-managed)
|-- logs/                    # Runtime logs/figures (auto-generated)
|-- requirements.txt
`-- setup.py

Additional Scripts (scripts/)

The scripts/ folder contains standalone analysis workflows used in the SCF pipeline:

  • Aminoacid to numerical conversion and feature extraction.py: Converts single-letter amino acid sequences into numeric encodings suitable for SCF analysis, and extracts amino acid composition/count-based features. Amino acid grouping rules are editable in the script.
  • DBSCAN_Binary_shape_clustering.py: Loads SCF distance data from a folder structure where each protein has a subfolder containing totalmo.dist, extracts binary tall-shape features, computes UMAP embeddings, and visualizes DBSCAN clusters.
  • SCF_features.py: Extracts SCF distance-derived features such as max height, attached length, and free length for downstream analysis.
  • Kernel_Kmeans_Clustering.py: Runs kernel K-means clustering and visualization using amino acid features (from the amino acid conversion script) and SCF distance features (from SCF_features.py). Expects per-protein features saved in Excel format.
  • Segmentation_RandomForest_Distancemetric.py: Extracts diblock clusters from DBSCAN output (cluster 2 and 3 in this project), segments adsorbed vs free regions, computes segment-level amino acid composition/features, trains a Random Forest classifier for attachment status, and builds a 14-dimensional distance metric from feature importance and segment features.

Environment Setup

1. Create and activate a virtual environment

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install dependencies

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Optional developer tooling (format/lint):

python -m pip install black ruff flake8

Quickstart

1. Preprocess data

The preprocessing entrypoint is:

  • notebooks/preprocess_data.py

Example:

python notebooks/preprocess_data.py --raw-path data\raw --ds-name my_dataset --overwrite-existing true

This creates processed output under data/processed/<ds-name>/.

2. Train a model (ProtTrans pipeline)

The current training script is:

  • notebooks/SCF_predict_ProtT.py

Example:

python notebooks/SCF_predict_ProtT.py --dataset-path my_dataset.pickle --model LSTM --epochs 10 --lstm-layers 2 --tensorboard false

3. Run inference/evaluation on a trained checkpoint

Use:

  • notebooks/SCF_ProtT_run.py

Example:

python notebooks/SCF_ProtT_run.py --dataset-path my_dataset.pickle --lstm-layers 2 --tensorboard false

Key CLI Arguments

Training/data scripts share argument classes in:

  • deepscf/utils/args/training_args.py
  • deepscf/utils/args/dataset_args.py

Common options:

  • --dataset-path: processed pickle filename
  • --model: model family selection
  • --epochs: number of epochs
  • --lstm-layers: LSTM depth
  • --tensorboard: enable/disable TensorBoard logging
  • --cache-path: embedding/dataset cache location
  • --force-recache: rebuild cache

Logging and Outputs

At runtime, the package creates timestamped log directories under:

  • logs/<timestamp>/

Artifacts may include:

  • log files
  • training/test plots
  • t-SNE/PCA visualization exports

Model checkpoints are typically saved in:

  • models/

Notes

  • This is research-oriented code and includes multiple experimental scripts in notebooks/.
  • Some scripts assume local dataset layout and may require path updates.
  • For large embedding runs, GPU is strongly recommended.

License

This project is released under the license in LICENSE.