Package 'HLAtools'

Description

Modifies cDNA alignment objects that are missing "AA codon" lines to include these lines in the correct location with the correct codon position information.

Usage

addCodonLine(cDNAalign, firstPos, afterLine = 8, codons = 25)

Arguments

Value

A complete cDNA alignment data frame that includes "AA codon" rows.

Note

For internal HLAtools use.

Description

Applies buildAlignments() to build a set of alignments for loci supported in the ANHIG/IMGTHLA GitHub repository.

Usage

alignmentFull(loci = "all", alignType = "all", version = HLAgazeteer$version)

Arguments

Value

A list object containing data frames of protein (prot), codon (codon), coding nucleotide (nuc), or genomic nucleotide (gen) alignments, for specified genes in the specified IPD-IMGT/HLA Database release, along with the pertinent reference database release.

Note

AlignmentFull() must be run to build the 'HLAalignments' object (HLAalignments <- alignmentFull()) before other functions that use alignments can be used, and therefore requires internet access.

Depending on local download speeds, building all available alignments for all loci can take several minutes.

Prior to IPD-IMGT/HLA Database release version 3.24.0, the HLA-DP and HLA-DQ sequence alignment files in the IPD-IMGT/HLA GitHub Repository did not all include a numerical suffix in the gene name (e.g., the protein sequence alignment file for the DQA1 gene was named 'DQA_prot.txt') because alignment files for the DPA2, DPB2, DQA2 and DQB2 genes had not been made available. Building DPA1, DPB1, DQA1, and DQB1 sequence alignments from releases prior to 3.24.0 require using a gene name that does not include the numerical suffix.

Description

Searches ANHIG/IMGT-HLA alignments and returns protein, codons or nucleotide sequences for a submitted allele name and position(s).

Usage

alignmentSearch(alignType, allelename, positions, prefix = TRUE, sep = "~")

Arguments

Value

A character string containing the corresponding peptide, codon or nucleotide sequence for each position in 'positions' for 'allelename'. A sequence is not returned if 'allelename' is not not found in the pertinent alignment. A position will be empty if 'allelename' does not have a value at the specified position.

Note

This function requires that the HLAalignments object has been populated with alignments via the alignmentFull() function.

Indel positions must be text-formatted (e.g. "607.12"). C.f., alignmentSearch("nuc","DRB115:07:01",11:22) vs alignmentSearch("nuc","DRB111:250N",c(605,"607.1","607.12",608)).

Description

A large list object of two elements. The first element contains version information. The second element contains all releases of allele name lists in the IMGT/HLA database. This object is built by the UpdateAlleleListHistory() function.

Usage

data(alleleListHistory)

Format

A large list of 2 elements that identify the table of allele names for each IPD-IMGT/HLA reference Database release and the source release

• (Version: the Date and IPD-IMGT HLA Release version under which the alleleListHistory object was made)

• (AlleleListHistory: a dataframe version of the alleleListHistory.txt file)

Source

https://raw.githubusercontent.com/ANHIG/IMGTHLA/Latest/Allelelist_history.txt

Description

Trims an HLA allele name to a specified number of fields or number of digits, depending on the nomenclature epoch. Expression variant suffixes in full-length allele names can be appended to truncated allele names.

Usage

alleleTrim(allele, resolution, version = 3, append = FALSE)

Arguments

Value

A character string of the trimmed allele name, shortened according to the input parameters.

Note

Expression variant suffixes will not be removed from full-length allele names that have fewer than four fields or eight digits.

Examples

alleleTrim(allele = "A*03:01:01", resolution = 2)
alleleTrim(allele = "A*030101", resolution = 2,version = 2)
alleleTrim(allele = "A*0303N",resolution = 1,version = 1, append = TRUE)
alleleTrim("HLA-A*24020102L",resolution = 3,version = 2, append = TRUE)

Description

Applies atlasMaker() to build a set of 'atlases' identifying the gene-feature (exon, intron, and UTR) boundaries in the protein, coding nucleotide, and genomic nucleotide alignments of all HLA loci.

Usage

atlasFull(version = "Latest")

Arguments

Value

A list object containing a list of data frames of protein (prot), coding nucleotide (nuc), and genomic nucleotide (gen) atlases for all genes in the IPD-IMGT/HLA Database release, along with a character vector identifying the pertinent IPD-IMGT/HLA Database release.

Note

Data informing the atlases were downloaded from the ANHIG/IMGTHLA Github repository.

For internal HLAtools use.

Description

