reconstruct: Pedigree reconstruction

In magnusdv/pedbuildr: Pedigree Reconstruction

Pedigree reconstruction

Description

Reconstructs the most likely pedigree from genotype data.

Usage

reconstruct(
  x,
  ids,
  extra = "parents",
  alleleMatrix = NULL,
  loci = NULL,
  pedlist = NULL,
  inferPO = FALSE,
  sex = NULL,
  age = NULL,
  knownPO = NULL,
  knownSub = NULL,
  allKnown = FALSE,
  notPO = NULL,
  noChildren = NULL,
  connected = TRUE,
  maxInbreeding = 1/16,
  linearInb = FALSE,
  sexSymmetry = TRUE,
  sortResults = TRUE,
  founderInb = 0,
  numCores = 1,
  verbose = TRUE
)

Arguments

x	A pedtools::ped object or a list of such.
ids	A vector of ID labels from x. By default, the genotyped members of x are used.
extra	Either the word "parents" (default), or a non-negative integer. See Details.
alleleMatrix	A matrix with two columns for each marker. By default extracted from x
loci	A list of marker attributes. By default extracted from x.
pedlist	A list of pedigrees to optimise over. If NULL, buildPeds() is used to generate a list.
inferPO	A logical. If TRUE, an initial stage of pairwise IBD estimation is done to infer high-confidence parent/child pairs, and also non-parent/child pairs. When this option is used, arguments to knownPO and notPO are ignored.
sex	A vector of the same length as labs, with entries 1 (male) or 2 (female).
age	A numeric or character vector. If numeric, and age[i] < age[j], then individual i will not be an ancestor of individual j. The numbers themselves are irrelevant, only the partial ordering. (No inference is made about individuals of equal age.) Alternatively, for finer control, age may be a character vector of inequalities, e.g., age = c("1>2", "1>3").
knownPO	A list of vectors of length 2, containing the ID labels of pairs known to be parent-offspring. By default, both directions are considered; use age to force a specific direction.
knownSub	A ped object involving a subset of the labs individuals.
allKnown	A logical. If TRUE, no other pairs than knownPO will be assigned as parent-offspring. If FALSE (default), all pairs except those in notPO are treated as potential parent-offspring.
notPO	A list of vectors of length 2, containing the ID labels of pairs known not to be parent-offspring.
noChildren	A vector of ID labels, indicating individuals without children of their own.
connected	A logical. If TRUE (default), only connected pedigrees are returned.
maxInbreeding	A single numeric indicating the highest permitted inbreeding coefficient. Default: 1/16 (as with first-cousin parents.)
linearInb	A parameter controlling the maximum separation of linearly related spouses. Either TRUE (allow all linear inbreeding), FALSE (disallow all) or a non-negative integer. For example, linearInb = 1 allows parent/child mating, but not grandparent/grandchild or more distant linear relatives. Default: FALSE.
sexSymmetry	A logical. If TRUE (default), pedigrees which are equal except for the gender distribution of the added parents, are regarded as equivalent, and only one of each equivalence class is returned. Example: paternal vs. maternal half sibs.
sortResults	A logical. If TRUE (default), the output is sorted so that the most likely pedigree comes first.
founderInb	A number in the interval ⁠[0,1]⁠, used as background inbreeding level in all founders. Default: 0.
numCores	A positive integer. The number of cores used in parallelisation. Default: 1.
verbose	A logical.

Details

The parameter extra controls which of two algorithms are used to create the pedigree list.

If extra is a nonnegative integer, it determines the number of extra individuals allowed in the iterative pedigree construction. These extras start off with undetermined sex, meaning that both males and females are used. It should be noted that the final pedigrees may contain additional extras, since missing parents are added at the end.

If extra is the word "parents", the algorithm is not iterative. It first generates all directed acyclic graphs between the original individuals. Then their parents are added and merged in all possible ways. This option has the advantage of not requiring an explicit/ad hoc number of "extras", but works best in smaller cases.

Value

An object of class pedrec, which is essentially list with the following entries:

• labs: The individual labels as given in ids.

• pedlist: A list of pedigrees, either built by buildPeds() or as supplied in the input argument pedlist. If sortResults = TRUE, the list is sorted so that the most likely pedigrees come first

• logliks: A numerical vector of pedigree log-likelihoods

• kappa: A data frame with pairwise estimates (if inferPO = TRUE)

• alleleMatrix: A matrix of marker alleles

• loci: A list of marker locus attributes

• errPeds: A list of pedigrees for which the likelihood calculation failed

• errIdx: The indices of pedigrees in errPeds as elements of pedlist

Examples

#-----------------
# Example 1: Trio
#-----------------

# Built-in dataset `trioData`
x = list(singleton(1), singleton(2), singleton(3)) |>
  setMarkers(alleleMatrix = trioData, locusAttributes ="snp12")

res = reconstruct(x, inferPO = TRUE, age = "1 > 2")

# Plot most likely pedigrees
plot(res, top = 6)


#--------------------
# Example 2: Siblings
#--------------------
library(forrel)

ids = c("s1", "s2")

# Create pedigree and simulate profiles with 20 STR markers
y = nuclearPed(children = ids) |>
  profileSim(markers = NorwegianFrequencies[1:20], ids = ids, seed = 123)

# Reconstruct allowing 2 extra individuals and any inbreeding
res2 = reconstruct(y, extra = 2, maxInb = 1)
plot(res2)

# With mutation modelling
y = setMutmod(y, model = "equal", rate = 0.01)
res3 = reconstruct(y, extra = 2, maxInb = 1)
plot(res3)

magnusdv/pedbuildr documentation built on Aug. 30, 2023, 8:32 a.m.