ped_modify: Add/remove pedigree members

Description

Functions for adding or removing individuals in a 'ped' object.

Usage

addChildren(
  x,
  father = NULL,
  mother = NULL,
  nch = NULL,
  sex = 1L,
  ids = NULL,
  verbose = TRUE
)
addChild(x, parents, id = NULL, sex = 1, verbose = TRUE)
addSon(x, parents, id = NULL, verbose = TRUE)
addDaughter(x, parents, id = NULL, verbose = TRUE)
addParents(x, id, father = NULL, mother = NULL, verbose = TRUE)
addSibling(x, id, sex = 1, side = c("right", "left"), verbose = TRUE)
removeIndividuals(
  x,
  ids,
  remove = c("descendants", "ancestors", "exact"),
  returnLabs = FALSE,
  verbose = TRUE
)
trim(x, uninformative, verbose = TRUE)
branch(x, id)
# S3 method for ped
subset(x, subset, ..., missingParents = c("error", "exclude", "include"))

Value

The modified ped object.

Arguments

x: A ped object, or a list of such.
father, mother: Single ID labels. At least one of these must be an existing member of x. The other may be (i) another existing member, (ii) a new founder to be created, or (iii) missing (i.e., NULL), in which case the other parent is created and given a suitable name.
nch: A positive integer indicating the number of children to be created. Default: 1.
sex: A vector of integers indicating the sex of the created individuals. (1 = male, 2 = female, 0 = unknown). Recycled as needed.
ids: A vector of ID labels. In addChildren() these are the children to be created. If NULL (default) given, automatic labels are generated.
verbose: A logical.
parents: A vector of 1 or 2 ID labels, of which at least one must be an existing member of x.
id: The ID label of a pedigree member.
side: A word indicating whether a new sibling should be placed to the left or right of the indicated individual. Default: "right".
remove: Either "descendants" (default), "ancestors" or "exact", dictating the method of removing pedigree members. Abbreviations are allowed.
returnLabs: A logical, by default FALSE. If TRUE, removeIndividuals() returns only the labels of all members to be removed, instead of actually removing them.
uninformative: A vector naming individuals considered "uninformative", or a function (typically a helper function like untypedMembers()). Uninformative leaves are removed iteratively until no more can be found.
subset: A character vector (or coercible to such): A subset of the ID labels of x.
...: Not used.
missingParents: A word indicating how to deal with single parents in the subset. Either "error" (default), "exclude" (remove the parent-child connection) or "include" (expand subset to include the missing parents).

Details

In addChildren() and addParents(), labels of added individuals are generated automatically if they are not specified by the user. The automatic labelling uses the smallest integers not already in use.

addChild(), addSon() and addDaughter() are convenient wrappers for the most common use of addChildren(), namely adding a single child to a pedigree. Note that the parents can be given in any order. If only one parent is supplied, the other is created as a new individual.

addSibling() adds a sibling to the indicated individual, creating parents if necessary. The new sibling is placed either directly before or after the indicated individual, depending on the side argument. (But note that the internal ordering of individuals is not always respected when plotting the pedigree.)

removeIndividuals() removes the indicated individuals from the pedigree. If remove = "descendants" (default), their descendants are also removed, together with leftover spouses disconnected from the remaining pedigree. Setting remove = "ancestors" does the same, but removes upwards instead of downwards. Finally, if remove = "exact", only the indicated individuals are removed.

The branch() function extracts the sub-pedigree formed by id and all his/her descendants, and all necessary spouses. Note that some structure may be lost in this process; for instance, compare x = halfSibTriangle(3) with branch(x, 1).

The trim() function iteratively removes uninformative leaves (i.e., members without children) from the pedigree. Note that the definition of "uninformative" is entirely user-defined. For example, trim(x, untypedMembers), will remove untyped individuals from the bottom until the process stops.

Finally, subset() can be used to extract any sub-pedigree, returning a list of pedigrees if the result is disconnected. By default, an error is raised if some individuals would be left with exactly one parent. Alternatively, missingParents = "exclude" removes the parent-child connection in such cases, while missingParents = "include" adds the missing parent to the subset.

Examples

Run this code


# In examples below, plot each step to see the changes in the pedigree.

x = nuclearPed(1) |>
  addSon(3) |>
  addParents(4, father = 6, mother = 7) |>
  addChildren(father = 6, mother = 7, nch = 3, sex = c(2,1,2))

# Remove 6 and 7 and their descendants
y1 = removeIndividuals(x, 6:7)

# "exact" removal converts children to singletons
y2 = removeIndividuals(x, 6:7, remove = "exact")

# Remove 8-10 and their parents
y3 = removeIndividuals(x, 8:10, remove = "ancestors")

# Adding a child across components
z = singletons(1:2, sex = 1:2) |> addDaughter(1:2)

# Extract a branch
w = cousinPed(1, child = TRUE)
w4 = branch(w, 4)
plot(list(w, w4))

# General subsetting depends on `missingParent`:
subset(w, c(3,7), missingParents = "exclude")
subset(w, c(3,7), missingParents = "include")