Part of Genetic Value Analysis
gvaConvergence(
ped,
pop = NULL,
nMax = 3000L,
guThresh = 1L,
byID = TRUE,
grid = NULL,
k = 20L,
oMin = 0.9,
rhoMin = 0.95,
seed = NULL,
updateProgress = NULL,
breedingTable = NULL,
gestationTable = NULL,
breedingAgeDefault = NULL,
gestationDefault = NULL,
kinshipOverrides = NULL
)An object of class nprcgenekeeprGVConv: a list with
convergence -- a data.frame with one row per assessed iteration
count: iterations, topOverlap (top-k selected-set
overlap, from 0 to 1), and rankAgreement (Kendall rank agreement
of the commonly-ranked animals, from -1 to 1).
recommendedIter -- the smallest assessed iteration count
meeting both criteria, or NA if none did within grid.
converged -- TRUE if any assessed count met both
criteria.
criteria -- the k, oMin, and rhoMin used.
nRankable -- the number of probands carrying a (non-NA)
rank that the order metrics are computed on.
nUndetermined -- the count of the excluded
Undetermined set.
nMax -- the gene-drop budget actually simulated.
The pedigree information in data.frame format (the same input
reportGV takes).
Character vector with animal IDs to consider as the population of interest. The default is NULL (all animals).
Integer gene-drop budget: the number of iteration columns to
simulate. Reproducibility is assessed for iteration counts N with
2 * N <= nMax (each half-split needs 2 * N columns). Default
3000.
Integer threshold number of animals for defining a rare
(unique) allele, passed to calcGU / calcA.
Default 1.
Logical passed to alleleFreq() via calcA; if
TRUE, homozygous alleles are counted once per individual. Default TRUE.
Integer vector of candidate iteration counts to assess. The
default builds c(25, 50, 100, 200, 400, 800, 1500), keeping only those
with 2 * N <= nMax.
Integer size of the top-k selected set compared for overlap.
Default 20.
Numeric minimum top-k overlap for reproducibility. Default
0.90.
Numeric minimum Kendall rank agreement for reproducibility. Default 0.95.
Optional integer; when supplied, set_seed pins the
gene-drop RNG so the convergence curve is reproducible. Default NULL.
Function or NULL passed through to geneDrop() to
update a shiny::Progress object. Default NULL.
Optional overrides for the unknown-parent mean-kinship correction, passed
through to correctUnknownParentMeanKinship() exactly as
reportGV passes them. NULL uses the bundled
defaults.
Optional data.frame of outside-information kinship
overrides (id1, id2, kinship; the coefficient f,
not relatedness r) applied to the kinship matrix before mean kinship
and the unknown-parent correction, exactly as reportGV applies
them, so the convergence diagnostic ranks on the same mean kinship the
report uses. NULL (the default) leaves the
pedigree-derived matrix unchanged. Ids outside the analysis set are
warn-dropped (the run is not aborted). An override REFINES the named kinship
cell; it does not suppress the + sexMean / 2 unknown-parent
correction, which is kept for every animal missing one parent. See
applyKinshipOverrides.
Genome uniqueness (calcGU) is the only ranked Genetic Value
Analysis output that carries Monte Carlo (gene-drop) sampling noise, so the
number of iterations a colony actually needs is pedigree-dependent: there is
no single universal "right" count. gvaConvergence answers the literal
request -- "define reproducible and automate finding the needed number of
iterations" -- on the ratified definition that the decision-relevant quantity
is the selection order (which animals are chosen, and in what order),
not the precision of the gu number itself.
Because the n gene-drop iteration columns are independent and
identically distributed replicates, the whole convergence picture is
recoverable from a single completed gene drop the user already pays
for: gvaConvergence runs one gene drop at nMax, computes the
per-iteration rare-allele matrix once (calcA), and for each
candidate iteration count N in grid splits the columns into two
disjoint halves of N columns each. The two halves are genuinely
independent N-iteration estimates; each is ranked through the same
ordering pipeline the report uses, and the two orderings are compared. A run
is judged reproducible at N when both
the top-k selected animals overlap by at least oMin
(the same animals are chosen), and
the Kendall rank agreement of the commonly-ranked animals is at least
rhoMin (they come out in the same order).
The recommended iteration count is the smallest N in grid at
which both criteria hold. The de-inflated gu = 0
"Undetermined" set (both parents unknown, no recorded origin) is a policy
constant with rank NA; it is excluded from the order the criteria are
computed on and reported separately as nUndetermined.
Because the half-split compares two N-column runs to each other
(never to their pooled mean), it is a conservative, self-validating estimate
of reproducibility at N. This changes nothing about seeding: a fixed
seed already makes gu bit-identical run to run; that is
reproducibility of the process, whereas this function reports the
sampling reproducibility of the estimate.
reportGV, calcGU, calcGUSE
library(nprcgenekeepr)
## A quick, small illustration (use a larger nMax in practice).
conv <- gvaConvergence(nprcgenekeepr::qcPed, nMax = 200L, seed = 1L)
conv$convergence
conv$recommendedIter
Run the code above in your browser using DataLab