Repertoire Schema

A Repertoire is an abstract organizational unit of analysis that is defined by the researcher and consists of study metadata, subject metadata, sample metadata, cell processing metadata, nucleic acid processing metadata, sequencing run metadata, a set of raw sequence files, data processing metadata, and a set of Rearrangements. A Repertoire gathers all of this information together into a composite object, which can be easily accessed by computer programs for data entry, analysis and visualization.

A Repertoire is specific to a single subject otherwise it can consist of any number of samples (which can be processed in different ways), any number of raw sequence files, and any number of rearrangements. It can also consist of any number of data processing metadata objects that describe the processing of raw sequence files into Rearrangements.

Typically, a Repertoire corresponds to the biological concept of the immune repertoire for that single subject which the researcher experimentally measures and computationally analyzes. However, researchers can have different interpretations about what constitutes the biological immune repertoire; therefore, the Repertoire schema attempts to be flexible and broadly useful for all AIRR-seq studies.

Another researcher can take the same raw sequencing data and associated metadata and create their own Repertoire that is different from the original researcher’s. A common example is to define a repertoire that is a subset such as “productive rearrangements for IGHV4” whereas the original researcher defined a more generic “B cell repertoire”. This new Repertoire would have much of the same metadata as the original Repertoire, except associated with a different study, and with additional information in the data processing metadata that describes how the rearrangements were filtered down to just the “productive rearrangements for IGHV4”. Likewise, another researcher may get access to the original biosample material and perform their own sample processing and sequencing, which also would be a new Repertoire. That new Repertoire could combine samples from the original researcher’s Repertoire with the new sample data as a large dataset for the subject.

Multiple Data Processing on a Repertoire

Data processing can be a complicated multi-stage process. Documenting the process in a formal way is challenging because of the diversity of actions that may be performed. The MiAIRR standard requires documentation of the process but in an informal way with free text descriptions. A Repertoire might undergo multiple different data processing for any number of reasons, e.g. to compare the results from different toolchains, or to compare different settings for the same toolchain.

It is expected that all of the Samples of a Repertoire will be processed together within a DataProcessing. That is, a DataProcessing that only uses some but not all samples in a Repertoire could be confusing to users and appear as though data is missing. Likewise, processing some samples within a Repertoire with one DataProcessing and the remaining samples with a different DataProcessing could also confuse users. Because DataProcessing is unstructured information, it is not possible to validate that all Samples in a Repertoire are being processed together, so this expectation cannot be strictly enforced.

Having multiple DataProcessing for a Repertoire will create multiple sets of Rearrangements that are distinct and separate from each other. Analysis tools need to be careful not to mix these sets of Rearrangements from different DataProcessing because it can generate incorrect results. The identifier data_processing_id was added so Rearrangements can identify their specific DataProcessing.

Linking Data

Each Repertoire has a unique repertoire_id identifier. This identifier should be globally unique so that repertoires from multiple studies can be combined together without conflict. The repertoire_id is used to link other AIRR data to a Repertoire. Specifically, the Rearrangements Schema includes repertoire_id for referencing the specific Repertoire for that Rearrangement.

If a Repertoire has multiple DataProcessing then data_processing_id should be used to distinguish the appropriate DataProcessing within the Repertoire. The Rearrangements contains data_processing_id for this purpose. The data_processing_id is only unique within a Repertoire so repertoire_id should first be used to get the appropriate Repertoire object and then data_processing_id used to acquire the appropriate DataProcessing.

It is expected that typical Repertoires might only have a single DataProcessing, in which case repertoire_id and data_processing_id will be semantically equivalent and only the former should be used.

If a Repertoire has multiple sample processing objects in the sample array then sample_processing_id should be used to distinguish the the approrpiate sample processing object within the Repertoire. The Rearrangement object can contain a sample_processing_id to uniquely identify a sample processing object within a Repertoire. Like data_processing_id, the sample_processing_id is only unique within the Repertoire so repertoire_id should first be used to get the appropiate Repertoire object and then sample_processing_id should be used to determine the appropiate sample processing object that is associated with the Rearrangement. If the Rearrangement object does not have a sample_processing_id then it can be assumed that the rearrangement is associated with all of the samples in the Repertoire (e.g. the rearrangement is a collapsed rearrangement across multiple samples).

It is expected that Repertoires might often have a single sample processing object, in which case repertoire_id and sample_processing_id will be semantically equivalent and only the former should be used.

Finally, if it is necessary to link a Rearrangement object with a unique pairing of sample processing and DataProcessing, the repertoire_id of the Rearrangement object should be used to identify the correct Repertoire object and then the data_processing_id should be used to identify the correct DataProcessing metadata and the sample_processing_id should be used to identify the correct sample processing metadata within that Repertoire.

