> ## Documentation Index
> Fetch the complete documentation index at: https://instance.bio/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Binding Scores

> Schema reference for computed binding score tables

These are the computed outputs of the data labeling pipeline.

***

## Binding Scores

**File:** `binding-scores-YYYYMMDD.parquet`

Aggregated binding scores per candidate and antigen pair. Replicate binding scores are averaged across replicates and pivoted so that each antigen concentration becomes its own column.

**Grain:** one row per unique `(candidate_id, sino_catalog_id)`.

### Fixed Columns

| Column                 | Type      | Description                                                        |
| :--------------------- | :-------- | :----------------------------------------------------------------- |
| `candidate_library_id` | `string`  | Identifier of the candidate library consumed by this sample.       |
| `candidate_name`       | `string`  | Customer-provided sequence name.                                   |
| `candidate_id`         | `string`  | Blake-3 content digest of the reference sequence.                  |
| `candidate_sequence`   | `string`  | The candidate amino acid sequence.                                 |
| `variant_id`           | `string`  | Blake-3 content digest of the variant sequence.                    |
| `variant_sequence`     | `string`  | The variant sequence.                                              |
| `sino_catalog_id`      | `string`  | Sino catalog identifier for the antigen used in the binding assay. |
| `antigen_gene_name`    | `string`  | Gene name of the antigen.                                          |
| `antigen_sequence`     | `string`  | Amino acid sequence of the antigen.                                |
| `targeting`            | `boolean` | Whether the candidate was designed to target this antigen.         |
| `is_expressed`         | `boolean` | Whether the candidate is expressed in at least one sample.         |

### Dynamic Concentration Columns

<Note>
  In addition to the fixed columns above, this table contains **dynamic columns** for each antigen concentration used in the experiment. The column names follow the pattern `binding_score_{conc}nM` and `binding_score_{conc}nM_std`.
</Note>

For example, if the experiment used concentrations of 10 nM, 50 nM, and 200 nM, you will see these additional columns:

| Column                    | Type    | Description                                            |
| :------------------------ | :------ | :----------------------------------------------------- |
| `binding_score_10nM`      | `float` | Mean log binding score at 10 nM.                       |
| `binding_score_10nM_std`  | `float` | Standard deviation of the log binding score at 10 nM.  |
| `binding_score_50nM`      | `float` | Mean log binding score at 50 nM.                       |
| `binding_score_50nM_std`  | `float` | Standard deviation of the log binding score at 50 nM.  |
| `binding_score_200nM`     | `float` | Mean log binding score at 200 nM.                      |
| `binding_score_200nM_std` | `float` | Standard deviation of the log binding score at 200 nM. |

***

## Replicate Binding Scores

**File:** `replicate-binding-scores-YYYYMMDD.parquet`

Per-replicate binding scores unrolled across antigen concentrations. Each row represents a single candidate measured in a specific expression/binding sample pair at a specific antigen concentration. Use this table to inspect replicate-level variation and per-sample UMI counts.

**Grain:** one row per `(candidate_id, binding_sample_id, antigen_concentration_nM)`.

| Column                     | Type      | Nullable | Description                                                    |
| :------------------------- | :-------- | :------- | :------------------------------------------------------------- |
| `candidate_library_id`     | `string`  | no       | Identifier of the candidate library consumed by this sample.   |
| `expression_sample_id`     | `string`  | no       | Sample identifier for the expression (base) sample.            |
| `binding_sample_id`        | `string`  | no       | Sample identifier for the binding (dose) sample.               |
| `candidate_name`           | `string`  | no       | Customer-provided sequence name.                               |
| `candidate_id`             | `string`  | no       | Blake-3 content digest of the reference sequence.              |
| `candidate_sequence`       | `string`  | no       | The candidate amino acid sequence.                             |
| `variant_id`               | `string`  | no       | Blake-3 content digest of the variant sequence.                |
| `variant_sequence`         | `string`  | no       | The variant sequence.                                          |
| `sino_catalog_id`          | `string`  | no       | Sino catalog identifier for the antigen.                       |
| `antigen_gene_name`        | `string`  | no       | Gene name of the antigen.                                      |
| `antigen_sequence`         | `string`  | no       | Amino acid sequence of the antigen.                            |
| `antigen_concentration_nM` | `float`   | no       | Antigen concentration in nanomolar.                            |
| `targeting`                | `boolean` | no       | Whether the candidate was designed to target this antigen.     |
| `is_expressed`             | `boolean` | no       | Whether the candidate is expressed.                            |
| `binding_score`            | `float`   | yes      | Log binding score. Null when UMI count thresholds are not met. |
| `expression_umi_count`     | `integer` | yes      | UMI count from the expression (base) sample.                   |
| `binding_umi_count`        | `integer` | yes      | UMI count from the binding (dose) sample.                      |

**Key relationships:**

* `expression_sample_id` and `binding_sample_id` both correspond to `dim_samples.sample_id`.
* `candidate_id` is the shared candidate key across all tables.