Estimate allele frequencies in reference strata and calculate the genotype log-likelihood of every individual under every candidate stratum. The native likelihood engine is implemented entirely in R and returns the complete individual-by-stratum score table required for assignment diagnostics and Dlr calculations.
Usage
assign_individuals(
data,
strata = NULL,
engine = c("likelihood", "elastic_net", "xgboost", "tabpfn"),
genotype.method = c("GT", "GL", "PL"),
leave.one.out = TRUE,
frequency.floor = NULL,
folds = 5L,
random.seed = NULL,
effective.n.tolerance = 0.2,
em.tolerance = 1e-07,
em.max.iterations = 200L,
unsampled.source = FALSE,
unsampled.cutoff = -3,
sequencing.error = 0.01,
evaluation.data = NULL,
marker.blocks = NULL,
reporting.unit = NULL,
verbose = TRUE
)Arguments
- data
A GDS file or object, or tidy genomic data accepted by [genometranslator::read_genome()]. Genotypes are converted internally to diploid alternate-allele dosage (`0`, `1`, `2`, or `NA`).
- strata
Optional strata file or object accepted by [genometranslator::read_strata()]. When `NULL`, `STRATA` must be present in `data`. Default:
strata = NULL.- engine
Assignment engine: native population-genetic likelihood, elastic-net multinomial regression, XGBoost, or experimental TabPFN. Default:
engine = "likelihood".- genotype.method
Genotype information used by the native likelihood engine: called genotypes (`"GT"`), log10-scaled or normalized genotype likelihoods (`"GL"`), or Phred-scaled genotype likelihoods (`"PL"`). GL requires `GL_HOM_REF`, `GL_HET`, and `GL_HOM_ALT`; PL uses the analogous `PL_` columns. Default:
genotype.method = "GT".- leave.one.out
Logical. When assigning a reference individual, exclude that individual from allele-frequency estimation in its home stratum. Default:
leave.one.out = TRUE.- frequency.floor
Minimum allele frequency used to prevent zero likelihoods. With `NULL`, the floor is estimated independently for every stratum and marker as `1 / (2 * N + 1)`, where `N` is the number of genotyped reference individuals. Default:
frequency.floor = NULL.- folds
Number of stratified outer validation folds used by machine- learning engines. Default:
folds = 5.- random.seed
Integer controlling fold creation and stochastic engines. Default:
random.seed = NULL.- effective.n.tolerance
Relative difference in effective reference sample size above which GL/PL analyses issue an imbalance warning. Default:
effective.n.tolerance = 0.20.- em.tolerance
Convergence tolerance for GL/PL allele-frequency estimation. Default:
em.tolerance = 1e-7.- em.max.iterations
Maximum EM iterations for each stratum-marker allele-frequency estimate. Default:
em.max.iterations = 200.- unsampled.source
Logical. For GL/PL data, calculate a coverage-aware, reference-standardized score for detecting individuals that may originate from an unsampled source. Requires `ALLELE_REF_DEPTH` and `ALLELE_ALT_DEPTH`. Default:
unsampled.source = FALSE.- unsampled.cutoff
Lower standardized-score threshold used to flag a possible unsampled source. This is an exploratory value that must be calibrated for the dataset. Default:
unsampled.cutoff = -3.- sequencing.error
Per-read error probability used by the unsampled-source expectation model. Default:
sequencing.error = 0.01.- evaluation.data
Optional GL/PL dataset used only to evaluate focal individuals while reference allele frequencies remain estimated from `data`. It must contain the same individual-marker combinations. This supports coverage-matched or deliberately downsampled leave-one-out evaluation. Default:
evaluation.data = NULL.- marker.blocks
Optional marker-block definition used to summarize how assignment likelihood accumulates across the genome. Supply a named vector, a table containing `MARKERS` and `MARKER_BLOCK`, or an integer number of interleaved blocks. Default:
marker.blocks = NULL.- reporting.unit
Optional metadata column defining broader reporting units containing one or more `STRATA`. A second complete assignment result is returned without replacing collection-level results. Default:
reporting.unit = NULL.- verbose
Logical. Display progress messages. Default:
verbose = TRUE.
Value
A list with:
- assignment
One row per individual with its current stratum, inferred stratum, home likelihood, maximum likelihood, likelihood-ratio statistic, and second-best stratum.
- likelihoods
The complete table containing the log-likelihood of every individual under every candidate stratum.
- allele.frequencies
Reference-stratum allele-frequency estimates before individual leave-one-out adjustment.
- effective.sample.size
For GL/PL, mean Fisher-information effective sample size by reference stratum, calculated across loci with estimated allele frequency between 0.05 and 0.95.
- effective.sample.size.markers
For GL/PL, effective sample size for every reference-stratum and marker combination.
- individual.effective.sample.size
For GL/PL, the mean effective information contributed by each reference individual across markers.
- marker.block.likelihoods
When requested, individual-by-candidate likelihoods calculated separately for every marker block.
- reporting.unit
When requested, a nested assignment result for the broader reporting-unit level.
- unsampled.calibration
When requested, reference-stratum mean and standard deviation used to standardize the unsampled-source score.
Details
For genotype dosage `0`, `1`, and `2`, the Hardy-Weinberg genotype probabilities are `(1-p)^2`, `2p(1-p)`, and `p^2`, respectively, where `p` is the alternate-allele frequency in a candidate stratum. Probabilities are accumulated on the log scale. Missing genotypes do not contribute to the score. For called genotypes, `likelihoods$Z_LIKELIHOOD` standardizes each candidate likelihood using the expected mean and variance from exactly the markers observed in that individual. This makes individuals with different missing-data patterns more comparable without imputing genotypes.
The complete `likelihoods` table is intentionally retained. The best and second-best assignments alone are insufficient for Dlr calculations and can conceal assignment ambiguity among additional candidate strata.
This is a classification method: candidate source strata must be defined and represented by reference samples. The native engine assigns an individual to the stratum with the greatest multilocus genotype likelihood. It does not perform a Monte Carlo exclusion test, estimate migration rates, or establish that the true source population was sampled. Those are separate inferential questions (Manel et al. 2005; Paetkau et al. 2004).
Reference individuals should normally be evaluated with `leave.one.out = TRUE`, because using the focal genotype to estimate its home allele frequencies biases assignment in favour of that stratum. Alleles that are observed in an individual but absent from a finite reference sample would otherwise produce a zero likelihood. `frequency.floor` controls the correction. The adaptive default reflects the number of called reference individuals at each marker; set `frequency.floor = 0.005` to use the fixed baseline described by Paetkau et al. (2004) and used by GenoDive.
Assignment reliability depends on representative reference sampling, differentiation among candidate strata, marker information, and reference sample size. Very small reference strata can yield unstable allele-frequency estimates. A high maximum likelihood is comparative evidence among the supplied candidates, not proof that the assigned stratum is the true source.
GT, GL, and PL assignment features
Choose the genotype representation explicitly with `genotype.method = "GT"`, `"GL"`, or `"PL"`; the function does not guess.
GL/PL reference allele frequencies are estimated by expectation- maximization rather than from hard genotype calls.
GL/PL assignment integrates over `0/0`, `0/1`, and `1/1`, retaining genotype uncertainty for the focal individual.
Leave-one-out recalculates the focal reference individual's home- stratum allele frequencies.
Observed Fisher information is summarized as effective reference sample size, revealing imbalances caused by sample number, coverage, and genotype uncertainty.
With the adaptive default, GL/PL frequency floors use marker-specific effective reference size when available, falling back to the number of usable reference individuals.
`evaluation.data` can hold lower-coverage or deliberately downsampled GL/PL values for honest coverage-matched evaluation while the original reference data continue to estimate allele frequencies.
`unsampled.source = TRUE` adds a coverage-aware, reference-standardized diagnostic for individuals that may not originate from any sampled source.
The complete individual-by-stratum likelihood table is retained for ambiguity assessment, Dlr, and downstream analyses.
Relationship to gsi_sim and rubias
Eric C. Anderson's
gsi_sim supports genetic stock
identification simulations and is used by evaluate_assignment
to evaluate assignment performance across marker panels and resampling
designs. Eric C. Anderson also developed assigner's original `gsi_sim`
wrapper.
rubias, developed by Eric C. Anderson and Ben Moran, implements Bayesian inference for the conditional genetic stock identification model. It is designed principally to estimate reporting-unit or population proportions in a mixture while also producing individual posterior assignments. In that joint analysis, estimated mixture proportions contribute information to individual membership.
By contrast, `assign_individuals()` evaluates each individual against the supplied reference strata and retains its full source-likelihood table. It does not estimate mixture proportions. Use rubias when mixed-stock composition is the principal estimand; use `assign_individuals()` for direct individual assignment, GL/PL uncertainty, Dlr, and unsampled-source exploration.
For GL/PL, allele frequencies are estimated from genotype likelihoods by an expectation-maximization algorithm. The genotype likelihood of the focal sample is marginalized over `0/0`, `0/1`, and `1/1`, rather than replacing uncertainty with a hard genotype call. Effective sample size follows the observed-Fisher-information formulation of DeSaix et al. (2024).
With `unsampled.source = TRUE`, the function calculates a coverage-aware raw score by comparing the observed log probability with the expectation under a binomial read-error model, then standardizes it using leave-one-out scores of reference individuals from the same source. This is an exploratory adaptation of DeSaix et al. (2024). The cutoff is dataset-specific: inspect reference score distributions and known controls rather than treating `-3` as universal. Use [compare_unsampled_scores()] to compare this independently implemented diagnostic with scores generated by WGSassign. Agreement should be evaluated on simulated data, known-origin controls, and realistic coverage profiles before selecting a cutoff.
Marker blocks and reporting units
Linked loci do not provide independent evidence. `marker.blocks` retains the full-data assignment while also returning likelihood contributions for biologically defined linkage groups, chromosomes, or reproducible marker partitions. These are sensitivity diagnostics, not independent replicates.
`reporting.unit` evaluates a broader classification in addition to the original `STRATA` analysis. Collections and reporting units answer different questions; the reporting-unit result is nested under `result$reporting.unit` so fine-scale ambiguity is not discarded.
Missing data
Missingness can encode sequencing batch, library, coverage, or processing differences and can therefore create misleading assignment accuracy. The likelihood engine ignores missing focal genotypes, estimates each stratum-marker frequency from called reference genotypes only, and compares candidate strata using the same called-marker set for an individual. Elastic net uses training-fold mean imputation. XGBoost uses its native missing-value routing. TabPFN uses its native preprocessing, including a missingness indicator. All preprocessing and model fitting occur within the training portion of each outer fold. Inspect the returned missingness table and test whether missingness is associated with strata or processing batch.
Data quality and assignment assumptions
Assignment can produce a confident-looking result from technical structure rather than population structure. Before interpreting the output, examine:
Candidate sources and reference sampling. The likelihood analysis assumes that candidate source populations are defined in advance, sampled representatively, and sufficiently differentiated. If the true source is absent, the function still reports the best of the supplied candidates. Unequal or small reference samples make allele-frequency estimates unevenly precise.
Hardy-Weinberg assumptions. The native diploid likelihood uses Hardy-Weinberg genotype probabilities within each stratum. Strong departures can reflect genotyping artefacts, inbreeding, family structure, admixture, or incorrectly pooled populations. Investigate the cause; Hardy-Weinberg departure is not by itself a reason to discard a marker.
Linkage disequilibrium. Multilocus likelihoods treat marker contributions as independent. With linked markers the result is a composite-likelihood approximation: assignment rankings can remain useful, but likelihood differences generally overstate independent information and should not be treated as calibrated uncertainty (DeSaix et al. 2024). Pruning is therefore not always required for classification, but sensitivity across pruned panels or biologically justified linkage blocks is important.
Genotyping error. Allelic dropout, paralogs, strand or allele coding errors, low-depth calls, and batch-specific calling differences can resemble population differentiation. Replicates, depth and balance diagnostics, reproducibility checks, and consistent joint genotyping are especially important.
Missingness and batch effects. Population, extraction batch, library, sequencing lane, coverage, and processing history must not be confounded. Compare missingness and other QC metrics across both strata and technical batches. Random cross-validation does not remove a confounded batch effect; when possible, validate on an independent batch.
Relatedness, duplicates, and family structure. Close relatives split across training and evaluation data can inflate apparent accuracy. Remove unintended duplicates and construct holdouts by family, collection, site, or batch when those groupings could leak information.
Marker frequency and selection. Very rare alleles and low minor-allele counts are unstable under leave-one-out estimation. Marker selection performed on the complete dataset leaks information into the evaluation; repeat selection inside each training fold. Anderson (2010) calls the resulting upward bias in predicted accuracy high-grading bias. Ordinary leave-one-out assignment does not remove it because the focal individual has already influenced which loci were selected. When a panel is chosen for its apparent differentiation among the reference samples, reserve untouched holdout individuals or use a complete Training-Holdout-Leave-one-out design in which marker ranking occurs only in the training data.
This function performs assignment, not general genomic filtering. Prepare and quality-control the input with genometranslator and radr first.
References
Manel S, Gaggiotti OE, Waples RS (2005). Assignment methods: matching biological questions with appropriate techniques. Trends in Ecology & Evolution, 20(3), 136-142. doi:10.1016/j.tree.2004.12.004 .
Paetkau D, Calvert W, Stirling I, Strobeck C (1995). Microsatellite analysis of population structure in Canadian polar bears. Molecular Ecology, 4, 347-354.
Paetkau D, Slade R, Burden M, Estoup A (2004). Genetic assignment methods for the direct, real-time estimation of migration rate: a simulation-based exploration of accuracy and power. Molecular Ecology, 13, 55-65. doi:10.1046/j.1365-294X.2003.02008.x .
Cornuet J-M, Piry S, Luikart G, Estoup A, Solignac M (1999). New methods employing multilocus genotypes to select or exclude populations as origins of individuals. Genetics, 153, 1989-2000.
DeSaix MG, Rodriguez MD, Ruegg KC, Anderson EC (2024). Population assignment from genotype likelihoods for low-coverage whole-genome sequencing data. Methods in Ecology and Evolution, 15, 493-510. doi:10.1111/2041-210X.14286 .
Moran BM, Anderson EC (2019). Bayesian inference from the conditional genetic stock identification model. Canadian Journal of Fisheries and Aquatic Sciences, 76(4), 551-560. doi:10.1139/cjfas-2018-0016 .
Anderson EC (2010). Assessing the power of informative subsets of loci for population assignment: standard methods are upwardly biased. Molecular Ecology Resources, 10(4), 701-710. doi:10.1111/j.1755-0998.2010.02846.x .