> ## 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.

# Ancillary Tables

> Schema reference for raw data tables in the data package

These are the underlying raw data tables snapshotted from the sequencing and alignment pipeline. Each table is stored as a directory of Parquet files.

***

## dim\_samples

Sample metadata for each physical sample in the experiment. Combines sample run execution data with plan-level identifiers and antigen information.

**Grain:** one row per `sample_id`.

| Column                      | Type      | Description                                                                                  |
| :-------------------------- | :-------- | :------------------------------------------------------------------------------------------- |
| `sample_id`                 | `string`  | Physical sample identifier.                                                                  |
| `sample_plan_id`            | `string`  | Planned sample part number from the run plan.                                                |
| `candidate_library_id`      | `string`  | Identifier of the candidate library consumed by this sample.                                 |
| `candidate_library_plan_id` | `string`  | Part number of the candidate library from the run plan.                                      |
| `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.                                                          |
| `antigen_concentration_nM`  | `float`   | Antigen concentration in nanomolar.                                                          |
| `translation_condition`     | `string`  | Translation condition used for the sample (e.g., reducing, disulfide).                       |
| `selection`                 | `boolean` | Whether the sample underwent binding selection. `false` indicates an expression-only sample. |

**Key relationships:**

* `sample_id` joins to `aligned_reads.sample_id`, `labeling_candidates_data.sample_id`.
* Binding samples (`selection = true`) correspond to `binding_umi_counts.binding_sample_id`.
* Expression samples (`selection = false`) correspond to `expression_umi_counts.expression_sample_id`.

***

## labeling\_candidates\_data

Candidate designs enriched with sample-run metadata, antigen information, and selection status. This table connects customer-provided candidate names and sequences with the experimental conditions under which they were tested.

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

| Column                     | Type      | Description                                                |
| :------------------------- | :-------- | :--------------------------------------------------------- |
| `sample_id`                | `string`  | The sample identifier from the run.                        |
| `candidate_name`           | `string`  | Customer-provided name for the candidate.                  |
| `candidate_sequence`       | `string`  | The full candidate sequence.                               |
| `sino_catalog_id`          | `string`  | Sino catalog identifier for the antigen.                   |
| `antigen_gene_name`        | `string`  | Gene name of the antigen.                                  |
| `antigen_sequence`         | `string`  | Amino acid sequence of the antigen.                        |
| `antigen_concentration_nM` | `float`   | The antigen concentration in nanomolar.                    |
| `selection`                | `boolean` | Whether this sample underwent binding selection.           |
| `candidate_id`             | `string`  | Blake-3 content digest of the reference fragment sequence. |

**Key relationships:**

* `sample_id` joins to `dim_samples.sample_id`.
* `candidate_id` is the shared candidate key across all tables.
* `candidate_name` is the customer-provided name that maps to the internal `candidate_id`.

***

## aligned\_reads

Full-length aligned reads with non-null UMI, filtered to the latest sequencing task attempt per sample and candidate. Joins alignment metrics with read sequences.

**Grain:** one row per `(read_id, sample_id)`.

| Column               | Type     | Description                                                                                                                                |
| :------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `read_id`            | `string` | UUID of the read coming off the sequencer.                                                                                                 |
| `sample_id`          | `string` | The sample identifier.                                                                                                                     |
| `candidate_id`       | `string` | Blake-3 hash of the reference DNA sequence that this read aligned to.                                                                      |
| `variant_id`         | `string` | Blake-3 digest of the reconstructed reference sequence after resolving non-UMI ambiguous N bases. Equals `candidate_id` when no ambiguity. |
| `umi`                | `string` | Unique Molecular Identifier extracted from the read.                                                                                       |
| `candidate_sequence` | `string` | The nucleotide sequence of the read.                                                                                                       |

**Key relationships:**

* `sample_id` joins to `dim_samples.sample_id`.
* `candidate_id` is the shared candidate key across all tables.

***

## binding\_umi\_counts

Per-UMI read counts for binding samples (samples where `selection = true`). Each row represents a unique combination of binding sample, candidate, variant, and UMI.

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

| Column              | Type      | Description                                                                                                                                |
| :------------------ | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `binding_sample_id` | `string`  | The binding sample identifier.                                                                                                             |
| `candidate_id`      | `string`  | Blake-3 content digest of the candidate reference sequence.                                                                                |
| `variant_id`        | `string`  | Blake-3 digest of the reconstructed reference sequence after resolving non-UMI ambiguous N bases. Equals `candidate_id` when no ambiguity. |
| `umi`               | `string`  | Unique Molecular Identifier extracted from the read.                                                                                       |
| `read_count`        | `integer` | Number of reads observed for this sample, candidate, and UMI.                                                                              |

**Key relationships:**

* `binding_sample_id` corresponds to `dim_samples.sample_id` where `selection = true`.
* `candidate_id` is the shared candidate key across all tables.

***

## expression\_umi\_counts

Per-UMI read counts for expression samples (samples where `selection = false`). Structure mirrors `binding_umi_counts`.

**Grain:** one row per `(expression_sample_id, candidate_id, variant_id, umi)`.

| Column                 | Type      | Description                                                                                                                                |
| :--------------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `expression_sample_id` | `string`  | The expression sample identifier.                                                                                                          |
| `candidate_id`         | `string`  | Blake-3 content digest of the candidate reference sequence.                                                                                |
| `variant_id`           | `string`  | Blake-3 digest of the reconstructed reference sequence after resolving non-UMI ambiguous N bases. Equals `candidate_id` when no ambiguity. |
| `umi`                  | `string`  | Unique Molecular Identifier extracted from the read.                                                                                       |
| `read_count`           | `integer` | Number of reads observed for this sample, candidate, and UMI.                                                                              |

**Key relationships:**

* `expression_sample_id` corresponds to `dim_samples.sample_id` where `selection = false`.
* `candidate_id` is the shared candidate key across all tables.