The 'AA' atlas identifies the amino acid (AA) positions encoded by codons that span each exon (E) boundary. The 'cDNA' atlas describes the 3' nucleotide position in the cDNA sequence that follows each exon boundary, as well as the codon that spans each exon boundary. The 'gDNA' atlas describes first 3' nucleotide position following each UTR (U), exon or intron (I) boundary. Each feature is followed by its rank (e.g U3 is the 3' UTR). Non-standard gene-features (H, J, N, and S) are detailed in the documentation for the ffN() function.

Usage

atlasMaker(loci, source, version = "Latest")

Arguments

Details

Builds an 'atlas' of the gene-feature (exon, intron and UTR) boundaries for IPD-IMGT/HLA loci, using IPD-IMGT/HLA Database alignments.

Value

A list object of 'atlas' dataframes and a 'release version' character string for each locus and alignment type.

Note

For internal HLAtools use.

Nucleotide atlases for pseudogenes will include a 'codon' row populated with NA values.

Some HLA-DQB1*05 and 06 alleles include a 5th exon that is not present in the DQB105:01:01:01 reference allele. In this case, the Exon 4 to Exon 5 boundary is defined as 'Ins' (insertion). For all other alleles there is no E.4-5 boundary.

Boundaries for non-standard hybrid (H), join (J), novel (N) and segment (S) features may be included in gene fragment and pseudogene atlases.

Description

Divides a BIGDAWG-formatted dataset into two subsets (strata) that do and do not include specified alleles.

Usage

BDstrat(dataset, alleles, warnBelow = 21)

Arguments

Value

A list-object of two BIGDAWG-formatted data frames titled dataset$⁠<alleles>-positive⁠ and dataset$⁠<alleles>-negative⁠. The positive list element includes all subjects with the specified alleles, and the negative list element includes all subjects without those specified alleles.

References

BIGDAWG Data Format

Examples

HLA_data.multi.strat <- BDstrat(sHLAdata,c("DRB1*16:02:01:01","DRB1*04:07:01:01","A*25:01:01:01"))
HLA_data.single.strat <- BDstrat(sHLAdata,"DRB1*16:02:01:01")

Description

Convert BIGDAWG datasets to PyPop datasets

Converts a BIGDAWG-formatted data frame into a pair of PyPop-formatted case and control data frames.

Usage

BDtoPyPop(dataset, filename, save.file = TRUE, save.path = tempdir())

Arguments

Value

When save.file = TRUE, a pair of files named "'filename'.positive.pop" and "'filename'.negative.pop" are generated in the working directory. When save.file = FALSE, a list of two-elements, named "'filename'.positive" and "'filename'.negative", is returned.

Note

Files generated by BDtoPyPop are intended for analysis using Pypop version 1.#.#. PyPop is not an R package, and must be installed separately.

References

Lancaster et al. Front Immunol. 2024 Apr 2;15:1378512. https://pubmed.ncbi.nlm.nih.gov/38629078/

Pappas et al. Hum Immunol. 2016 Mar 77(3):283-287. https://pubmed.ncbi.nlm.nih.gov/26708359/

Examples

HLAdata.PP <- BDtoPyPop(sHLAdata,"BDHLA",FALSE)

Description

Returns a list of data frames of amino acid, codon, nucleotide and genomic alignments, with version information.

Usage

buildAlignments(loci, source, version = "Latest")

Arguments

Value

A list object with a data frame of all allele names (and trimmed, two-field allele names) and their corresponding sequences (Amino Acid, codon, cDNA, or gDNA) for a specific locus, as well as version details for the returned information. These alignments identify locations of feature boundaries in relation to amino acid, codon, cDNA, and gDNA sequences. When a three- or four-field allele name includes an expression variant suffix, that suffix is appended to the trimmed name.

Note

For internal HLAtools use.

Description

Consumes information in the ANHIG/IMGTHLA GitHub repository and at hla.alleles.org/genes to define specific categories of genes supported by the IPD-IMGT/HLA Database, which are represented as nineteen elements of the HLAgazeteer object.

Elements:

• All genes with alignments ($align)

• Genes that that do and do not have amino acid ($prot/$noprot), nucleotide ($nuc/$nonuc), and genomic ($gen/$nogen) alignments

• HLA genes ($hla), pseudogenes ($pseudo), gene fragments ($frag)

• Genes that are expressed ($expressed) or not expressed ($notexpressed)

• Genes in the Class I region ($classireg), Class I HLA genes ($classIhla), Genes in the Class II region ($classiireg), and Class II HLA genes ($classiihla)

• Classical HLA genes ($classical) and non-classical exprssed HLA genes ($nonclassical)

• All genes presented in map order ($map)

The twentieth element ($version) identifies the IPD-IMGT/HLA Database version used to build the HLAgazeteer.

Usage

buildGazeteer(version = getLatestVersion())

Arguments

Value

A list object of vectors organizing the genes in the IPD-IMGT/HLA Database into specific categories.

Note

The $prot and $nuc vectors include a 'DRB' "gene". While 'DRB' is not a gene name, the DRB_prot.txt file includes combined alignments for the DRB1, DRB3, DRB4, and DRB5 genes, and the DRB_nuc.txt file includes combined alignments for the DRB1, DRB2, DRB3, DRB4, DRB5, DRB6, DRB7, DRB8, and DRB9 genes. 'DRB' is included in these vectors for the purpose of validation when these combined alignments are desired.

For interal HLAtools use.

These elements are constructed using data compiled from hla.alleles.org/genes/, github.com/ANHIG/IMGTHLA/tree/Latest/alignments, DOI:10.2741/a317, DOI:10.1111/tan.15180, and Human Genome Assembly GRCh38.p14 reference assembly NC_000006.12.

Additional information about these genes can be found in HLAtools::IMGTHLAGeneTypes.

The $map element does not distinguish the order of the DRB3, DRB4 and DRB5 genes (DRB3/4/5) or the DR6 and DR7 (DR6/7) genes, as the individual elements of these gene sets are found on different DRB haplotypes.

This function requires internet access to function.

Source

Andersson G. Evolution of the human HLA-DR region. Front. Biosci. 1998 Jul 27:3:d739-45.

Alexandrov et al. HLA-OLI: A new MHC class I pseudogene and HLA-Y are located on a 60 kb indel in the human MHC between HLA-W and HLA-J. HLA 2023 Nov; 102(5):599-606.

Description

buildIMGTHLAGeneTypes() scrapes 'hla.alleles.org/genes/index.html' and generates a data frame identifying each gene. It requires internet access to function. As such, this function always returns data for the current IPD-IMGT/HLA Database release.

Usage

buildIMGTHLAGeneTypes()

Value

A list object of two elements – 'version' and 'GeneTypes'. The 'version' element identifies the date that the source table was generated. The 'GeneTypes' element is a data frame of three columns, identifying each gene supported by the IPD-IMGT/HLA Database, along with its molecular characteristics and its status as either a pseudogene or a gene fragment.

Note

For internal HLAtools use.

Description

Evaluates 'alignType' values to ensure that only "prot", "nuc", "codon" and "gen" are passed to downstream functions. If any other values are entered, a message describing excluded values is generated. If no valid 'alignType' values are are present, an error is generated, and any calling function is ended.

Usage

checkAlignType(alignType)

Arguments

Value

A character vector that includes only allowed 'alignType' values.

Examples

checkAlignType(c("nuc","prot","gDNA"))

Description

Checks the position of the first feature boundary (the 5' UTR - Exon 1 boundary in expressed genes) in each gDNA alignment, and identifies those alignments in which that position is not 1.

Usage

checkgDNAstart(verbose = FALSE)

Arguments

Details

This function reviews the gDNA atlases in the HLAatlas object and returns a data frame of the first feature boundary position for each locus. For expressed genes and some pseudogenes, this is the position of the start of Exon 1.

Value

A one-row data frame with one column for each locus with a gDNA alignment.

Note

This function requires that the HLAalignments object has been populated with alignments via the alignmentFull() function.

For internal HLAtools use.

Description

Evaluates 'source' values to ensure that only "AA", "cDNA", and "gDNA" are passed to downstream functions. If any other values are entered, a message describing excluded values is generated.

Usage

checkSource(source)

Arguments

Value

A character vector that includes only allowed 'source' values.

Examples

checkSource(c("AA","cDNA","codon"))

Description

Determines if allele name data for a given IPD-IMGT/HLA Release Version is present in the local HLAtools package.

Usage

checkVersion(version)

Arguments

Value

A logical. TRUE indicates that data for 'version' is available to the local HLAtools package. FALSE means that data for 'version' is not available.

Note

For internal HLAtools use.

Examples

checkVersion(version = "3.25.0")
checkVersion(version = "Latest")

Description

Compares the sequences of two alleles at a locus, and identifies the differences between them at specific positions

Usage

compareSequences(alignType, alleles)

Arguments

Value

A two-row data frame identifying the positions and sequences at which the two alleles differ. E.g., compareSequences(alignType = "gen", alleles = c("DPA101:03:38:01","DPA101:03:38:02"). Positions for which the sequence of either allele is unknown are ignored.

Description

Convert Values Across an Entire Data Frame or Vector

Converts all instances of a value in a data frame or vector to a specified value.

Usage

convertAny(dataset, change.from = NA, change.to = "****")

Arguments

Value

A data frame or vector in which 'change.from' has been converted to 'change.to'.

Examples

dataset <- convertAny(sHLAdata)

Description

Counts the number of spaces in a character string.

Usage

countSpaces(x)

Arguments

Value

A numeric value representing the number of spaces (' ') in x.

Author(s)

Josh Bredeweg, Reddit user jbraids1421

Source

https://www.reddit.com/r/rstats/comments/2th8ic/function_to_count_the_number_of_white_spaces/

Examples

countSpaces("abc def")

Description

Generates a peptide, codon, coding or genomic nucleotide alignment table for user-specified HLA alleles at user-specified positions.

Usage

customAlign(alignType, alleles, positions)

Arguments

Value

A data frame of allele names and the corresponding nucleotide sequences for each desired nucleotide position. an error message is returned if input locus is not available in the ANHIG/IMGTHLA Github Repository.

Note

This function requires that the HLAalignments object has been populated with alignments via the alignmentFull() function. C.f., customAlign("codon",c("DRB101:01","DQB102:01","DPB101:01"),c(1,2,3,7,8,9,13,14,15)) and customAlign("codon",c("DPB101:01:01:01","DQA101:01:01:01","DQB105:01:01:01"),list(19:35,1:4,6:9)).

Description

Adds the '.' delimiters to a 'squashed' IPD-IMGT/HLA Database Release Version name

Usage

expandVersion(ver)

Arguments

Value

A character vector of the expanded IPD-IMGT/HLA Database Release Version name.

Note

For internal HLAtools use.

This function assumes single-character-length first and third fields of IPD-IMGT/HLA Database Release Version names.

Examples

expandVersion(3450)

Description

HLA pseudogenes and gene fragments many not share all of the gene features of their expressed homologs. The ffN() function generates a list object identifying the features present in a given gene fragment or pseudogene with a genomic alignment file. This includes annotations of the differences between the pseudogenes and gene fragments, and their expressed homologs. Pseudogenes and gene fragments are identified in the IMGTHLAGeneTypes data object.

Standard Features

• E - Exon, a peptide-encoding sequence

• I - Intron, an intervening sequence found between Exons

• U - UTR, an untranslated region of sequence preceding the first Exon or following the last Exon

Additional Features used in these annotations, based on boundaries indicated in the sequence alignment, are:

• H - Hybrid, a sequence that includes at least one known feature sequence and one nucleotide sequence that does not correspond to a known feature

• J - Join, a sequence that includes two or more features that are separated by a feature boundary in the reference

• N - Novel, a novel sequence that does correspond to a known feature sequence

• S - Segment, a subset of a longer feature sequence

Reference Genes

• HLA-C genomic sequence is used as the reference for class I pseudogenes and gene fragments.

• HLA-DPA1 and -DPB1 genomic sequences are used as the references for class II pseudogenes -DPA2 and -DPB2, respectively.

Usage

ffN(version)

Arguments

Value

A list object where each element is the name of a pseudogene or gene fragment. Each of these elements is a list of 'features' and 'annotation'. "Features" identifies the gene features for that gene, ordered from 5' to 3'. Because these genes are not-expressed, the three standard gene features (U, Untranslated Region (UTR); E, Exon; and I, Intron) may not always be present. In these cases, H, J, N and S features (defined below) are returned. Each feature identifier is followed by an identifying number (e.g. U.5 is the 5' UTR, and E.3 is Exon 3). "Annotation" provides the composition of the non-standard H, J, N and S features for each gene. #'

Note

Features and their annotations have been identified manually. Feature annotations will not change unless a new pseudogene or gene fragment is added in a future release, in which case new annotations will be generated.

The H, J, N and S features are described for class I pseudogenes and gene fragment sequences, all of which are described relative to the HLA-C reference sequence. Feature length differences for DPA2 and DPB2, relative to the DPA1 and DPB1 references, are noted in annotations of standard feature abbreviations (E, I and U).

No annotations are included for the DRB2, DRB6, DRB7, and DRB9 genes, as genomic alignments for these genes are not available.

For internal HLAtools use.

Examples

fragmentFeatureNames <- ffN("3.35.0")

Description

Format PyPop Data Frame Headers

Format the header of a PyPop-formatted data frame.

Usage

formatHead(colHead)

Arguments

Value

A vector in which the locus names are suffixed with '_1' and '_2'.

Note

This function assumes that the first two elements the 'colHead' vector are not locus/gene names.

References

Lancaster et al. Front Immunol. 2024 Apr 2;15:1378512. https://pubmed.ncbi.nlm.nih.gov/38629078/

Pappas et al. Hum Immunol. 2016 Mar 77(3):283-287. https://pubmed.ncbi.nlm.nih.gov/26708359/

Examples

formatHead(colHead = colnames(sHLAdata))

Description

A list object of 15 elements. Each of the 15 elements corresponds to one of the 15 HLA pseudogenes and gene fragments, and contains two items. The first item identifies the gene features for that locus. The second item contains an annotation detailing information regarding non-standard gene structures. This object is built by the ffN() function.

Usage

data(fragmentFeatureNames)

Format

A list of 15 elements that identify the gene features for each locus wih a genomic alignment and annotate non-standard features

Source

https://hla.alleles.org/genes/index.html

https://github.com/ANHIG/IMGTHLA/tree/Latest/alignments

Description

Retrieves the filenames of the protein, nucleotide and genomic alignments available a specific branch of the IMGTHLA GitHub Repository

Usage

getAlignmentNames(URL)

Arguments

Value

A character vector of all of the filenames.

Note

For internal HLAtools use.

Description

Trims a properly formatted colon-delimited HLA allele name to a desired number of fields.

If an allele name with an expression-variant suffix is truncated, the suffix can be appended to the end of the truncated allele name. If a resolution value greater then the number of fields in the submitted field is specified, the original allele is returned.

Usage

getField(allele, res, append = FALSE)

Arguments

Value

A version of the 'allele' character string that has been trimmed to 'res' resolution.

Note

For internal HLAtools use.

Examples

getField("HLA-A*01:01:01:01", 3)
getField("DRB1*11:01:01:12N", 2,TRUE)

Description

Identifies the most recent version of the IPD-IMGT/HLA Database available in the ANHIG/IMGTHLA Github repository.

Usage

getLatestVersion()

Value

A dot-delimited character string identifying the latest release version (branch) of the ANHIG/IMGTHLA Github repository.

Note

For internal HLAtools use.

Examples

getLatestVersion()

Description

Calls GLupdate() to translate the HLA allele names in a vector or data frame between two IPD-IMGT/HLA Database release versions.

Usage

GIANT(data, transFrom, transTo)

Arguments

Value

A data frame or vector of HLA allele name data in the 'transTo' release.

Note

GIANT() will ignore the first two columns of BIGDAWG-formatted data frames, which include non-HLA data. All columns in non-BIGDAWG-formatted data frames are expected to contain HLA allele names.

Examples

GIANT(c("A*01:01:01:01","DOA*01:01:01:01"),"3.56.0","2.20.0")
updsHLAdata <- GIANT(sHLAdata,"3.56.0","2.25.0")

Description

A two-column data frame (modified from pould::hla.hap.demo) including GL String data in Gl String Code format. Column one identifies each subject's status, while column two identifies each subject's HLA genotype in GL String Code format. This data is provided for use in examples and demonstrations.

Usage

data(GLSC.ex)

Format

A dataframe with 419 rows and 2 columns.

Source

pould::hla.hap.demo

References

Mack et al. HLA 2023 Oct;102(4):501-507 https://doi.org/10.1111/tan.15145

Description

A wrapper function for GLtoUN, which translates strings from GL String format to UNIFORMAT format.

Usage

GLStoUNI(GLstring, prefix = "HLA-", pre = FALSE)

Arguments

Value

A version of 'GLstring' converted to UNIFORMAT format, or FALSE if 'GLstring' is invalid.

Note

This function does not function with the "?" operator, as the "?" operator has no cognate in UNIFORMAT.

References

Nunes Tissue Antigens 2007;69(s1):203-205 https://doi.org/10.1111/j.1399-0039.2006.00808.x

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Examples

GLStoUNI("HLA-A*02:01/HLA-A*02:02+HLA-A*03:01/HLA-A*03:02")
GLStoUNI("A+B/C~D^G|E^W+X/Y^Z+J")

Description

A two-column example data frame (from pould::hla.hap.demo) including GL String Data. Column one identifies each subject's status, while column two identifies each subject's HLA genotype in GL String format. This data is provided for use in examples and demonstrations.

Usage

data(GLstring.ex)

Format

A dataframe with 419 rows and 2 columns.

Source

pould::hla.hap.demo

References

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Description

A function that translates strings from GL String format to UNIFORMAT format.

Usage

GLtoUN(GLstring, prefix = "HLA-", pre = FALSE)

Arguments

Value

A version of the input string converted to UNIFORMAT format.

Note

For internal use only.

This function does not function with the "?" operator, as the "?" operator has no cognate in UNIFORMAT.

References

Nunes Tissue Antigens 2007;69(s1):203-205 https://doi.org/10.1111/j.1399-0039.2006.00808.x

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Examples

GLtoUN("HLA-A*02:01/HLA-A*02:02+HLA-A*03:01/HLA-A*03:02")
GLtoUN("A+B/C~D^G|E^W+X/Y^Z+J")

Description

Updates the allele names in a Genotype List (GL) String Code to the desired reference database version using the IPD-IMGT/HLA Database's Allele List History table.

Usage

GLupdate(GLString, Version, expand = FALSE)

Arguments

Value

An updated version the GL String Code input (in the form of a character string) updated to the input desired version.

Note

For internal use only.

Source

https://github.com/ANHIG/IMGTHLA/blob/Latest/Allelelist_history.txt

References

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Mack et al. HLA 05 July 2023 https://doi.org/10.1111/tan.15145

Examples

GLupdate("hla#3.36.0#HLA-B*15:35", "3.52.0")
GLupdate("hla#3.45.0#HLA-A*02:08", "3.52.0")
GLupdate("hla#3.45.0#HLA-A*02:08", "3.52.0", expand = TRUE)

GLupdate("hla#3.1.0#HLA-A*02:01+HLA-A*01:01:01:01", Version = "3.53.0")
GLupdate("hla#3.44.0#HLA-DPA1*02:01:01:05", "3.45.0")
GLupdate("hla#3.45.0#HLA-DPA1*02:01:01:05", "3.46.0")
GLupdate("hla#3.37.0#HLA-A*01:02", "3.52.0", expand = TRUE)

Description

Extracts the version data from an input GL String Code, or provides appropriate options if version input is not present in the IPD-IMGT/HLA Database.

Usage

GLV(GLString)

Arguments

Value

Returns A character string of the version of the release as it appears in the pertinent alleleListHistory$AlleleListHistory-column-header.

Note

For internal use only.

References

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Mack et al. HLA 05 July 2023 https://doi.org/10.1111/tan.15145

Examples

GLV("hla#3.25.0#HLA-B15:35")

Description

Returns a compressed IPD-IMGT/HLA Database release version or a vector of dot-delimited release version options if the specified version is not present in the alleleListHistory object.

Usage

GLV2(Version)

Arguments

Value

Returns either a single, compressed character string-formatted release version, or a character vector of potential release versions.

Note

For internal use only.

References

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Mack et al. HLA 05 July 2023 https://doi.org/10.1111/tan.15145

Examples

GLV2("3.34.0")
GLV2("3.0.0")

Description

A lightweight validator that inspects a GL String Code for correct structure. If the namespace field contains a value other than value of 'namespace', the namespace is changed to 'hla'. The version and GL String fields are not evaluated.

Usage

GLvalidate(GLString, namespace = c("hla", "kir"))

Arguments

Value

A character string describing wither a well-formatted GL String Code or the value FALSE.

Note

For internal use only.

References

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Mack et al. HLA 05 July 2023 https://doi.org/10.1111/tan.15145

Examples

GLvalidate("ha#3.25.0#hla-B15:35")

Description

Uses the provided version information to locate and return possible matches for an incompletely defined IPD-IMGT/HLA Database release version.

Usage

GLVhelper(Version)

Arguments

Value

A list of character strings of possible matches to a given incomplete input.

Note

For internal use only.

References

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Mack et al. HLA 05 July 2023 https://doi.org/10.1111/tan.15145

Examples

GLVhelper("2.25")
GLVhelper("3.9.0")

Description

A list object of sub-lists of R dataframes (atlases) for each locus with a protein (prot), cDNA (nuc), and gDNA (gen) alignment. Each atlas identifies the position of the exon (E), intron (I) or UTR (U) gene-feature boundaries in an alignment. Boundaries for non-standard hybrid (H), join (J), novel (N) and segment (S) features may be included in gene fragment and pseudogene atlases. This object is built by the atlasFull() function.

Usage

data(HLAatlas)

Format

A list of 4 elements that include the gene features boundaries in each ANHIG/IMGTHLA sequence alignment.

• (prot: peptide-alignment atlases)

• (nuc: cDNA-alignment atlases)

• (gen: gDNA-alignment atlases)

• (version: The IPD-IMGT/HLA Database release version under which these data were generated)

Source

https://github.com/ANHIG/IMGTHLA/tree/Latest/alignments

Description

A list object of nineteen vectors that identify genes in the HLA region that share specific commonalities. This object is built by the buildGazeteer() function.

Usage

data(HLAgazeteer)

Format

A large list of 19 vectors that define specific categories of genes supported by the IPD-IMGT/HLA Database

.

• (align: all genes with alignments in the IPD/IMGT-HLA GitHub Repository)

• (gen: genes with genomic alignments in the IPD/IMGT-HLA GitHub Repository)

• (nuc: genes with nucleotide alignments in the IPD/IMGT-HLA GitHub Repository)

• (prot: genes with protein alignments in the IPD/IMGT-HLA GitHub Repository)

• (nogen: genes with no genomic alignments)

• (nonuc: genes with no nucleotide alignments)

• (noprot: genes with no protein alignments)

• (pseudo: pseudogenes)

• (frag: gene fragments)

• (hla: HLA genes)

• (expressed: genes that are expressed)

• (notexpressed: genes that are not expressed)

• (classireg: genes found in the HLA class I region)

• (classihla: class I HLA genes)

• (classiireg: genes found in the HLA class II region)

• (classiihla: class II HLA genes)

• (classical: classical HLA genes)

• (nonclassical: non-classical HLA genes)

• (map: all genes organized by 5' to 3' map order on the genomic reference + strand)

• (version: IPD-IMGT/HLA Database version used to build the HLAgazeteer)

Source

https://hla.alleles.org/genes

https://github.com/ANHIG/IMGTHLA/tree/Latest/alignments

Andersson Front. Biosci. 1998, 3(4), 739–745. https://doi.org/10.2741/a317

Alexandrov et al. HLA 2023, Vol.102(5), p.599-606. https://doi.org/10.1111/tan.15180

https://www.ncbi.nlm.nih.gov/nucleotide/NC_000009.12

Description

A data frame of three columns identifying each gene supported by the IPD-IMGT/HLA Database, its molecular characteristics, and its status as a gene fragment or pseudogene. This object is built by the BuildIMGTHLAGeneTypes() function.

Usage

data(IMGTHLAGeneTypes)

Format

A list object of two elements:

• (GeneTypes: a data frame of three columns)

• (version: a character string identifying the date that the source file was written)

Source

https://hla.alleles.org/genes/index.html

Description

Searches alignments for alleles that share a specific sequence motif.

Usage

motifMatch(motif, alignType, full = TRUE)

Arguments

Value

A character vector of allele names that contain the motif, or NA when no alleles contain the motif, NULL when no alignment is available for specified locus, and FALSE when the locus or motif is invalid.

Note

This function requires an HLAalignments object that has been populated with alignments via alignmentFull().

Description

Generates a peptide, codon, coding nucleotide or genomic alignment for HLA alleles allowing each allele to be aligned to a different set of positions.

Usage

multiAlign(alignType, alleles, positions)

Arguments

Value

A data frame of 'allele' and the corresponding nucleotide sequence for specified positions designated for an allele. a nucleotide sequence is not returned for a specific allele if input allele is not available in the ANHIG/IMGTHLA Github Repository. position will be left empty if specific allele does not have a nucleotide at the input position.

Note

For internal HLAtools use.

Description

Trim a vector of allele names to a specified number of fields or digits.

Usage

multiAlleleTrim(alleles, resolution, version = 3, append = FALSE)

Arguments

Value

A vector of the trimmed allele name, shortened according to the input parameters.

Note

Expression variant suffixes will not be removed from full-length allele names that have fewer than four fields or eight digits.

Examples

alleles <- c("A*02:01:01:02L","DRB1*08:07", "DQB1*04:02:01:16Q")
multiAlleleTrim(alleles,2)
multiAlleleTrim(alleles,2,append = TRUE)

alleles <- c("A*01010102L","DRB1*1613N","HLA-Cw*0322Q")
multiAlleleTrim(alleles,1,2,TRUE)
multiAlleleTrim(alleles,2,2)

Description

Translate a data frame or a vector of GL Strings to UNIFORMAT strings.

Usage

multiGLStoUNI(GLstringArray, prefix = "HLA-", pre = FALSE)

Arguments

Value

A version of 'GLStringArray' in which the GL String data has been converted to UNIFORMAT format. If a 'GLstringArray' was a data frame, a data frame is returned. If 'GLstringArray' was a vector, a vector is returned.

Note

GL Strings that include the "?" operator will not be translated, as the "?" operator has no cognate in UNIFORMAT.

References

Nunes Tissue Antigens 2007;69(s1):203-205 https://doi.org/10.1111/j.1399-0039.2006.00808.x

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Examples

multiGLStoUNI(GLstring.ex[[2]][1:5],version) ## converting a vector of GL Strings to UNIFORMAT
multiGLStoUNI(GLstring.ex[1:5,1:2])  ## converting a data.frame of GL Strings to UNIFORMAT

Description

Applies validateLocus() to a vector of locus names, validates them against HLAgazeteer$gen, and returns a vector of validated locus names.

Usage

multiLocusValidation(loci, source = "gDNA", verbose = TRUE)

Arguments

Value

A character vector of locus names that are present in HLAgazeteer$gen.

Note

The results of this check should only be considered valid for the IPD-IMGT/HLA Database release version of the current HLAgazeteer.

Examples

multiLocusValidation(loci = c("DRB1","DPB1","DQB8"))
multiLocusValidation(loci = c("A","B","C","D","Q"))

Description

Searches specific release versions in the AlleleListHistory object for a set of user-defined allele-name elements.

Usage

multiQueryRelease(rel, variants = "", all = TRUE)

Arguments

Value

A character vector of all alleles that share all 'variants' in 'rel' or the number of alleles that share all 'variants' in 'rel'.

Examples

# Identify DRB1 allele names that include a 'Q' character in release 3.58.0.
multiQueryRelease("3.58.0",c("DRB1","Q"),TRUE) 
# Identify the number of null (N) DRB1 alleles.
multiQueryRelease("3.58.0",c("DRB1","N"),FALSE)

Description

Generates a character string of multiple protein, codon or nucleotide or genomic sequences at the specified positions for the specified allele name.

Usage

multiSearch(
  alignType,
  locus,
  allele,
  positions,
  prefix = TRUE,
  sep = "~",
  trimmed = FALSE
)

Arguments

Value

codons (possibly with position number) at 'positions' for 'allele'. If 'allele' does not have a codon at 'position', ” will be returned.

Note

For internal HLAtools use only.

Description

Translate a data frame or vector of UNIFORMAT strings to GL Strings.

Usage

multiUNItoGLS(UniformatArray, prefix = "HLA-", pre = TRUE)

Arguments

Value

A version of 'UniformatArray' in which the UNIFORMAT data have been converted to GL String format. If a 'UniformatArray' was a data frame, a data frame is returned. If 'UniformatArray' was a vector, a vector is returned.

Note

This function does not return the GL String "?" operator, as the "?" operator has no cognate in UNIFORMAT.

References

Nunes Tissue Antigens 2007;69(s1):203-205 https://doi.org/10.1111/j.1399-0039.2006.00808.x

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Examples

multiUNItoGLS(unname(as.vector(UNIFORMAT.example[2]))[[1]])
multiUNItoGLS(UNIFORMAT.example[1:2])

Description

Updates a column from a data frame in GL String Code format to a desired reference database version.

Usage

multiUpdateGL(GLstringArray, Version, expand = FALSE)

Arguments

Value

A version of the input array of GL String Codes (in a data frame) updated to the desired version. NA values are returned in place of alleles that are not present in Version.

References

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Mack et al. HLA 05 July 2023 https://doi.org/10.1111/tan.15145

Examples

# Example update of two GL Strings Codes containing truncated alleles from version 3.1.0 to 3.53.0.
GLSC.ex[[2]][1:2] 
multiUpdateGL(GLSC.ex[[2]][1:2], Version = "3.53.0")

Description

Returns the number of fields in a colon-delimited HLA allele name. A value of 1 is returned for digit-delimited HLA allele names.

Usage

numFields(allele)

Arguments

Value

A numeric value describing the number of fields in the allele name.

Examples

numFields("HLA-A*01:01")
numFields("DRB1*04:03:01")
numFields("13:02:01:01")

Description

Returns a vector describing the location of key information in the header blocks of alignment files.

Usage

parseAlignmentHead(version)

Arguments

Value

Either FALSE if the version is not valid, or two-value numerical vector describing (1) the header line in which alignment version data appears and (2) the length of the character string in that line preceding version data.

Examples

parseAlignmentHead("3.25.0")

Description

Sorts sequence alignment positions that contain indels in numerical order; e.g., three indels following position X are are identified as X.1, X.2 and X.3.

Positions are validated against a specified locus for a specified alignment type. Positions that do not exist for that locus-alignment combination are not returned.

Usage

posSort(posVec, alignType, locus)

Arguments

Value

A character string of the correctly sorted sequence.

Note

Indel positions must be text-formatted (e.g. "607.12"). C.f., posSort(c(2,4,3,1,5), "nuc","DRB1") vs posSort(c("607.23","607.10","607.3","607.4"),"nuc","DRB1").

Description

Convert the header of a BIGDAWG-formatted data frame into a Python for Population Genomics (PyPop) formatted header.

Usage

pypopHeaders(colHead)

Arguments

Value

A PyPop-formatted column header vector.

Note

This function returns unique locus names for each column. For example, "A_1" and "A_2" headers will be returned for two "A" locus columns. PyPop configuration (.ini) files allow this format to be customized.

References

Lancaster et al. Front Immunol. 2024 Apr 2;15:1378512. https://pubmed.ncbi.nlm.nih.gov/38629078/

Pappas et al. Hum Immunol. 2016 Mar 77(3):283-287. https://pubmed.ncbi.nlm.nih.gov/26708359/

See Also

PyPop Configuration File

Examples

pyHead <- pypopHeaders(colnames(sHLAdata))

Description

Searches specific release versions in the AlleleListHistory object for user-defined allele variants.

Usage

queryRelease(rel, variant = "", all = FALSE)

Arguments

Value

A character vector of all matches to 'variant' in 'rel' or the number of all matches to 'variant' in 'rel'.

Examples

# Identify the number of DRB9 alleles in releases 3.30.0 and 3.31.0.
queryRelease("3.30.0","DRB9",FALSE) 
queryRelease("3.31.0","DRB9",FALSE)

# Identify the total number of alleles in release 3.56.0.
queryRelease(3560)

Description

Correctly put decimals back into an AlleleListHistory column-formatted version name.

Usage

redec(Cname)

Arguments

Value

A character string describing a version name with decimals in appropriate places according to the IPD-IMGT/HLA Database.

Note

For internal use only.

Examples

redec("X3090")

Description

This function returns a list object containing relative risk, confidence interval and p-value data for the individual alleles and individual genotypes at each locus in a BIGDAWG-formatted non-case-control genotype data frame or file.

Usage

relRisk(dataset, return = TRUE, save.path = tempdir())

Arguments

Value

A list object of two lists ("alleles" and "genotypes"), each of which contains a list of nine-column data frames containing results for each unique allele or genotype (in rows) at each locus. Column headers in each dataframe are, Locus, Variant, Status_1, Status_0, RelativeRisk, CI.low, CI.high, p.value, and Significant.

References

BIGDAWG Data Format

Examples

rr <- relRisk(sHLAdata)

Description

Removes periods from IMGT/HLA Database release versions, and converts release versions '3.00.0'-'3.09.0' to '300'-'390' to facilitate working with these GitHub repo branches.

Usage

repoVersion(version)

Arguments

Value

A character string of the release version suitable for use in an IMGT/HLA GitHub repository URL.

Note

For internal HLAtools use.

Examples

repoVersion("3.05.0")

Description

A BIGDAWG-formatted data frame of 18 columns and 47 rows containing synthetic HLA-A, -C, -B, -DRB1, -DQA1, -DQB1, -DPA1, and -DPB1 genotype data for 24 control subjects and 23 case subjects. Allele name data were recorded under IPD-IMGT/HLA Database release version 3.56.0. These are synthetic data generated for the imaginary UchiTelle population, and do not represent biologically-derived HLA genotypes.

Usage

data(sHLAdata)

Format

A data frame of 18 columns and 47 rows.

Source

These synthetic data were generated as part of the 13th International HLA Workshop to demonstrate PyPop functions. See http://pypop.org/docs/guide-chapter-usage.html#data-minimal-noheader for additional details.

Description

Removes the '.' delimiters from an IPD-IMGT/HLA Database Release Version name

Usage

squashVersion(ver, num = FALSE)

Arguments

Value

A 4-digit value, as either a character string or a number.

Note

For internal HLAtools use.

Examples

squashVersion("3.45.0",TRUE)

Description

Converts between 'alignType' values, identifying four types of sequence alignments and 'source' values, identifying three kinds of alignment files.

Usage

typeToSource(alignVector, toSource = TRUE)

Arguments

Value

A character string of the converted 'align' or 'source' value.

Examples

typeToSource(c("nuc","prot","gen"),TRUE)

Description

Generates a peptide, codon, coding or genomic nucleotide alignment at a single set of positions for HLA alleles at one or more loci.

Usage

uniAlign(alignType, alleles, positions)

Arguments

Value

A data frame of allele names and the corresponding codon sequence for specified position. a codon sequence is not returned for a specific allele if input allele is not available in the ANHIG/IMGTHLA Github Repository. position will be left empty if specific allele does not have a codon at the input position.

Note

For internal HLAtools use.

Description

A two-column example data frame including UNIFORMAT data. Column one contains sample identifiers, while column two identifies each subject's HLA genotype in UNIFORMAT format. To be used for example runs and demonstrations.

Usage

data(UNIFORMAT.example)

Format

A dataframe with 20 rows and 2 columns.

Source

https://hla-net.eu/wp/wp-content/uploads/example-three-loci.unif_.txt

References

Nunes Tissue Antigens 2007;69(s1):203-205 https://doi.org/10.1111/j.1399-0039.2006.00808.x

Description

Generates a character string of the peptide, codon or nucleotide sequence at the specified position for the specified HLA allele.

Usage

uniSearch(alignType, locus, allele, position, prefix = TRUE, trimmed = FALSE)

Arguments

Value

The peptide residue, codon or nucleotide sequence at specified position for specified allele as available in the ANHIG/IMGTHLA Github Repository.

Note

For internal HLAtools use.

Description

A wrapper function for UNtoGL() which translates strings from UNIFORMAT format to GL String format.

Usage

UNItoGLS(uniformat, prefix = "HLA-", pre = TRUE)

Arguments

Value

An version of 'uniformat' converted to GL String format, or FALSE if 'uniformat' is invalid.

Note

This function does not return the "?" operator, as the "?" operator has no cognate in UNIFORMAT.

References

Nunes Tissue Antigens 2007;69(s1):203-205 https://doi.org/10.1111/j.1399-0039.2006.00808.x

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Examples

UNItoGLS("A*02:01,A*03:01|A*02:01,A*03:02|A*02:02,A*03:01|A*02:02,A*03:02")
UNItoGLS("A,B|A,C~D G|E W,X|W,Y Z,J J,Z")

Description

A function that translates strings from UNIFORMAT format to GL String format.

Usage

UNtoGL(uniformat, prefix = "HLA-", pre = TRUE)

Arguments

Value

An altered version of the input character string, converted to GL String format.

Note

For internal use only.

This function does not return the "?" operator, as the "?" operator has no cognate in UNIFORMAT.

References

Nunes Tissue Antigens 2007;69(s1):203-205 https://doi.org/10.1111/j.1399-0039.2006.00808.x

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Examples

UNtoGL("A*02:01,A*03:01|A*02:01,A*03:02|A*02:02,A*03:01|A*02:02,A*03:02")
UNtoGL("A,B|A,C|D,B|D,C|E,B|E,C", pre = FALSE)

Description

Applies updateAlleleListHistory(), atlasFull(), buildGazeteer(), extractGeneTypes(), and ffN() to update the alleleListHistory, HLAatlas, HLAgazeteer, IMGTHLAGeneTypes and fragmentFeatureNames data objects.

A new alleleListHistory data object should be generated with each IPD-IMGT/HLA Database release. The other data objects will likely only change when new genes are added to the IPD-IMGT/HLA Database.

Usage

updateAll(updateType = "all", version = getLatestVersion())

Arguments

Value

No value is returned. The desired versions of the specified data objects are built into the environment that called updateAll().

Note

Generating a new HLAatlas can take 5 minutes or more to complete.

Description

Consumes the ANHIG/IMGTHLA GitHub repository's allelelisthistory.txt file to create the AlleleListHistory object.

Usage

updateAlleleListHistory()

Value

A list object containing two data frames. alleleListHistory$Version identifies the date and version of alleleListHistory$AlleleListHistory. alleleListHistory$AlleleListHistory relates each IPD-IMGT/HLA Database Accession ID (HLA_ID) to the corresponding HLA allele name in each release version since 1.05.0.

Description

A quality control wrapper for GLupdate, which updates a GL String Code to a desired reference database version.

Usage

updateGL(GLStringCode, Version, expand = FALSE)

Arguments

Value

A version of the input GL String code (in the form of a character string) updated to the desired version.

References

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Mack et al. HLA 05 July 2023 https://doi.org/10.1111/tan.15145

Examples

updateGL("hla#1.05.0#HLA-DPA1*0106", "3.52.0")
updateGL("hla#3.36.0#HLA-B*15:35", "3.52.0")
updateGL("hla#3.45.0#HLA-DPA1*02:01:01:04", "3.52.0")

updateGL("hla#3.45.0#HLA-A*02:08", "3.52.0", expand = TRUE)
updateGL("hla#1.05.0#HLA-DPA1*0106", "3.52.0", expand = TRUE)
updateGL("hla#1.05.0#HLA-DPA1*0106", "2.27.0", expand = TRUE)

Description

Returns TRUE if an allele name is found in HLAalignments in either the 'allele_name' column of full-length allele names or the 'trimmed_allele' column of two-field allele names in the pertinent genomic alignment. Returns FALSE if the allele name is not properly formed, or if the allele name is not found in HLAalignments.

Usage

validateAllele(allele)

Arguments

Value

A logical identifying if the allele name is present in the alignments (TRUE) or, if it is not in the alignments or is not valid not (FALSE).

Note

Messages will be returned to the console if the allele name is malformed, or the locus is invalid; e.g., validateAllele("C01:01:01:01") or validateAllele("A01:01:01:01:01").

The locus being evaluated must be included in HLAalignments.

Description

Evaluates a GL String to identify unsupported characters for a specified GL String version.

Usage

validateGLstring(GLstring, version)

Arguments

Value

A logical. TRUE is returned when all characters in a 'version' GL String are permitted. FALSE is returned when forbidden characters are present, or when an incorrect 'version' is specified.

References

Mack et al. HLA 2023;102(2):206-212 https://doi.org/10.1111/tan.15126

Examples

validateGLstring("HLA-A*02:01/HLA-A*02:02+HLA-A*03:01/HLA-A*03:02", version = "1.0")

Description

Checks a vector of HLA locus names against the HLAgazeteer to determine if the locus name is valid for a specific type of alignment.

Usage

validateLocus(loci, source)

Arguments

Value

A logical value. TRUE indicates that all of the names and source types are valid. FALSE indicates that at least one locus name or alignment source type is invalid.

Note

The results of this check should only be considered valid for the version of the HLAgazeteer included in the HLAtools package.

Examples

validateLocus(loci = "DRB1", source = "AA")
validateLocus(loci = c("V"), source = c("cDNA","gDNA"))
validateLocus(loci = c("E","F","G"), source = "gDNA")

Description

Evaluates a motif to determine if the locus is valid and variants are valid.

Usage

validateMotif(motif, alignType)

Arguments

Value

If the motif is valid, TRUE is returned. If the locus or body of the motif is invalid, FALSE is returned along with a brief message.

Examples

validateMotif("A*-21M~2P","prot")
validateMotif("A*196G~301A~3046T","gen")

Description

Evaluates a UNIFORMAT string to identify unsupported characters.

Usage

validateUniformat(uniformat)

Arguments

Value

A logical. TRUE is returned when all characters in 'uniformat' are permitted. FALSE is returned when forbidden characters are present.

References

Nunes Tissue Antigens 2007;69(s1):203-205 https://doi.org/10.1111/j.1399-0039.2006.00808.x

Examples

validateUniformat("A*02:01,A*03:01|A*02:01,A*03:02|A*02:02,A*03:01|A*02:02,A*03:02")

Description

Determines if an IPD-IMGT/HLA Release Version is referenced in the AlleleListHistory file.

Usage

validateVersion(version)

Arguments

Value

A logical. TRUE indicates that data for 'version' is available in the ANHIG/IMGTHLA GitHub repository. FALSE means that data for 'version' is not available.

Note

For internal HLAtools use.

Examples

validateVersion(version = "3.31.1")
validateVersion(version = "3.13.0")

Description

Returns TRUE if an allele name is present in AlleleListHistory or FALSE it is absent, or c(TRUE,version), where 'version' is the most recent IPD-IMGT/HLA Database release in which that name appeared, when version = TRUE.

Usage

verifyAllele(allele, version = FALSE)

Arguments

Value

A logical identifying if the allele name is found in AlleleListHistory (TRUE) or not (FALSE), or c(TRUE,version) if version = TRUE.

Examples

verifyAllele("A*01:01:01:01")
verifyAllele("A*01:01:01:01",TRUE)
verifyAllele("A*010101",TRUE)
verifyAllele("A*0101",TRUE)