Estimate probability ratios \(P(R|A) / P(R)\) for age differences A and five categories of parent-offspring and sibling relationships R.
MakeAgePrior(
Pedigree = NULL,
LifeHistData = NULL,
MinAgeParent = NULL,
MaxAgeParent = NULL,
Discrete = NULL,
Flatten = NULL,
lambdaNW = -log(0.5)/100,
Smooth = TRUE,
Plot = TRUE,
Return = "LR",
quiet = FALSE
)A matrix with the probability ratio of the age difference between two individuals conditional on them being a certain type of relative (\(P(A|R)\)) versus being a random draw from the sample (\(P(A)\)). Assuming conditional independence, this equals the probability ratio of being a certain type of relative conditional on the age difference, versus being a random draw.
The matrix has one row per age difference (0 - nAgeClasses) and five columns, one for each relationship type, with abbreviations:
Mothers
Fathers
Full siblings
Maternal half-siblings
Paternal half-siblings
When Return='all', a list is returned with the following elements:
vector length 2
vector length 2, see details
matrix with the counts per age difference (rows) / relationship (columns) combination, plus a column 'X' with age differences across all pairs of individuals
Proportions, i.e. tblA.R divided by its colSums,
with full-sibling correction applied if necessary (see vignette).
Proportions PA.R standardised by global age
difference distribution (column 'X'); LR.RU.A prior to flattening
and smoothing
vector length 4, the weights used to flatten the distributions
the ageprior, flattend and/or smoothed
the names of the input Pedigree and
LifeHistData (or NULL), lambdaNW, and the 'effective'
settings (i.e. after any automatic update) of Discrete,
Smooth, and Flatten.
dataframe with id - dam - sire in columns 1-3, and optional column with birth years. Other columns are ignored.
dataframe with 3 or 5 columns: id - sex (not used) - birthyear (optional columns BY.min - BY.max - YearLast not used), with unknown birth years coded as negative numbers or NA. "Birth year" may be in any arbitrary discrete time unit relevant to the species (day, month, decade), as long as parents are never born in the same time unit as their offspring. It may include individuals not in the pedigree, and not all individuals in the pedigree need to be in LifeHistData.
minimum age of a parent, a single number (min across dams and sires) or a vector of length two (dams, sires). Defaults to 1. When there is a conflict with the minimum age in the pedigree, the pedigree takes precedent.
maximum age of a parent, a single number (max across
dams and sires) or a vector of length two (dams, sires). If NULL, it will
be set to latest - earliest birth year in LifeHistData, or estimated
from the pedigree if one is provided. See details below.
discrete generations? By default (NULL), discrete
generations are assumed if all parent-offspring pairs have an age
difference of 1, and all siblings an age difference of 0, and there are at
least 20 pairs of each category (mother, father, maternal sibling, paternal
sibling). Otherwise, overlapping generations are presumed. When
Discrete=TRUE (explicitly or deduced), Smooth and
Flatten are always automatically set to FALSE. Use
Discrete=FALSE to enforce (potential for) overlapping generations.
logical. To deal with small sample sizes for some or all
relationships, calculate weighed average between the observed age
difference distribution among relatives and a flat (0/1) distribution. When
Flatten=NULL (the default) automatically set to TRUE when there are
fewer than 20 parents with known age of either sex assigned, or fewer than
20 maternal or paternal siblings with known age difference. Also advisable
if the sampled relative pairs with known age difference are non-typical of
the pedigree as a whole.
control weighing factors when Flatten=TRUE. Weights
are calculated as \(W(R) = 1 - exp(-lambdaNW * N(R))\), where \(N(R)\)
is the number of pairs with relationship R for which the age difference is
known. Large values (>0.2) put strong emphasis on the pedigree, small
values (<0.0001) cause the pedigree to be ignored. Default results in
\(W=0.5\) for \(N=100\).
smooth the tails of and any dips in the distribution? Sets dips
(<10% of average of neighbouring ages) to the average of the neighbouring
ages, sets the age after the end (oldest observed age) to LR(end)/2, and
assigns a small value (0.001) to the ages before the front (youngest
observed age) and after the new end. Peaks are not smoothed out, as these
are less likely to cause problems than dips, and are more likely to be
genuine characteristics of the species. Is set to FALSE when
generations do not overlap (Discrete=TRUE).
plot a heatmap of the results?
return only a matrix with the likelihood-ratio \(P(A|R) /
P(A)\) ("LR") or a list including also various intermediate
statistics ("all") ?
suppress messages.
The small sample correction with Smooth and/or Flatten
prevents errors in one dataset, but may introduce errors in another; a
single solution that fits to the wide variety of life histories and
datasets is impossible. Please do inspect the matrix, e.g. with
PlotAgePrior, and adjust the input parameters and/or the output
matrix as necessary.
When all individuals in LifeHistData have the same birth year, it is
assumed that Discrete=TRUE and MaxAgeParent=1. Consequently,
it is assumed there are no avuncular pairs present in the sample; cousins
are considered as alternative. To enforce overlapping generations, and
thereby the consideration of full- and half- avuncular relationships, set
MaxAgeParent to some value greater than \(1\).
When no birth year information is given at all, a single cohort is assumed, and the same rules apply.
"Birth year" may be in any arbitrary time unit relevant to the species (day, month, decade), as long as parents are always born before their putative offspring, and never in the same time unit (e.g. parent's BirthYear= 1 (or 2001) and offspring BirthYear=5 (or 2005)). Negative numbers and NA's are interpreted as unknown, and fractional numbers are not allowed.
The maximum parental age for each sex equals the maximum of:
the maximum age of parents in Pedigree,
the input parameter MaxAgeParent,
the maximum range of birth years in LifeHistData (including
BY.min and BY.max). Only used if both of the previous are NA, or
if there are fewer than 20 parents of either sex assigned.
1, if Discrete=TRUE or the previous three are all NA
If the age distribution of assigned parents does not capture the maximum
possible age of parents, it is advised to specify MaxAgeParent for
one or both sexes. Not doing so may hinder subsequent assignment of both
dummy parents and grandparents. Not compatible with Smooth. If the
largest age difference in the pedigree is larger than the specified
MaxAgeParent, the pedigree takes precedent (i.e. the largest of the
two is used).
@section grandparents & avuncular
The agepriors for grand-parental and avuncular pairs is calculated from
these by sequoia, and included in its output as
`AgePriorExtra`.
\(\alpha_{A,R}\) is the ratio between the observed counts of pairs with age difference A and relationship R (\(N_{A,R}\)), and the expected counts if age and relationship were independent (\(N_{.,.}*p_A*p_R\)).
During pedigree reconstruction, \(\alpha_{A,R}\) are multiplied by the genetic-only \(P(R|G)\) to obtain a probability that the pair are relatives of type R conditional on both their age difference and their genotypes.
The age-difference prior is used for pairs of genotyped individuals, as well as for dummy individuals. This assumes that the propensity for a pair with a given age difference to both be sampled does not depend on their relationship, so that the ratio \(P(A|R) / P(A)\) does not differ between sampled and unsampled pairs.
For further details, see the vignette.
sequoia and its argument args.AP,
PlotAgePrior for visualisation. The age vignette gives
further details, mathematical justification, and some examples.
# without pedigree or lifehistdata:
MakeAgePrior(MaxAgeParent = c(2,3))
MakeAgePrior(Discrete=TRUE)
# single cohort:
MakeAgePrior(LifeHistData = data.frame(ID = letters[1:5], Sex=3,
BirthYear=1984))
# overlapping generations:
# without pedigree: MaxAgeParent = max age difference between any pair +1
MakeAgePrior(LifeHistData = SeqOUT_griffin$LifeHist)
# with pedigree:
MakeAgePrior(Pedigree=Ped_griffin,
LifeHistData=SeqOUT_griffin$LifeHist,
Smooth=FALSE, Flatten=FALSE)
# with small-sample correction:
MakeAgePrior(Pedigree=Ped_griffin,
LifeHistData=SeqOUT_griffin$LifeHist,
Smooth=TRUE, Flatten=TRUE)
# Call from sequoia() via args.AP:
Seq_HSg5 <- sequoia(SimGeno_example, LH_HSg5, Module="par",
args.AP=list(Discrete = TRUE), # non-overlapping generations
CalcLLR = FALSE, # skip time-consuming calculation of LLR's
Plot = FALSE) # no summary plots when finished
Run the code above in your browser using DataLab