Duality between Repertoires and Rearrangements

There is an important duality relationship between Repertoires and Rearrangements, specifically with the experimental protocols described in the Repertoire versus the annotations on Rearrangements. A Repertoire defines an experimental design for what a researcher intends to measure or observe, while the Rearrangements are what was actually measured and observed. Technically, the border between the two occurs at sequencing, that is when the biological physical entity (prepared DNA) is measured and recorded as information (nucleotide sequence).

This duality is important when considering how to answer certain questions. For example, locus for Rearrangements may have the value “IGH” which indicates that B cell heavy chain receptors were measured, yet the Repertoire might have “T cell” in cell_subset which indicates the researcher intended to measure T cells. This conflict between the two indicates something is wrong. Differences can occur in many ways, as with errors in the experimental protocol, or data processing might have incorrectly processed the raw sequencing data leading to invalid annotations.

File Format Specification

Files are YAML/JSON with a structure defined below. Files should be encoded as UTF-8. Identifiers are case-sensitive. Files should have the extension .yaml, .yml, or .json.

File Structure

  • The file as a whole is considered a dictionary (key/value pair) structure with the keys Info and Repertoire.

  • The file can (optionally) contain an Info object, at the beginning of the file, based upon the Info schema in the OpenAPI V2 specification. If provided, version in Info should reference the version of the AIRR schema for the file.

  • The file should correspond to a list of Repertoire objects, using Repertoire as the key to the list.

  • Each Repertoire object should contain a top-level key/value pair for repertoire_id that uniquely identifies the repertoire.

  • Some fields require the use of a particular ontology or controlled vocabulary.

  • The structure is the same regardless of whether the data is stored in a file or a data repository. For example, The ADC API will return a properly structured JSON object that can be saved to a file and used directly without modification.

Repertoire Fields

Download as TSV

Name

Type

Attributes

Definition

repertoire_id

string

optional, identifier, nullable

Identifier for the repertoire object. This identifier should be globally unique so that repertoires from multiple studies can be combined together without conflict. The repertoire_id is used to link other AIRR data to a Repertoire. Specifically, the Rearrangements Schema includes repertoire_id for referencing the specific Repertoire for that Rearrangement.

repertoire_name

string

optional, nullable

Short generic display name for the repertoire

repertoire_description

string

optional, nullable

Generic repertoire description

study

Study

required

Study object

subject

Subject

required

Subject object

sample

array

required

List of Sample objects

data_processing

array of DataProcessing

required

List of Data Processing objects

Study Fields

Download as TSV

Name

Type

Attributes

Definition

study_id

string

required, nullable

Unique ID assigned by study registry

study_title

string

required, nullable

Descriptive study title

study_type

Ontology

required, nullable

Type of study design

study_description

string

optional, nullable

Generic study description

inclusion_exclusion_criteria

string

required, nullable

List of criteria for inclusion/exclusion for the study

grants

string

required, nullable

Funding agencies and grant numbers

study_contact

string

optional, nullable

Full contact information of the contact persons for this study This should include an e-mail address and a persistent identifier such as an ORCID ID.

collected_by

string

required, nullable

Full contact information of the data collector, i.e. the person who is legally responsible for data collection and release. This should include an e-mail address.

lab_name

string

required, nullable

Department of data collector

lab_address

string

required, nullable

Institution and institutional address of data collector

submitted_by

string

required, nullable

Full contact information of the data depositor, i.e. the person submitting the data to a repository. This is supposed to be a short-lived and technical role until the submission is relased.

pub_ids

string

required, nullable

Publications describing the rationale and/or outcome of the study

keywords_study

array of string

required, nullable

Keywords describing properties of one or more data sets in a study

Subject Fields

Download as TSV

Name

Type

Attributes

Definition

subject_id

string

required, nullable

Subject ID assigned by submitter, unique within study

synthetic

boolean

required

TRUE for libraries in which the diversity has been synthetically generated (e.g. phage display)

species

Ontology

required

Binomial designation of subject’s species

organism

Ontology

DEPRECATED

Binomial designation of subject’s species

sex

string

required, nullable

Biological sex of subject

age_min

number

required, nullable

Specific age or lower boundary of age range.

age_max

number

required, nullable

Upper boundary of age range or equal to age_min for specific age. This field should only be null if age_min is null.

age_unit

Ontology

required, nullable

Unit of age range

age_event

string

required, nullable

Event in the study schedule to which Age refers. For NCBI BioSample this MUST be sampling. For other implementations submitters need to be aware that there is currently no mechanism to encode to potential delta between Age event and Sample collection time, hence the chosen events should be in temporal proximity.

