Quickstart - Instance

Instance datasets are delivered as Parquet files organized into table-specific folders (for example, ./data/binding_scores/binding_scores_20260103.parquet). You can load a table by passing its directory path.

Environment Setup

To set up an isolated Python virtual environment using uv:

# Create and activate an isolated virtual environment
uv venv
source .venv/bin/activate

# Install your preferred data analysis library
uv pip install pandas polars duckdb pyarrow

Read Dataset Tables

Store the path to your downloaded dataset in a data_dir variable so your scripts remain portable across environments. Pointing the reader to a table folder with a trailing slash loads the Parquet files in that folder. The examples below load the table and display the first 5 records.

Pandas
Polars
DuckDB

import pandas as pd

data_dir = "./data"

# Read the binding_scores folder directly and display the first 5 records
scores = pd.read_parquet(f"{data_dir}/binding_scores/")
print(scores.head(5))

import polars as pl

data_dir = "./data"

# Read the binding_scores folder and display the first 5 records
scores = pl.read_parquet(f"{data_dir}/binding_scores/")
print(scores.head(5))

import duckdb

data_dir = "./data"

# Query the Parquet folder directly with SQL and display the first 5 records
scores = duckdb.sql(f"select * from read_parquet('{data_dir}/binding_scores/') limit 5").df()
print(scores)

Screen and Rank Candidates by Binding Score

To prioritize binders, filter binding_scores for a designated target antigen, select candidates that were expressed (is_expressed = true) and designed for the target (targeting = true), and rank the candidates in descending order by binding score. The examples below rank candidates and display the first 10 top-ranking records.

Pandas
Polars
DuckDB

import pandas as pd

data_dir = "./data"
target_antigen_gene_name = "YOUR_ANTIGEN_GENE_NAME"  # Matches antigen_gene_name

scores = pd.read_parquet(f"{data_dir}/binding_scores/")

ranked_candidates = (
    scores.loc[
        (scores["antigen_gene_name"] == target_antigen_gene_name)
        & scores["is_expressed"]
        & scores["targeting"]
    ]
    .sort_values(by="binding_score_50nM", ascending=False)
).head(10)

# Display the first 10 top-ranking candidates
print(ranked_candidates)

import polars as pl

data_dir = "./data"
target_antigen_gene_name = "YOUR_ANTIGEN_GENE_NAME"

ranked_candidates = (
    pl.read_parquet(f"{data_dir}/binding_scores/")
    .filter(
        (pl.col("antigen_gene_name") == target_antigen_gene_name)
        & pl.col("is_expressed")
        & pl.col("targeting")
    )
    .sort(by="binding_score_50nM", descending=True, nulls_last=True)
).head(10)

# Display the first 10 top-ranking candidates
print(ranked_candidates)

import duckdb

data_dir = "./data"
target_antigen_gene_name = "YOUR_ANTIGEN_GENE_NAME"

# Query and display the first 10 top-ranking candidates
ranked_candidates = duckdb.execute(f"""
select *
from read_parquet('{data_dir}/binding_scores/')
where antigen_gene_name = ?
  and is_expressed = true
  and targeting = true
order by binding_score_50nM desc
limit 10
""", [target_antigen_gene_name]).df()

print(ranked_candidates)

Comparing Computational Model Predictions: If your team generated predictions before submitting your order, you can join your predictions table with binding_scores using candidate_name to compute rank correlation (such as Spearman’s

\rho

) and evaluate model performance against experimental ground truth.

Inspect Replicate Measurements and UMI Counts

If you want to inspect replicate scores for your top rankers, you can do so using replicate_binding_scores to see per-sample measurements and molecule counts (binding_umi_count). The examples below filter for replicate measurements corresponding to the top candidates identified above.

Pandas
Polars
DuckDB

import pandas as pd

data_dir = "./data"

# Reuse the top candidates from ranked_candidates above
key_cols = ["candidate_library_id", "sino_catalog_id", "variant_id"]
top_candidates = ranked_candidates[key_cols]

replicate_binding_scores = pd.read_parquet(f"{data_dir}/replicate_binding_scores/")

lead_replicates = (
    replicate_binding_scores[
        replicate_binding_scores.set_index(key_cols).index.isin(
            pd.MultiIndex.from_frame(top_candidates)
        )
    ]
    .sort_values(by=["candidate_id", "antigen_concentration_nM"])
)

print(lead_replicates)

import polars as pl

data_dir = "./data"

replicate_binding_scores = pl.scan_parquet(f"{data_dir}/replicate_binding_scores/")

lead_replicates = (
    replicate_binding_scores
    .join(
        ranked_candidates.lazy(),
        on=["candidate_library_id", "sino_catalog_id", "variant_id"],
        how="semi",
    )
    .sort(by=["candidate_id", "antigen_concentration_nM"])
    .collect()
)

print(lead_replicates)

import duckdb

data_dir = "./data"

lead_replicates = duckdb.execute(f"""
    select r.*
    from read_parquet('{data_dir}/replicate_binding_scores/') as r
    where exists (
        select 1
        from ranked_candidates as c
        where c.candidate_library_id = r.candidate_library_id
        and c.sino_catalog_id = r.sino_catalog_id
        and c.variant_id = r.variant_id
    )
    order by r.candidate_id, r.antigen_concentration_nM
""").df()

print(lead_replicates)

Best Practices for Joining Tables

When joining Instance tables, following standard join hygiene ensures data integrity and prevents unintended duplicate rows.

1. Join on a Table’s Complete Unique Grain

Always join two tables on the complete unique grain of at least one of the tables. Joining only on a subset of identifying keys (such as joining on candidate_id alone when multiple variants or concentrations exist) can lead to unintentional row duplication.

Table	Unique Grain Columns
`binding_scores`	`(candidate_library_id, sino_catalog_id, variant_id)`
`specificity_scores`	`(candidate_library_id, sino_catalog_id, variant_id)`
`replicate_binding_scores`	`(expression_sample_id, binding_sample_id, variant_id)`
`replicate_specificity_scores`	`(expression_sample_id, binding_sample_id, variant_id)`
`dim_samples`	`sample_id`
`dim_candidates`	`(sample_id, sino_catalog_id, antigen_concentration_nM)`
`aligned_reads`	`(read_id, sample_id)`
`binding_umi_counts`	`(binding_sample_id, variant_id, umi)`

2. Avoid Unnecessary Joins

Our score datasets (binding_scores and specificity_scores) are intentionally denormalized to include candidate names, full amino acid sequences, antigen catalog IDs, and antigen gene names. You do not need to join dim_samples or dim_candidates merely to access candidate sequences or target antigen names. Reserve table joins for cross-assay analysis, such as comparing binding_scores against specificity_scores.

​Environment Setup

​Read Dataset Tables

​Screen and Rank Candidates by Binding Score

​Inspect Replicate Measurements and UMI Counts

​Best Practices for Joining Tables

​1. Join on a Table’s Complete Unique Grain

​2. Avoid Unnecessary Joins