pedtools (version 2.12.0)

breakLoops: Pedigree loops

Description

Functions for identifying, breaking and restoring loops in pedigrees.

Usage

breakLoops(
  x,
  loopBreakers = NULL,
  verbose = TRUE,
  errorIfFail = TRUE,
  score = NULL,
  allowFounder = TRUE,
  allowRepeated = TRUE
)
tieLoops(x, verbose = TRUE)
findLoopBreakers(
  x,
  score = NULL,
  errorIfFail = TRUE,
  allowFounder = TRUE,
  allowRepeated = TRUE
)

Value

For breakLoops(), a ped object in which the indicated loop breakers are duplicated. The returned object has a non-null LOOP_BREAKERS entry: a matrix with the internal IDs of the originals in the first column and the copies in the second. If loop breaking fails, then depending on errorIfFail, either an error is raised or the input pedigree is returned unchanged.

For tieLoops(), a ped object in which any duplicated individuals listed in x$LOOP_BREAKERS are merged back into their originals. For any ped object x, the call tieLoops(breakLoops(x)) should return x.

For findLoopBreakers(), a two-column character matrix giving suitable loop breakers in the first column and split children in the second.

Arguments

x

A ped() object.

loopBreakers

Either NULL, resulting in automatic selection of loop breakers, a vector indicating the individuals to be used as loop breakers, or a two-column matrix/data frame giving loop breakers and children.

verbose

A logical indicating whether to print progress messages.

errorIfFail

A logical. If TRUE, an error is raised if loop breaking fails. If FALSE, the pedigree is returned unchanged.

score

Optional preference scores used by findLoopBreakers(). Higher values are preferred. If named, the names are interpreted as individual labels. Otherwise the vector must have length pedsize(x).

allowFounder

A logical indicating if founders may be used as loop breakers.

allowRepeated

A logical indicating if the same individual may be used to break multiple loops.

Details

In pedtools and other pedsuite packages, pedigree loops are usually handled under the hood by the functions described here, without the need for explicit action from end users. When a ped object x is created, an internal routine detects if the pedigree contains loops, in which case x$UNBROKEN_LOOPS is set to TRUE.

In cases with complex inbreeding, it can be instructive to plot the pedigree after breaking the loops. Duplicated individuals are plotted with suitable labels (see examples).

The function findLoopBreakers() searches the marriage graph for cycles. For each cycle it chooses a suitable loop breaker and one child indicating which full-sibship should be moved.

The function breakLoops() then makes one founder copy of each selected loop breaker. For each pair of loop breaker and child, all children with the same parents as the indicated child are moved from the original parent to the copy. Repeating this removes the cycles, while recording the original and copied individuals in x$LOOP_BREAKERS so that tieLoops() can restore the original pedigree.

Loop breakers may also be supplied by the user. A vector gives the loop breakers themselves; for each one, a full-sibship is chosen automatically. Repeated values are allowed and select successive sibships of the same individual. Alternatively, loopBreakers may be a two-column matrix or data frame whose first column gives loop breakers and whose second column gives a child in the sibship to be moved.

Examples

x = cousinPed(1, child = TRUE)
plot(breakLoops(x))

# Pedigree with marriage loop: Double first cousins
y = doubleCousins(1, 1, child = TRUE)
y2 = breakLoops(y)
plot(y2)

# Alternatively, first find loop breakers, then break loops with them
lb = findLoopBreakers(y)
y3 = breakLoops(y, lb)
stopifnot(identical(y2, y3))

# Different set of loop breakers enforced
y4 = breakLoops(y, 6:7)
plot(y4)