Immune Assay Data Block Guide

This document outlines the standard for a block that integrates functional immune assay data (e.g., from ELISA, SPR, or cell-based functional screens) with VDJ clonotype datasets. By adhering to this standard, an assay data block can link experimental measurements to specific clonotypes, making the data queryable and available for downstream analysis.

Overview

The diagram below illustrates how an assay data block fits into a VDJ analysis pipeline. It consumes a VDJ dataset and a user-provided table of assay results. It then aligns the sequences and exports a new p-frame containing the original clonotypes annotated with their corresponding assay data.

 Blocks                                 Result pool
                                       ┌───────────
             ┌─────────────────────────┤
             │                         │
             v                         │
 ╔═══════════════════════╗   exports   │
 ║   Clonotyping Block   ║───────>─────┤ Abundance & Properties
 ╚═══════════════════════╝             │ ----------------------
             │                         │
             │                         ├ [clonotypeKey] -> sequence
             │                         │
             v                         │
 ╔═══════════════════════╗             │
 ║  Immune Assay Block   ║───────>─────┤ Enriched Properties
 ╚═══════════════════════╝   exports   │ -------------------
             │                         │
             │                         ├ [clonotypeKey] -> assay results (EC50 etc.)
             │                         ├ [clonotypeKey] -> alignment scores
             v                         │
 ╔═══════════════════════╗             │
 ║  Downstream Analysis  ║             │
 ╚═══════════════════════╝             │

Inputs

A standard assay data block requires two main inputs:

1. VDJ Dataset: A compliant VDJ dataset (either bulk or single-cell), identified by its anchor p-column. The user must also specify which sequence p-column within this dataset (e.g., CDRH3 amino acid sequence) should be used for matching.
2. Assay Data File: A user-uploaded table (e.g., CSV or TSV) containing the experimental results. This file must contain:
   • A column with receptor sequences.
   • One or more columns with experimental measurements (e.g., EC50, MFI).

Block exports (for downstream analysis)

The block's main export is an augmented version of the input VDJ p-frame. It adds the assay measurements and alignment statistics as new property p-columns, keyed by the original [clonotypeKey] or [scClonotypeKey].

Assay result p-columns

For each measurement column in the user's input file (e.g., EC50), the block generates a corresponding p-column.

• Name: The p-column name should be the same as the header from the input file.
• Specification (EC50 example):

  name: "EC50" 
  valueType: Float
  axesSpec:
    - name: pl7.app/vdj/clonotypeKey # or scClonotypeKey
      type: String
  annotations:
    pl7.app/label: "EC50"
    pl7.app/isScore: "true"
    pl7.app/score/rankingOrder: "increasing" # Lower EC50 is better

Alignment statistics p-columns

The block must also export p-columns describing the quality of the sequence alignment.

• pl7.app/alignment/bitScore: The alignment bit score.
• pl7.app/alignment/evalue: The alignment E-value.
• pl7.app/alignment/pident: The percentage of identical matches in the alignment.

Summary of standard exports

The following table provides a summary of all standard p-columns that a compliant immune assay data block adds to the input VDJ dataset.

P-Column Name	Description	Axes	Requirement
User-Defined Assay Data
(User-defined)	Experimental measurement (e.g., EC50, MFI).	[clonotypeKey]	Required
Alignment Statistics
pl7.app/alignment/bitScore	The alignment bit score from the sequence search.	[clonotypeKey]	Required
pl7.app/alignment/evalue	The alignment E-value from the sequence search.	[clonotypeKey]	Required
pl7.app/alignment/pident	Percentage of identical matches in the alignment.	[clonotypeKey]	Required