- candidates
Character vector of IDs of the animals available for
use in forming the groups. The animals that may be present in
currentGroups are not included within candidates. Ids given
as numbers or as a factor, here, in currentGroups and in the
pedigree's id, sire and dam, are taken as their text.
- kmat
a numeric matrix of pairwise kinship coefficients.
Animal IDs are the row and column names.
- ped
dataframe that is the Pedigree. It contains pedigree
information including the IDs listed in ids.
- currentGroups
List of character vectors of IDs of animals currently
assigned to groups.
Defaults to list(character(0L)), a list with a single empty
element regardless of numGp, assuming no groups are prepopulated.
- threshold
Numeric value indicating the minimum kinship level to be
considered in group formation. Pairwise kinship below this level will be
ignored. The default value is 0.015625.
- ignore
List of character vectors representing the sex combinations
to be ignored. If provided, the vectors in the list specify if pairwise
kinship should be ignored between certain sexes.
Default is to ignore all pairwise kinship between females.
- minAge
Integer value indicating the minimum age to consider in group
formation. Pairwise kinships involving an animal younger than this age
(by the age column of ped) are ignored; an animal exactly
this old is not ignored. Default is 1 year.
- iter
Integer indicating the number of times to perform the random
group formation process. Default value is 1000 iterations.
- numGp
Integer value indicating the number of groups that should be
formed from the list of IDs. Default is 1.
- harem
Logical variable when set to TRUE, the formed groups
have a single male at least minAge old. A harem's sire is held to
the same rules as every other animal: animals related to him at or above
threshold (and, with ancestryRules, animals a block rule bars
from him) are not placed in his group, and when that leaves no one the group
is the sire alone. A group whose seed animals (currentGroups) include
a male at least minAge old keeps him as its sire; a group with no
seeded male is given a sire chosen at random from candidates. It
cannot be combined with a non-zero sexRatio; the call stops with a
message naming both settings.
- sexRatio
Numeric value indicating the number of non-males (females
and animals of other or unknown sex) per male. Values from 0.5 to 20 in
steps of 0.5 are typical, but the range is not enforced. A male is placed
only if he is at least minAge years old; a male younger than that, or
with no birth date, is left out of the groups. A group stops being filled
when it has no such male left, so it can end with fewer females than the
ratio asks for. A non-zero sexRatio cannot be combined with
harem = TRUE; the call stops with a message.
- withKin
Logical variable when set to TRUE, the kinship
matrix for the group is returned along with the group and score.
Defaults to not return the kinship matrix. This maintains compatibility with
earlier versions.
- maxCandidates
Integer value indicating the maximum number of
distinct candidate solutions to retain during the simulation (issue #146
Slice 1). Default is 5.
- exhaustive
Logical. When TRUE, enumerate every maximal
independent set of the conflict graph instead of random sampling (issue
#146 Slice 2), subject to maxExhaustiveCandidates/
exhaustiveTimeLimit. Only supported for numGp = 1,
harem = FALSE, sexRatio = 0 -- any other combination
stop()s with a message naming the specific unsupported condition,
rather than silently falling back to sampling. Default is FALSE
(the existing sampling behavior, unchanged).
- maxExhaustiveCandidates
Integer. Pre-flight feasibility ceiling
for exhaustive = TRUE: a candidate pool larger than this
stop()s before any enumeration runs. Default is 20.
- exhaustiveTimeLimit
Numeric. Wall-clock seconds allowed for
exhaustive = TRUE's search before it truncates gracefully
(exhaustive = FALSE in the return value, not an error). Default
is 10.
- ancestryRules
Optional data frame of ancestry compatibility rules
(issue #168), in the shape checkAncestryRules validates --
it is (re-)validated here, so structural or domain errors stop()
with the validator's specific message. Default NULL: no rules,
behavior identical to previous versions. When supplied, ped must
carry an ancestry column (an error otherwise, so a script user
who passed rules gets truth, not silence). block-severity rules
exclude their conflicting pairs during formation -- in sampling,
exhaustive, and sexRatio modes, and sex-blind (deliberately
bypassing the female-female kinship exemption in ignore).
flag-severity rules never affect the search; compute them
afterward with reportAncestryViolations.
- updateProgress
Function or NULL. If this function is defined, it
will be called during each iteration to update a
shiny::Progress object.