Germline Schema (Experimental)

Motivation

Understanding and cataloguing receptor germline genes and allele sequences is critical to the analysis of AIRR data. While the human set is relatively well understood in outline, although probably still far from complete, those of other species, even those that are relatively closely studied, is at a much earlier stage. There is an urgent need to define a standardised format for listing such genes, so that they can be shared between researchers and easily consumed by software tools.

Receptor Germline Schema

The receptor germline schema defines the data elements necessary to describe one or more receptor germline genes, together with supporting evidence. The fundamental object is the AlleleDescription, which describes a single gene or allele, containing the necessary details for the annotation of a rearranged sequence such as the location of CDRs (in the case of a V-gene) and framing information (in the case of a J-gene). AlleleDescription also contains fields to delineate RSS, and the leader regions of V-genes, should those be covered by the sequence provided.

Evidence supporting the gene or allele can be provided in linked UnrearrangedSequence and RearrangedSequence objects. Information represented in these objects will typically be stored in a repository: either an INSDC repository such as Genbank or SRA, or a lower-tier repository such as OGRDB. Please note that the key distinction between these object types is whether the V(D)J genes have rearranged, rather than the origin of the material, as mature B and T cells carry rearranged sequences in chromosomal DNA. It is most likely that supporting sequences will be UnrearrangedSequences, i.e. prior to rearrangement. In the case of a germline inference from a repertoire, the inferred germline sequence should be provided as a RearrangedSequence, if the evidence has been deposited in a repository.

For V-genes, an IMGT-gapped sequence (i.e.,. a sequence delineated in accordance with the IMGT numbering scheme) is provided in AlleleDescription. Other delineations, such as Chothia and Kabat, can be provided via linked SequenceDelineationV objects. A GermlineSet brings together multiple AlleleDescriptions from the same locus to form a curated set. The schema assumes that germline sets will be published by multiple repositories. A germline set may be uniquely referenced by means of the germline_set_ref, which is a composite field containing the repository id, germline set label, and version.

Gene and Allele Naming

