Summarize MHC haplotype frequencies and flag rare haplotypes

Computes, from a wide per-animal MHC haplotype designation table (the checkMhcHaplotypeFile format), a per-haplotype summary – copy count, carrier count, uncertain-call count, frequency, and a rare flag – plus the file-level counts that make the frequencies interpretable. Frequencies follow the HLA/NHP-MHC convention of a chromosomes-among-genotyped denominator (Solberg et al. 2008; Doxiadis et al. 2013): the number of certain calls, i.e. 2 x animals minus missing minus uncertain calls. Uncertain calls (a trailing ? on a designation) are excluded from copy counts, carrier counts, and frequencies but always disclosed – per haplotype in nUncertain and file-wide in counts – and a haplotype observed only as uncertain calls gets no summary row (it is never counted as a distinct haplotype; it remains visible in the file-level counts).

Usage

mhcHaplotypeFrequency(
  genotype,
  rareFrequencyThreshold = 0.01,
  rareCarrierThreshold = 2L
)

Arguments

genotype: dataframe with wide-format MHC haplotype data as validated by checkMhcHaplotypeFile (which this function re-runs defensively): columns id, haplotype1, haplotype2, one row per animal.
rareFrequencyThreshold: single non-negative number; a haplotype with frequency at or below it is flagged rare. Default 0.01.
rareCarrierThreshold: single non-negative number; a haplotype with that many or fewer carriers is flagged rare. Default 2L.

Value

A list with two elements. summary: a dataframe with one row per distinct certain haplotype, ordered by haplotype label – haplotype (character), nCopies (integer, certain calls), nCarriers (integer, animals with at least one certain call), nUncertain (integer, uncertain calls of this haplotype), frequency (nCopies / denominator), and isRare (logical, the dual criterion above). counts: a one-row dataframe of file-level totals – nAnimals, nCalls, nMissing, nUncertain, denominator (all integer).

Details

A haplotype is flagged rare when its frequency is at or below rareFrequencyThreshold OR its carrier count is at or below rareCarrierThreshold – a dual criterion with direct precedent in the combined frequency and observation-count bins of the CIWD 3.0 catalog (Hurley et al. 2020). Each leg is anchored: about 0.01 is the published nonhuman-primate MHC "rare" usage (Kanthaswamy et al. 2026; Doxiadis et al. 2013), and a haplotype carried by two or fewer animals can be lost to two removals regardless of frequency, the allele-retention framing of conservation management. At small colony scale the carrier leg does the flagging (no observed haplotype can have frequency at or below 0.01 when fewer than about 100 chromosomes are genotyped), while at registry scale the frequency leg takes over. Both defaults are working-filter settings, not scientific claims.

A homozygous animal contributes two copies and one carrier. Carrier counts include only animals with at least one certain call of the haplotype – an animal whose only call of a haplotype is uncertain is a provisional carrier, listed (and flagged) by mhcHaplotypeCarriers but never counted here. Haplotype designations are opaque labels throughout: never split, parsed, or matched against MHC region names (see checkMhcHaplotypeFile).

References

Kanthaswamy, S., et al. (2026). Next-generation short-read sequencing reveals impacts on major histocompatibility complex diversity resulting from differences in captive rhesus macaque (Macaca mulatta) colony expansion strategies. American Journal of Primatology, 88(1), e70108. doi:10.1002/ajp.70108

Hurley, C. K., et al. (2020). Common, intermediate and well-documented HLA alleles in world populations: CIWD version 3.0.0. HLA, 95(6), 516-531. doi:10.1111/tan.13811

Solberg, O. D., Mack, S. J., Lancaster, A. K., Single, R. M., Tsai, Y., Sanchez-Mazas, A., & Thomson, G. (2008). Balancing selection and heterogeneity across the classical human leukocyte antigen loci: A meta-analytic review of 497 population studies. Human Immunology, 69(7), 443-464. doi:10.1016/j.humimm.2008.05.001

Doxiadis, G. G., et al. (2013). Haplotype diversity generated by ancient recombination-like events in the MHC of Indian rhesus macaques. Immunogenetics, 65(8), 569-584. doi:10.1007/s00251-013-0707-8

Examples

library(nprcgenekeepr)
result <- mhcHaplotypeFrequency(rhesusGenotypes)
head(result$summary)
#>     haplotype nCopies nCarriers nUncertain  frequency isRare
#> 1  A001_B001a       3         3          0 0.05000000  FALSE
#> 2 A002a_B001a       2         2          0 0.03333333   TRUE
#> 3 A002a_B012b       1         1          0 0.01666667   TRUE
#> 4 A002a_B015a       1         1          0 0.01666667   TRUE
#> 5 A002a_B024a       1         1          0 0.01666667   TRUE
#> 6 A002a_B069a       2         2          0 0.03333333   TRUE
result$counts
#>   nAnimals nCalls nMissing nUncertain denominator
#> 1       31     62        0          2          60