README.md

---
language: en
license: mit
tags:
  - biology
  - protein
  - FRET
  - machine-learning
  - esm
  - protein-engineering
library_name: tensorflow
---

# FRET-FACS — FRET classification pipeline

Scripts, pre-trained models, and datasets for binary FRET classifiers (`highFRET` vs `lowFRET`) on designed protein variants, plus utilities for ESM embedding extraction and structure-based descriptors.

**Paper:** [Learning the structural diversity in random protein sequence space](https://www.biorxiv.org/content/10.64898/2026.04.30.722084v1) (bioRxiv 2026; [doi:10.64898/2026.04.30.722084](https://doi.org/10.64898/2026.04.30.722084)). See [LICENSE](LICENSE) for terms and the recommended citation.

**Hub repository:** [huggingface.co/neuwirtt/FRET-FACS](https://huggingface.co/neuwirtt/FRET-FACS)

## Download

```bash
pip install -U "huggingface_hub[cli]"
hf download neuwirtt/FRET-FACS --local-dir FRET-FACS
cd FRET-FACS
```

## Quick start

**Install evaluation dependencies:**

```bash
pip install -r evaluation/requirements.txt
```

**Evaluate** with bundled weights (paths are relative to the repo root):

```bash
python evaluation/evaluate_nn_one_hot.py --fasta your_seqs.fa --output eval_out/
```

**Train** a new model (example — one-hot neural net):

```bash
pip install -r models/requirements_models_training.txt
python models/nn_one_hot.py --fasta seqs.fa --csv labels.csv --output run_out/
```

**ESM models** require per-sequence `.pt` embedding files — extract them first (`extract_embeddings/`), then train or point evaluators at `--emb-mean` / `--emb-token`.

See the README in each subdirectory for full CLI options, CSV column schemas, and artifact naming.

## Repository layout

| Directory | Purpose |
|-----------|---------|
| [`models/`](models/) | Training scripts (one-hot NN/RF, ESM NN/RF, composition logistic-regression baseline) |
| [`evaluation/`](evaluation/) | Inference and supervised scoring on new FASTA inputs using checkpoints in `weights/` |
| [`weights/`](weights/) | Pre-trained checkpoints, calibration CSVs, and reproducibility metadata (see `weights/README.md`) |
| [`extract_embeddings/`](extract_embeddings/) | Extract fair-esm `.pt` embedding caches for ESM-based models |
| [`datasets/`](datasets/) | FRET variant labels and natural-protein reference FASTAs |
| [`structure_predictions_processing/`](structure_predictions_processing/) | Batch PDB + DSSP structure statistics (`pdb_dssp_analyses.py`) |
| [`similarity_split/`](similarity_split/) | MMseqs2 cluster-based train/test split (`mmseqs_cluster_split.py`) |

## `weights/` bundles

| Subdirectory | Evaluator |
|--------------|-----------|
| `weights/nn_one_hot/` | `evaluation/evaluate_nn_one_hot.py` |
| `weights/nn_mean_pertoken_esm/` | `evaluation/evaluate_nn_mean_pertoken_esm.py` |
| `weights/rf_one_hot/` | `evaluation/evaluate_rf_one_hot.py` |
| `weights/rf_mean_pertoken_esm/` | `evaluation/evaluate_rf_mean_pertoken_esm.py` |

Each bundle contains inference artifacts plus `model_parameters.json`, `random_seed.txt`, and hyperparameter CSVs for reproducibility. See [`weights/README.md`](weights/README.md) for the full file list.

**Composition LR** is not pre-bundled — train with `models/lr_sequence_composition_baseline.py`, then pass `--model-dir` to `evaluation/evaluate_lr_sequence_composition.py`.

**ESM embedding caches** (`.pt` per FASTA header) are not included; create them with `extract_embeddings/` and place or symlink `mean_embeddings_pt/` and `per_token_embeddings_pt/` next to the ESM checkpoint dirs.

## Datasets

| File | Rows | What it contains |
|------|------|------------------|
| `datasets/full_dataset_mmseq.csv` | ~94k | **Full** MMseq-clustered table: `split=train` (~77k) + `split=test` (~17k) |
| `datasets/test_only_mmseq.csv` | ~17k | **Held-out test split only** (balanced highFRET/lowFRET); same rows as `split=test` in the full file |

- `datasets/natural_proteins/` — SCOP globular sets and UniProt coiled-coil reference FASTAs

## Citation

```bibtex
@article{Buchel2026structural,
  title   = {Learning the structural diversity in random protein sequence space},
  author  = {Buchel, Filip and Neuwirthova, Tereza and Tureckiova, Theodora and
             Fuertes, Gustavo and Benda, Ales and Panek, Dalibor and Fricek, Matus and
             AlQuraishi, Mohammed and Hlouchova, Klara},
  journal = {bioRxiv},
  year    = {2026},
  doi     = {10.64898/2026.04.30.722084},
  url     = {https://www.biorxiv.org/content/10.64898/2026.04.30.722084v1}
}
```