# Protein binder dataset schema — v0 (draft for discussion)

**Status:** proposed delivery format. The accompanying sample file, `sample_binders.csv`, is an illustration of the format only. Its sequences are masked and several columns hold illustrative values, so it is not a dataset. What it is built from is documented in the separate reference document.

## What one row is

One row = one construct, one replicate.

```
(target, binder sequence, mutation set vs parent)
  -> expression, solubility, Kd, kon, koff,
     thermostability, device signal change, pass/fail
```

Everything on a row is measured on the same physical construct in the same workflow. That is the property public data lacks: affinity, stability and expression usually live in different studies and cannot be joined.

## Design choices

1. **Columns grouped by meaning.** identity, design, assay, production, binding, fit quality, stability, device, outcome. Names follow Adaptyv's where a column overlaps (`kd`, `kon`, `koff`, `binding`, `binding_strength`, `confidence`, `method`, `MAE`, `rel_MAE`, `rmax_estimate`), so a mapping is trivial, but the file does not keep their column order. 30 columns in `sample_binders.csv`.
2. **Failures stay in the file.** A binder that does not bind is a row with `binding = false` and its measured numbers, not a missing row. Values past the detection limit use `kd_qualifier` (`>`, `<`) instead of a guessed number. Public data often drops failures or reports below-detection as an arbitrary value.
3. **Blank is not zero.** An empty cell means not measured or not reported. It never means no hit.
4. **Mutation coverage is explicit.** `parent_id`, `mutations` and `n_mutations` are columns, so a user can slice by coverage, check how dense a neighbourhood is, and validate intermediate model outputs against single and combined mutants.
6. **Provenance lives in a separate file.** Source, license and origin (public reference or pilot-measured) are not columns in the data file; they are documented in the separate reference document shipped alongside it.
7. **Device readout is a second label.** `delta_signal` is the construct's signal change in the sensor readout. A construct can bind tightly and still give no signal, so this is orthogonal to Kd. Populated only for sensor pilots.

## Files in a release

| File | Contents |
|---|---|
| `sample_binders.csv` | One row per construct per replicate. Columns in `data_dictionary.csv` |
| `aux/properties.csv` | Long format, one row per property per construct |
| `aux/replicate_info.csv` | Fit quality and provenance per replicate |
| `README.md` | Thresholds, ranges, license, known gaps |

## Thresholds (defaults, changeable per campaign)

- `binder`: Kd <= 1 uM
- `binding_strength`: strong <= 1 nM; medium <= 100 nM; weak <= 1 uM; else none
- `thermostable`: Tm1 >= 70 C
- `pass`: defined in the pilot contract, e.g. Kd within a target window AND expression >= Y

## What the sample shows, and does not show

The sample holds 117 rows. Every column is populated so the format can be read end to end. Sequences are masked. Some columns carry illustrative values chosen to show the type and range of data a campaign would deliver, not measurements. The reference document states which columns are which.

License note: the sample inherits CC BY-NC 4.0 from the source. It is a format and gap illustration, not a commercial dataset.

## Open choices for the pilot spec

- Target class: protein, small-molecule sensor, or both
- Scaffold and size of the mutational neighbourhood
- Which columns are required versus best-effort for the campaign
- Whether the buyer wants this as an eval benchmark (held-out, fixed split) or as training data. This changes the split and release rules, not the columns.