age

string

DEPRECATED

ancestry_population

string

required, nullable

Broad geographic origin of ancestry (continent)

ethnicity

string

required, nullable

Ethnic group of subject (defined as cultural/language-based membership)

race

string

required, nullable

Racial group of subject (as defined by NIH)

strain_name

string

required, nullable

Non-human designation of the strain or breed of animal used

linked_subjects

string

required, nullable

Subject ID to which Relation type refers

link_type

string

required, nullable

Relation between subject and linked_subjects, can be genetic or environmental (e.g.exposure)

diagnosis

array of Diagnosis

optional

Diagnosis information for subject

germline

object

optional, nullable

Germline for this subject, if known, by germline class.

Diagnosis Fields

Download as TSV

Name

Type

Attributes

Definition

study_group_description

string

required, nullable

Designation of study arm to which the subject is assigned to

disease_diagnosis

Ontology

required, nullable

Diagnosis of subject

disease_length

string

required, nullable

Time duration between initial diagnosis and current intervention

disease_stage

string

required, nullable

Stage of disease at current intervention

prior_therapies

string

required, nullable

List of all relevant previous therapies applied to subject for treatment of Diagnosis

immunogen

string

required, nullable

Antigen, vaccine or drug applied to subject at this intervention

intervention

string

required, nullable

Description of intervention

medical_history

string

required, nullable

Medical history of subject that is relevant to assess the course of disease and/or treatment

Sample Fields

Download as TSV

Name

Type

Attributes

Definition

sample_id

string

required, nullable

Sample ID assigned by submitter, unique within study

sample_type

string

required, nullable

The way the sample was obtained, e.g. fine-needle aspirate, organ harvest, peripheral venous puncture

tissue

Ontology

required, nullable

The actual tissue sampled, e.g. lymph node, liver, peripheral blood

anatomic_site

string

required, nullable

The anatomic location of the tissue, e.g. Inguinal, femur

disease_state_sample

string

required, nullable

Histopathologic evaluation of the sample

collection_time_point_relative

number

required, nullable

Time point at which sample was taken, relative to Collection time event

collection_time_point_relative_unit

Ontology

required, nullable

Unit of Sample collection time

collection_time_point_reference

string

required, nullable

Event in the study schedule to which Sample collection time relates to

biomaterial_provider

string

required, nullable

Name and address of the entity providing the sample

Tissue and Cell Processing Fields

Download as TSV

Name

Type

Attributes

Definition

tissue_processing

string

required, nullable

Enzymatic digestion and/or physical methods used to isolate cells from sample

cell_subset

Ontology

required, nullable

Commonly-used designation of isolated cell population

cell_phenotype

string

required, nullable

List of cellular markers and their expression levels used to isolate the cell population

cell_species

Ontology

optional, nullable

Binomial designation of the species from which the analyzed cells originate. Typically, this value should be identical to species, if which case it SHOULD NOT be set explicitly. Howver, there are valid experimental setups in which the two might differ, e.g. chimeric animal models. If set, this key will overwrite the species information for all lower layers of the schema.

single_cell

boolean

required, nullable

TRUE if single cells were isolated into separate compartments

cell_number

integer

required, nullable

Total number of cells that went into the experiment

cells_per_reaction

integer

required, nullable

Number of cells for each biological replicate

cell_storage

boolean

required, nullable

TRUE if cells were cryo-preserved between isolation and further processing

cell_quality

string

required, nullable

Relative amount of viable cells after preparation and (if applicable) thawing

cell_isolation

string

required, nullable

Description of the procedure used for marker-based isolation or enrich cells

cell_processing_protocol

string

required, nullable

Description of the methods applied to the sample including cell preparation/ isolation/enrichment and nucleic acid extraction. This should closely mirror the Materials and methods section in the manuscript.

Nucleic Acid Processing Fields

Download as TSV

Name

Type

Attributes

Definition

template_class

string

required

The class of nucleic acid that was used as primary starting material for the following procedures

template_quality

string

required, nullable

Description and results of the quality control performed on the template material

template_amount

number

required, nullable

Amount of template that went into the process

template_amount_unit

Ontology

required, nullable

Unit of template amount

library_generation_method

string

required

Generic type of library generation

library_generation_protocol

string

required, nullable

Description of processes applied to substrate to obtain a library that is ready for sequencing

library_generation_kit_version

string

required, nullable

When using a library generation protocol from a commercial provider, provide the protocol version number

pcr_target

array of PCRTarget

optional

