- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| deepscf | ||
| docs | ||
| models | ||
| notebooks | ||
| references | ||
| reports | ||
| scripts | ||
| .gitignore | ||
| LICENSE | ||
| README.md | ||
| requirements.txt | ||
| setup.py | ||
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 containingtotalmo.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 (fromSCF_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.pydeepscf/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.