PhaseFlow is organized around one modeling goal: learn how sequence-level, phase-diagram, and protein-context signals map into phase-separation behavior, then use those learned mappings for prediction, localization, and design.
| Signal family | Role in PhaseFlow |
|---|---|
| Peptide sequence tokens | Sequence-to-phase prediction and phase-conditioned sequence generation |
| 4x4 PSSI phase diagrams | Compact representation of phase-separation score landscapes |
| Flow Matching and causal language modeling | Fast phase-diagram regression and target-conditioned peptide design |
| Protein residue context | Protein-level LLPS prediction and residue-level DPR scanning |
| ESM2, physicochemical, disorder, structure, graph, and local-context features | Multi-modal protein representations for protein tasks |
| Ordered bridge tokens | Transfer short-peptide sequence-phase knowledge into protein modeling |
PhaseFlow supports a connected set of phase-separation applications: designing peptide sequences from target phase diagrams, predicting phase diagrams from candidate sequences, scanning proteins for LLPS-driving regions, and estimating mutation effects on phase-separation behavior. These workflows share the same sequence-phase modeling foundation while exposing outputs that map naturally to peptide design, protein annotation, and mutagenesis analysis.
The short-peptide module is the bidirectional sequence-phase model. For sequence-to-phase prediction, peptide tokens and phase-grid tokens pass through shared Transformer blocks and a Flow Matching velocity head to predict a 4x4 PSSI diagram. For phase-to-sequence design, the same architecture conditions on the target phase diagram and uses causal language modeling to generate peptide sequences.
The protein module handles protein-scale context separately from the short-peptide task. It combines residue-level ESM2, physicochemical, disorder, structure-derived, graph, and local-context features, then bridges peptide sequence-phase knowledge through ordered bridge tokens and residue-query cross-attention. The outputs are protein-level LLPS probability and DPR scanner profiles that are post-processed into droplet-promoting region calls.
You should consider PhaseFlow when your phase-separation workflow needs:
| 🧬 | Unified multi-modal generative model | Brings sequence, phase-diagram, residue-context, structure-derived, graph, LLPS, DPR, and mutation-effect signals into one PhaseFlow workflow. |
| 🧪 | Multi-scale LLPS modeling | Covers short-peptide phase diagrams, protein LLPS, DPR localization, and mutation-effect scoring. |
| 🔁 | Bidirectional peptide model | Learns mappings between amino-acid sequences and 4x4 phase-separation score index (PSSI) diagrams. |
| ⚡ | Flow Matching for phase diagrams | Supports faster phase-conditioned peptide design loops than diffusion-style sampling. |
| 🔎 | Protein LLPS and DPR scanning | Predicts protein-level LLPS propensity and localizes droplet-promoting regions from residue context. |
| 🌉 | Staged transfer bridge | Transfers short-peptide sequence-phase knowledge to proteins through 32 ordered bridge tokens. |
| 🧫 | Mutation-effect scoring | Amino-acid perturbations can be scored for predicted shifts in phase-separation behavior. |
| 🧠 | Rich protein features | Combines ESM2, physicochemical, disorder, Protenix-derived, graph, and residue-context signals. |
| 📦 | Artifact-ready layout | Code, configs, docs, figures, local datasets, and local model downloads are separated so GitHub stays lightweight while Hugging Face artifacts can be added cleanly. |
The values below are summarized from the tracked configs, audit reports, and
figure artifacts in this repository. They are included to make the README
useful as a project entry point; detailed provenance remains in
configs/protein/ and docs/protein/.
| Task | Evaluation setting | PhaseFlow result |
|---|---|---|
| Protein LLPS | PPMC full panel | AUPRC 0.752, AUROC 0.874 |
| Protein LLPS | threshold 0.5 | MCC 0.549, F1 0.676 |
| Peptide phase prediction | complete held-out peptide diagrams | Spearman 0.4168, Pearson 0.4219, MSE 0.5652 |
| Flow Matching vs DDPM | matched peptide phase-grid comparison | mean Spearman 0.559 vs 0.277; MSE 0.570 vs 1.315 |
| DPR localization | PhasePro, p257 readout | residue AUPRC 0.712, top-5 enrichment 1.813 |
| DPR region calling | IoU 0.25 region matching | recall 0.580, precision 0.638, segment F1 0.608 |
| Mutation effects | TDP-43 point-mutation panels | strongest average ranking/classification metrics among compared methods in the included benchmark summary |
| Module | Path | Description |
|---|---|---|
| Peptide core package | phaseflow/ |
Tokenizer, peptide Transformer, Flow Matching/DDPM model, utilities |
| Protein package | phaseflow/protein/ |
Protein model structure, data contracts, reusable feature/structure functions, objectives, metrics, and post-processing |
| Peptide configs | configs/peptide/ |
Lightweight peptide training defaults |
| Protein configs | configs/protein/ |
LLPS and DPR training configurations |
| Peptide scripts | scripts/peptide/ |
Training, inference, resume, and experiment launchers |
| Protein scripts | scripts/protein/ |
Reproduction workflows for data construction, training, evaluation, release validation, and benchmark utilities |
| Examples | examples/ |
Small peptide demo inputs and phase-to-sequence example |
| Tests | tests/ |
Peptide smoke tests and focused protein tests |
| Figures | figures/ |
Curated README and paper-result figures |
| Research workflows | research/ |
Short-peptide experiments and analysis scripts |
| Local artifacts | artifacts/ |
Placeholder for local datasets, model downloads, and curated result artifacts |
Table of Contents
- Model Overview
- Application
- Unified Model Architecture
- Why Use PhaseFlow?
- Key Results
- Key Modules
- Public Resources
- Quick Start
- Installation
- Repository Layout
- Models And Datasets
- Short-Peptide Usage
- Protein Usage
- Evaluation And Checks
- Input And Output Formats
- Artifact Policy
- Figures
- Citation
- License
| Resource | Link | Purpose |
|---|---|---|
| Source code | GitHub: kevinhyj/PhaseFlow | Installation, workflows, configurations, and documentation |
| Unified checkpoint | Hugging Face: GENTEL-Lab/PhaseFlow | Combined peptide, full-protein, and DPR runtime weights |
| Training data | Hugging Face: GENTEL-Lab/OpenPhase | Public peptide, LLPS, and DPR research-data packages |
| Online demo | phaseflow.bio | Interactive PhaseFlow usage |
Install the source package:
git clone <your-phaseflow-repo-url>
cd PhaseFlow
conda env create -f environment.yml
conda activate phaseflow
python -m pip install -e .
python -c "import phaseflow; print(phaseflow.__version__)"Download the public training data and the combined runtime checkpoint:
huggingface-cli download GENTEL-Lab/OpenPhase \
--repo-type dataset \
--local-dir artifacts/data/peptide
hf download GENTEL-Lab/PhaseFlow PhaseFlow.pt \
--local-dir artifacts/modelsRun peptide sequence-to-phase inference:
bash scripts/peptide/infer.sh \
artifacts/models/peptide/best_model.pt \
examples/sequences.txt \
artifacts/results/peptide/predicted_phases.csv \
0The training data are hosted at
GENTEL-Lab/OpenPhase.
The combined PhaseFlow runtime checkpoint
contains peptide, full-protein, and DPR weights. It is intended for the
combined runtime; the standalone peptide scripts below still expect a
peptide-only best_model.pt checkpoint.
conda env create -f environment.yml
conda activate phaseflow
python -m pip install -e .Install optional protein and test dependencies:
python -m pip install -e ".[protein,test]"Install optional feature-generation dependencies:
python -m pip install -e ".[plm,starling]"The default source install is intended for code reuse, peptide workflows, and lightweight checks. Protein reproduction requires external data, feature stores, and model checkpoints that are not committed to Git.
phaseflow/ Peptide and protein packages
phaseflow/protein/ Protein model structure and reusable core components
configs/peptide/ Short-peptide configs
configs/protein/ Protein LLPS and DPR configs
docs/peptide/ Short-peptide documentation
docs/protein/ Protein documentation and audit reports
scripts/peptide/ Short-peptide training and inference launchers
scripts/protein/ Protein reproduction workflows and command adapters
scripts/protein/analysis/ Protein benchmark and threshold analyses
scripts/protein/inference/ Standalone protein DPR inference
tests/peptide/ Short-peptide smoke tests
tests/protein/ Protein focused tests
examples/ Short-peptide demo inputs
scripts/peptide/workflows/ Short-peptide training, inference, and evaluation entry points
scripts/peptide/analysis/ Short-peptide analysis scripts
artifacts/results/peptide/ Curated short-peptide analysis outputs
artifacts/results/protein/ Protein publication results and renderers
figures/peptide/ Short-peptide figures
figures/protein/ Protein LLPS/DPR figures
artifacts/data/ Local datasets and generated feature stores
artifacts/models/ Local model checkpoints downloaded from Hugging Face
artifacts/results/ Lightweight curated result artifacts
Large artifacts are intentionally separated from the source repository.
Suggested local layout:
artifacts/data/
peptide/ Phase-diagram CSV/NPZ data and split files
protein/ Manifests, feature stores, benchmark inputs
artifacts/models/
PhaseFlow.pt Combined peptide, full-protein, and DPR checkpoint
peptide/ Optional standalone peptide-only checkpoints
Public peptide training-data download:
huggingface-cli download GENTEL-Lab/OpenPhase \
--repo-type dataset \
--local-dir artifacts/data/peptide
hf download GENTEL-Lab/PhaseFlow PhaseFlow.pt \
--local-dir artifacts/models| Resource | Local target | Status |
|---|---|---|
| OpenPhase training data | artifacts/data/peptide/ |
Available on Hugging Face |
| Protein feature/data bundle | artifacts/data/protein/ |
Not yet released |
| Combined peptide, full-protein, and DPR checkpoint | artifacts/models/PhaseFlow.pt |
Available on Hugging Face |
| Standalone peptide-only checkpoint | artifacts/models/peptide/ |
Not yet released |
bash scripts/peptide/train.sh \
--config configs/peptide/peptide.yaml \
--data artifacts/data/peptide/phase_diagram_original_scale.csv \
--output-dir outputs/peptide \
--gpu 0 \
--foregroundbash scripts/peptide/infer.sh \
artifacts/models/peptide/best_model.pt \
examples/sequences.txt \
artifacts/results/peptide/predicted_phases.csv \
0python examples/phase2seq_demo.py \
--checkpoint artifacts/models/peptide/best_model.pt \
--input_csv artifacts/data/peptide/test_set.csv \
--num_samples 5python scripts/peptide/workflows/evaluate_seq2phase.py \
--test_path artifacts/data/peptide/test_set.csv \
--models_dir outputs/peptideThe protein code is packaged under phaseflow.protein. It expects
downloaded model checkpoints and feature/data bundles under artifacts/models/protein/
and artifacts/data/protein/.
Protein training configurations:
configs/protein/llps.yamlconfigs/protein/dpr.yaml
python scripts/protein/inference/predict_protein_dpr.py \
--input artifacts/data/protein/idr_sequences.xlsx \
--checkpoint artifacts/models/peptide/best_model.pt \
--output runs/protein/idr_phaseflow_profiles.jsonl \
--csv runs/protein/idr_phaseflow_profiles.csvtorchrun --nproc_per_node=8 scripts/protein/run.py train-dpr \
--config configs/protein/dpr.yaml \
--arm dpr \
--updates 50 \
--output-root runs/dprThis command requires the protein data package, reconstructed feature stores, and checkpoints referenced by the config.
python artifacts/results/protein/scripts/figures/plot_llps_benchmark.py --help
python artifacts/results/protein/scripts/figures/plot_dpr_benchmark.py --help
python artifacts/results/protein/scripts/figures/plot_model_architecture.py \
--output-dir runs/figures/proteinShort-peptide checks:
python -m compileall phaseflow scripts/peptide examples tests/peptide
python -m unittest discover tests/peptideProtein checks:
python -m compileall phaseflow/protein scripts/protein tests/protein
python -m pytest tests/protein/test_imports.py tests/protein/test_phaseflow_fusion.pyInstall test dependencies if pytest is unavailable:
python -m pip install -e ".[test]"scripts/peptide/infer.sh accepts a text file with one amino-acid sequence per
line, or the underlying Python script can read a CSV column named
AminoAcidSequence.
ACDEFGHIKLMNPQRSTVWY
GGGGGSSSSSQQQQQNNNNN
Sequence-to-phase inference writes a CSV with the sequence and 16 PSSI columns:
AminoAcidSequence,group_11,group_12,...,group_44
ACDEFGHIKLMNPQRSTVWY,0.12,-0.08,...,0.31
The IDR helper writes JSONL profiles and an optional compact CSV:
{"id":"IDR_000","length":120,"window_sizes":[20],"pssi_mean":0.14}Git tracks code, configs, docs, tests, and curated lightweight figures/results. It does not track raw datasets, generated feature stores, model checkpoints, training logs, or large runtime outputs.
Local artifact paths:
artifacts/data/peptide/andartifacts/data/protein/for datasets and feature stores.artifacts/models/peptide/andartifacts/models/protein/for Hugging Face model downloads.outputs/andlogs/for regenerated training or inference outputs.
The repository .gitignore excludes common checkpoint formats such as .pt,
.pth, .ckpt, and .safetensors, and also ignores local model files under
artifacts/models/.
Protein-level LLPS benchmark. |
Input-stream and weak-supervision ablations. |
Residue- and region-level DPR benchmark. |
DPR scanner input and bridge ablations. |
Representative DPR profiles on PhasePro proteins.
Flow Matching and DDPM phase-diagram comparison. |
Phase-conditioned generation and rescoring loop. |
Generated high-tendency peptide candidates. |
Generated low-tendency peptide candidates. |
TDP-43 point-mutation benchmark summary. |
Within-panel W-to-G multi-mutant trend. |
Citation information will be added after the public manuscript and artifact release are finalized.
This project is licensed under the Apache License, Version 2.0. See
LICENSE for details.