If a PCR step was performed that specifically targets the IG/TR loci, the target and primer locations need to be provided here. This field holds an array of PCRTarget objects, so that multiplex PCR setups amplifying multiple loci at the same time can be annotated using one record per locus. PCR setups not targeting any specific locus must not annotate this field but select the appropriate library_generation_method instead.

complete_sequences

string

required

To be considered complete, the procedure used for library construction MUST generate sequences that 1) include the first V gene codon that encodes the mature polypeptide chain (i.e. after the leader sequence) and 2) include the last complete codon of the J gene (i.e. 1 bp 5’ of the J->C splice site) and 3) provide sequence information for all positions between 1) and 2). To be considered complete & untemplated, the sections of the sequences defined in points 1) to 3) of the previous sentence MUST be untemplated, i.e. MUST NOT overlap with the primers used in library preparation. mixed should only be used if the procedure used for library construction will likely produce multiple categories of sequences in the given experiment. It SHOULD NOT be used as a replacement of a NULL value.

physical_linkage

string

required

In case an experimental setup is used that physically links nucleic acids derived from distinct Rearrangements before library preparation, this field describes the mode of that linkage. All hetero_* terms indicate that in case of paired-read sequencing, the two reads should be expected to map to distinct IG/TR loci. *_head-head refers to techniques that link the 5’ ends of transcripts in a single-cell context. *_tail-head refers to techniques that link the 3’ end of one transcript to the 5’ end of another one in a single-cell context. This term does not provide any information whether a continuous reading-frame between the two is generated. *_prelinked refers to constructs in which the linkage was already present on the DNA level (e.g. scFv).

PCR Target Locus Fields

Download as TSV

Name

Type

Attributes

Definition

pcr_target_locus

string

required, nullable

Designation of the target locus. Note that this field uses a controlled vocubulary that is meant to provide a generic classification of the locus, not necessarily the correct designation according to a specific nomenclature.

forward_pcr_primer_target_location

string

required, nullable

Position of the most distal nucleotide templated by the forward primer or primer mix

reverse_pcr_primer_target_location

string

required, nullable

Position of the most proximal nucleotide templated by the reverse primer or primer mix

Raw Sequence Data Fields

Download as TSV

Name

Type

Attributes

Definition

file_type

string

required, nullable

File format for the raw reads or sequences

filename

string

required, nullable

File name for the raw reads or sequences. The first file in paired-read sequencing.

read_direction

string

required, nullable

Read direction for the raw reads or sequences. The first file in paired-read sequencing.

read_length

integer

required, nullable

Read length in bases for the first file in paired-read sequencing

paired_filename

string

required, nullable

File name for the second file in paired-read sequencing

paired_read_direction

string

required, nullable

Read direction for the second file in paired-read sequencing

paired_read_length

integer

required, nullable

Read length in bases for the second file in paired-read sequencing

Sequencing Run Fields

Download as TSV

Name

Type

Attributes

Definition

sequencing_run_id

string

required, nullable

ID of sequencing run assigned by the sequencing facility

total_reads_passing_qc_filter

integer

required, nullable

Number of usable reads for analysis

sequencing_platform

string

required, nullable

Designation of sequencing instrument used

sequencing_facility

string

required, nullable

Name and address of sequencing facility

sequencing_run_date

string

required, nullable

Date of sequencing run

sequencing_kit

string

required, nullable

Name, manufacturer, order and lot numbers of sequencing kit

sequencing_files

RawSequenceData

optional

Set of sequencing files produced by the sequencing run

Data Processing Fields

Download as TSV

Name

Type

Attributes

Definition

data_processing_id

string

optional, identifier, nullable

Identifier for the data processing object.

primary_annotation

boolean

optional, identifier

If true, indicates this is the primary or default data processing for the repertoire and its rearrangements. If false, indicates this is a secondary or additional data processing.

software_versions

string

required, nullable

Version number and / or date, include company pipelines

paired_reads_assembly

string

required, nullable

How paired end reads were assembled into a single receptor sequence

quality_thresholds

string

required, nullable

How sequences were removed from (4) based on base quality scores

primer_match_cutoffs

string

required, nullable

How primers were identified in the sequences, were they removed/masked/etc?

collapsing_method

string

required, nullable

The method used for combining multiple sequences from (4) into a single sequence in (5)

data_processing_protocols

string

required, nullable

General description of how QC is performed

data_processing_files

array of string

optional, nullable

Array of file names for data produced by this data processing.

data_processing_germline

object

optional, nullable

Germline used for this data processing process

germline_database

string

required, nullable

Source of germline V(D)J genes with version number or date accessed.

analysis_provenance_id

string

optional, nullable

Identifier for machine-readable PROV model of analysis provenance