ped_internal {pedtools}

Internal ordering of pedigree members

Description

These functions give access to - and enable modifications of - the order in which the members of a pedigree are stored. (This is the order in which the members are listed when a ped object is printed to the screen.)

Usage

reorderPed(x, neworder = NULL, internal = FALSE)

parentsBeforeChildren(x)

hasParentsBeforeChildren(x)

foundersFirst(x)

internalID(x, ids, errorIfUnknown = TRUE)

Arguments

x

A ped object. Most of these functions also accepts ped lists.

neworder

A permutation of labels(x) (or a subset of this), indicating the new internal ordering. If internal = TRUE, neworder refers to the internal ordering, so must be numeric. 1:pedsize(x). By default, the natural order of the ID labels is used.

internal

A logical (default: FALSE). If TRUE, neworder is interpreted as referring to the internal ordering.

ids

A character vector (or coercible to one) of original ID labels.

errorIfUnknown

A logical. If TRUE (default), the function stops with an error if not all elements of ids are recognised as names of members in x.

Details

The internal ordering is usually of little importance for end users, with one important exception: Certain pedigree-traversing algorithms require parents to precede their children. A special function, parentsBeforeChildren() is provided for this purpose. This is a wrapper of the more general reorderPed() which allows any permutation of the members.

It should be noted that ped() by default calls parentsBeforeChildren() whenever a pedigree is created, unless explicitly avoided with reorder = FALSE.

hasParentsBeforeChildren() can be used as a quick test to decide if it is necessary to call parentsBeforeChildren().

The foundersFirst() function reorders the pedigree so that all the founders come first.

The utility internalID() converts ID labels to indices in the internal ordering. If x is a list of pedigrees, the output is a data frame containing both the component number and internal ID (within the component).

See Also

ped()

Examples

x = ped(id = 3:1, fid = c(1,0,0), mid = c(2,0,0), sex = c(1,2,1), reorder = FALSE)
x

# The 'ids' argument is converted to character, hence these are the same:
internalID(x, ids = 3)
internalID(x, ids = "3")

hasParentsBeforeChildren(x)

# Put parents first
parentsBeforeChildren(x)

# Typical use of reorderPed: Swap sibling plot order
y = nuclearPed(2) |> reorderPed(4:3)
plot(y)


### If labels are numeric, argument `internal` is important
z = singleton(1) |> addParents(1)
z
reorderPed(z, 1:3, internal = FALSE) # ID order = "1","2","3"
reorderPed(z, 1:3, internal = TRUE)  # index order: 1,2,3 (i.e., no change)