AlleleDescription contains a label field, which should contain the accepted name for the field, as determined by the authors/curators of the record. The Nomenclature Committee of the International Union of Immunological Societies (IUIS) allocates gene symbols for receptor genes, and, if a gene symbol has been allocated, this should be used as the label. Where a gene symbol has not been allocated (for example, because the gene or allele has only recently been discovered, or because the available evidence does not meet IUIS standards, a ‘temporary label’ should be used. It is anticipated that publishers of gene sets will provide mechanisms to issue these temporary labels, and to allow researchers to review change history of AlleleDescriptions and GermlineSets. To provide consistency across research groups, the Germline Database Working Group of the AIRR Community is developing a community-wide approach to the allocation of temporary labels.

Genotypes

A GenotypeSet describes the specific receptor alleles found in a subject, and also identifies genes that are not found (this could be either because they are not present in the chromosomal locus, or because they are not expressed or expressed only at low levels). Depending on the data available and the inference method used, genotypes may contain haplotyping information, which may be full, or partial. As an example of partial haplotyping, the genotype may have been determined from genomic sequencing in which the sequence of the locus was assembled into contigs, but could not be fully assembled. In this case the co-location of alleles in each contig has been established, but the co-location across the entire locus can not be. Co-location is therefore indicated by means of the phasing parameter, which in this case would be assigned a different value for alleles on each contig.

MHC Genotypes

Similary to the IG/TR genotypes, the MHCGenotype amd MHCGenotypeSet objects describe the MHC alleles found in a subject. MHCGenotype objects assemble alleles from one class: MHC-I, MHC-II or MHC-nonclassical. The method used to determine the genotype can be provided in the mhc_genotyping_method field. As different methods might be use for the various classes, this field is located in the MHCGenotype object, not the MHCGenotypeSet.

The mhc_genotyping_method allows free-text descriptions, however data curators are asked to keep close to the following terms if applicable:

• PCR-based typing: Methods whose read-out is the amplification of specific sequences, but which do not provide sequence data by themselves. This includes SSP and SSOP.

• Sequencing-based typing: Clinical-grade NGS-based assays, providing high quality and resolution.

• Inference-based typing: Allele inferrence based on genome-wide DNA or RNA sequencing.

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.

Germline Set File Structure

The Germline Set file has a standardised structure that is utilized by all top-level AIRR Schema Objects and defined by the DataFile schema. It is intended to contan all information necessary to annotate receptor sequences derived from a single germline locus, and to be directly usable by annotation tools and other processing software.

The file must contain YAML or JSON representation of one or more GermlineSet objects, including the associated AlleleDescription objects. It may optionally include other associated objects: SequenceDelineationV, RearrangedSequence, UnrearrangedSequence, Acknowledgement. These should all be embedded into the overall GermlineSet as specified in the schema.

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

• The GermlineSet contains fields release_version, release_description and release_date, which are intended to be used for version identification, under the control of the authors of the GermlineSet as identified by the fields author, lab_name and lab_address. If the set is modified by a party other than these authors, that these 6 fields should be modified to reflect the authors of the modification, and their own version identication. These modifications MUST be made if the GermlineSet is, or is likely to become, public, in order to avoid confusion with the original set prior to modification. Repositories are encouraged to manage version fields automatically.

• The file can (optionally) contain an Info object, at the beginning of the file, based upon the Info schema in the OpenAPI 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 GermlineSet objects, using GermlineSet as the key to the list.

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

• There should be only one AlleleDescription for each allele in the list.

• Each AlleleDescription object should contain a top-level key/value pair for allele_description_id that uniquely identifies the allele description object in the file.

• Each GermlineSet object should contain a top-level key/value pair for germline_set_id that uniquely identifies the germline set object in the file.

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

• GermlineSet and AlleleDescription contain reference fields germline_set_ref and allele_description_ref. These are intended to be globally unique references (containing identifiers of the repository, object and version) that can be used in a query API.

• The structure is the same regardless of whether the data is stored in a file or retrieved from 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.

GermlineSet Fields

Download as TSV

Name	Type	Attributes	Definition
germline_set_id	string	required, identifier, nullable	Unique identifier of the GermlineSet within this file. Typically, generated by the repository hosting the record.
acknowledgements	array of Contributor	required, nullable	List of individuals whose contribution to the germline set should be acknowledged. Note that these are not necessarily identical with the authors on an associated manuscript or other scholarly communication. Further note that typically at least the three CRediT contributor roles “supervision”, “investigation” and “data curation” should be assigned. The coresponding author should be listed last.
release_version	number	required, nullable	Version number of this record, allocated automatically
release_description	string	required, nullable	Brief descriptive notes of the reason for this release and the changes embodied
release_date	string	required, nullable	Date of this release
germline_set_name	string	required, nullable	descriptive name of this germline set
germline_set_ref	string	required, nullable	Unique identifier of the germline set and version, in standardized form (Repo:Label:Version)
pub_ids	array of string	optional, nullable	Publications describing the germline set
species	Ontology	required	Binomial designation of subject’s species
species_subgroup	string	optional, nullable	Race, strain or other species subgroup to which this subject belongs
species_subgroup_type	string	optional, nullable
locus	string	required	Gene locus
allele_descriptions	array of AlleleDescription	required, nullable	list of allele_descriptions in the germline set
curation	string	optional, nullable	Curational notes on the GermlineSet. This can be used to give more extensive notes on the decisions taken than are provided in the release_description.

AlleleDescription Fields

Download as TSV

Name	Type	Attributes	Definition
allele_description_id	string	required, identifier, nullable	Unique identifier of this AlleleDescription within the file. Typically, generated by the repository hosting the record.
allele_description_ref	string	optional, nullable	Unique reference to the allele description, in standardized form (Repo:Label:Version)
acknowledgements	array of Contributor	required, nullable	List of individuals whose contribution to the gene description should be acknowledged. Note that these are not necessarily identical with the authors on an associated manuscript or other scholarly communication. Further note that typically at least the three CRediT contributor roles “supervision”, “investigation” and “data curation” should be assigned. The current maintainer should be listed first.
release_version	integer	required, nullable	Version number of this record, updated whenever a revised version is published or released
release_date	string	required, nullable	Date of this release
release_description	string	required, nullable	Brief descriptive notes of the reason for this release and the changes embodied
label	string	optional, nullable	The accepted name for this gene or allele following the relevant nomenclature. The value in this field should correspond to values in acceptable name fields of other schemas, such as v_call, d_call, and j_call fields.
sequence	string	required	Nucleotide sequence of the gene. This should cover the full length that is available, including where possible RSS, and 5’ UTR and lead-in for V-gene sequences.
coding_sequence	string	required, nullable	Nucleotide sequence of the core coding region, such as the coding region of a D-, J- or C- gene or the coding region of a V-gene excluding the leader.
aliases	array of string	optional, nullable	Alternative names for this sequence
locus	string	required	Gene locus
chromosome	integer	optional, nullable	chromosome on which the gene is located
sequence_type	string	required	Sequence type (V, D, J, C)
functional	boolean	required, nullable	True if the gene is functional, false if it is a pseudogene
inference_type	string	required, nullable	Type of inference(s) from which this gene sequence was inferred
species	Ontology	required	Binomial designation of subject’s species
species_subgroup	string	optional, nullable	Race, strain or other species subgroup to which this subject belongs
species_subgroup_type	string	optional, nullable
status	string	optional, nullable	Status of record, assumed active if the field is not present
subgroup_designation	string	optional, nullable	Identifier of the gene subgroup or clade, as (and if) defined
gene_designation	string	optional, nullable	Gene number or other identifier, as (and if) defined
allele_designation	string	optional, nullable	Allele number or other identifier, as (and if) defined
allele_similarity_cluster_designation	string	optional, nullable	ID of the similarity cluster used in this germline set, if designated
allele_similarity_cluster_member_id	string	optional, nullable	Membership ID of the allele within the similarity cluster, if a cluster is designated
j_codon_frame	integer	optional, nullable	Codon position of the first nucleotide in the ‘coding_sequence’ field. Mandatory for J genes. Not used for V or D genes. ‘1’ means the sequence is in-frame, ‘2’ means that the first bp is missing from the first codon, and ‘3’ means that the first 2 bp are missing.
gene_start	integer	optional, nullable	Co-ordinate in the sequence field of the first nucleotide in the coding_sequence field.
gene_end	integer	optional, nullable	Co-ordinate in the sequence field of the last gene-coding nucleotide in the coding_sequence field.
utr_5_prime_start	integer	optional, nullable	Start co-ordinate in the sequence field of the 5 prime UTR (V-genes only).
utr_5_prime_end	integer	optional, nullable	End co-ordinate in the sequence field of the 5 prime UTR (V-genes only).
leader_1_start	integer	optional, nullable	Start co-ordinate in the sequence field of L-PART1 (V-genes only).
leader_1_end	integer	optional, nullable	End co-ordinate in the sequence field of L-PART1 (V-genes only).
leader_2_start	integer	optional, nullable	Start co-ordinate in the sequence field of L-PART2 (V-genes only).
leader_2_end	integer	optional, nullable	End co-ordinate in the sequence field of L-PART2 (V-genes only).
v_rs_start	integer	optional, nullable	Start co-ordinate in the sequence field of the V recombination site (V-genes only).
v_rs_end	integer	optional, nullable	End co-ordinate in the sequence field of the V recombination site (V-genes only).
d_rs_3_prime_start	integer	optional, nullable	Start co-ordinate in the sequence field of the 3 prime D recombination site (D-genes only).
d_rs_3_prime_end	integer	optional, nullable	End co-ordinate in the sequence field of the 3 prime D recombination site (D-genes only).
d_rs_5_prime_start	integer	optional, nullable	Start co-ordinate in the sequence field of the 5 prime D recombination site (D-genes only).
d_rs_5_prime_end	integer	optional, nullable	End co-ordinate in the sequence field of 5 the prime D recombination site (D-genes only).
j_cdr3_end	integer	optional, nullable	In the case of a J-gene, the co-ordinate in the sequence field of the first nucelotide of the conserved PHE or TRP (IMGT codon position 118).
j_rs_start	integer	optional, nullable	Start co-ordinate in the sequence field of J recombination site (J-genes only).
j_rs_end	integer	optional, nullable	End co-ordinate in the sequence field of J recombination site (J-genes only).
j_donor_splice	integer	optional, nullable	Co-ordinate in the sequence field of the final 3’ nucleotide of the J-REGION (J-genes only).
v_gene_delineations	array of SequenceDelineationV	optional, nullable
unrearranged_support	array of UnrearrangedSequence	optional, nullable
rearranged_support	array of RearrangedSequence	optional, nullable
paralogs	array of string	optional, nullable	Gene symbols of any paralogs
curation	string	optional, nullable	Curational notes on the AlleleDescription. This can be used to give more extensive notes on the decisions taken than are provided in the release_description.
curational_tags	array of string	optional, nullable	Controlled-vocabulary tags applied to this description

RearrangedSequence Fields

Download as TSV

Name	Type	Attributes	Definition
sequence_id	string	required, identifier, nullable	Unique identifier of this RearrangedSequence within the file, typically generated by the repository hosting the schema, for example from the underlying ID of the database record.
sequence	string	required	nucleotide sequence
derivation	string	required, nullable	The class of nucleic acid that was used as primary starting material
observation_type	string	required	The type of observation from which this sequence was drawn, such as direct sequencing or inference from repertoire sequencing data.
curation	string	optional, nullable	Curational notes on the sequence
repository_name	string	required, nullable	Name of the repository in which the sequence has been deposited
repository_ref	string	optional, nullable	Queryable id or accession number of the sequence published by the repository
deposited_version	string	required, nullable	Version number of the sequence within the repository
sequence_start	integer	optional	Start co-ordinate of the sequence detailed in this record, within the sequence deposited
sequence_end	integer	optional	End co-ordinate of the sequence detailed in this record, within the sequence deposited

UnrearrangedSequence Fields

Download as TSV

Name	Type	Attributes	Definition
sequence_id	string	required, identifier, nullable	unique identifier of this UnrearrangedSequence within the file
sequence	string	required	Sequence of interest described in this record. Typically, this will include gene and promoter region.
curation	string	optional, nullable	Curational notes on the sequence
repository_name	string	required, nullable	Name of the repository in which the assembly or contig is deposited
repository_ref	string	optional, nullable	Queryable id or accession number of the sequence published by the repository
patch_no	string	optional, nullable	Genome assembly patch number in which this gene was determined
gff_seqid	string	required, nullable	Sequence (from the assembly) of a window including the gene and preferably also the promoter region.
gff_start	integer	required, nullable	Genomic co-ordinates of the start of the sequence of interest described in this record in Ensemble GFF version 3.
gff_end	integer	required, nullable	Genomic co-ordinates of the end of the sequence of interest described in this record in Ensemble GFF version 3.
strand	string	required, nullable	sense (+ or -)

SequenceDelineationV Fields

Download as TSV

Name	Type	Attributes	Definition
sequence_delineation_id	string	required, identifier, nullable	Unique identifier of this SequenceDelineationV within the file. Typically, generated by the repository hosting the record.
delineation_scheme	string	required, nullable	Name of the delineation scheme
unaligned_sequence	string	optional, nullable	entire V-sequence covered by this delineation
aligned_sequence	string	optional, nullable	Aligned sequence if this delineation provides an alignment. An aligned sequence should always be provided for IMGT delineations.
fwr1_start	integer	required, nullable	FWR1 start co-ordinate in the ‘unaligned sequence’ field
fwr1_end	integer	required, nullable	FWR1 end co-ordinate in the ‘unaligned sequence’ field
cdr1_start	integer	required, nullable	CDR1 start co-ordinate in the ‘unaligned sequence’ field
cdr1_end	integer	required, nullable	CDR1 end co-ordinate in the ‘unaligned sequence’ field
fwr2_start	integer	required, nullable	FWR2 start co-ordinate in the ‘unaligned sequence’ field
fwr2_end	integer	required, nullable	FWR2 end co-ordinate in the ‘unaligned sequence’ field
cdr2_start	integer	required, nullable	CDR2 start co-ordinate in the ‘unaligned sequence’ field
cdr2_end	integer	required, nullable	CDR2 end co-ordinate in the ‘unaligned sequence’ field
fwr3_start	integer	required, nullable	FWR3 start co-ordinate in the ‘unaligned sequence’ field
fwr3_end	integer	required, nullable	FWR3 end co-ordinate in the ‘unaligned sequence’ field
cdr3_start	integer	required, nullable	CDR3 start co-ordinate in the ‘unaligned sequence’ field
alignment_labels	array of string	optional, nullable	One string for each codon in the aligned_sequence indicating the label of that codon according to the numbering of the delineation scheme if it provides one.

GenotypeSet Fields

Download as TSV

Name	Type	Attributes	Definition
receptor_genotype_set_id	string	required, identifier, nullable	A unique identifier for this Receptor Genotype Set, typically generated by the repository hosting the schema, for example from the underlying ID of the database record.
genotype_class_list	array of Genotype	optional, nullable	List of Genotypes included in this Receptor Genotype Set.

Genotype Fields

Download as TSV

Name	Type	Attributes	Definition
receptor_genotype_id	string	required, identifier, nullable	A unique identifier within the file for this Receptor Genotype, typically generated by the repository hosting the schema, for example from the underlying ID of the database record.
locus	string	required	Gene locus
documented_alleles	array of DocumentedAllele	optional, nullable	List of alleles documented in reference set(s)
undocumented_alleles	array of UndocumentedAllele	optional, nullable	List of alleles inferred to be present and not documented in an identified GermlineSet
deleted_genes	array of DeletedGene	optional, nullable	Array of genes identified as being deleted in this genotype
inference_process	string	optional, nullable	Information on how the genotype was acquired. Controlled vocabulary.

MHCGenotypeSet Fields

Download as TSV

Name	Type	Attributes	Definition
mhc_genotype_set_id	string	required, identifier, nullable	A unique identifier for this MHCGenotypeSet
mhc_genotype_list	array of MHCGenotype	required, nullable	List of MHCGenotypes included in this set

MHCGenotype Fields

Download as TSV

Name	Type	Attributes	Definition
mhc_genotype_id	string	required, identifier, nullable	A unique identifier for this MHCGenotype, assumed to be unique in the context of the study
mhc_class	string	required	Class of MHC alleles described by the MHCGenotype
mhc_alleles	array of MHCAllele	required, nullable	List of MHC alleles of the indicated mhc_class identified in an individual
mhc_genotyping_method	string	optional, nullable	Information on how the genotype was determined. The content of this field should come from a list of recommended terms provided in the AIRR Schema documentation.