plotmethods {pedtools}

Internal plot methods

Description

The main purpose of this page is to document the many options for pedigree plotting. Most of the arguments shown here may be supplied directly in plot(x, ...), where x is a pedigree. See plot.ped() for many examples.

Usage

.pedAlignment(
  x = NULL,
  plist = NULL,
  arrows = FALSE,
  twins = NULL,
  packed = TRUE,
  width = 10,
  align = c(1.5, 2),
  spouseOrder = NULL,
  hints = NULL,
  ...
)

.pedAnnotation(
  x,
  title = NULL,
  marker = NULL,
  sep = "/",
  missing = "-",
  showEmpty = FALSE,
  labs = labels(x),
  foldLabs = 12,
  trimLabs = TRUE,
  col = 1,
  fill = NA,
  lty = 1,
  lwd = 1,
  hatched = NULL,
  hatchDensity = 25,
  aff = NULL,
  carrier = NULL,
  deceased = NULL,
  starred = NULL,
  textAnnot = NULL,
  textInside = NULL,
  textAbove = NULL,
  fouInb = "autosomal",
  ...
)

.pedScaling(
  alignment,
  annotation,
  cex = 1,
  symbolsize = 1,
  margins = 1,
  addSpace = 0,
  xlim = NULL,
  ylim = NULL,
  vsep2 = FALSE,
  autoScale = FALSE,
  minsize = 0.15,
  ...
)

.drawPed(alignment, annotation, scaling)

.annotatePed(
  alignment,
  annotation,
  scaling,
  font = NULL,
  fam = NULL,
  col = NULL,
  colUnder = 1,
  colInside = 1,
  colAbove = 1,
  cex.main = NULL,
  font.main = NULL,
  col.main = NULL,
  ...
)

Arguments

x

A ped() object.

plist

Alignment list with format similar to kinship2::align.pedigree().

arrows

A logical (default = FALSE). If TRUE, the pedigree is plotted as a DAG, i.e., with arrows connecting parent-child pairs.

twins

A data frame with columns id1, id2 and code, passed on to the relation parameter of kinship2::plot.pedigree().

packed, width, align

Parameters passed on to kinship2::align.pedigree(). Can usually be left untouched.

spouseOrder

An optional vector (or list of vectors) indicating plot ordering for spouses. (This is converted into a matrix and forward as hints; see below.)

hints

An optional list of hints passed on to kinship2::align.pedigree().

...

Further parameters passed between methods.

title

The plot title. If NULL (default) or ”, no title is added to the plot.

marker

Either a vector of names or indices referring to markers attached to x, a marker object, or a list of such. The genotypes for the chosen markers are written below each individual in the pedigree, in the format determined by sep and missing. See also showEmpty. If NULL (the default), no genotypes are plotted.

sep

A character of length 1 separating alleles for diploid markers.

missing

The symbol (integer or character) for missing alleles.

showEmpty

A logical, indicating if empty genotypes should be included.

labs

A vector or function controlling the individual labels in the plot. By default, labels(x) are used. See Details for valid formats.

foldLabs

A number or function controlling the folding of long labels. If a number, line breaks are inserted at roughly this width, trying to break at break-friendly characters. If a function, this is applied to each label.

trimLabs

A logical, by default TRUE. Removes line breaks and tabs from both ends of the labels (after adding genotypes, if marker is not NULL).

col

A vector or list specifying outline colours for the pedigree members. See Details for valid formats.

fill

A vector or list specifying fill/hatch colours for the pedigree members. See Details for valid formats. Note that if fill is unnamed, and either aff or hatched are given, then the fill colour is applied only to those.

lty, lwd

Vectors or lists specifying linetype and width of pedigree symbol outlines. See Details for valid formats.

hatched

A vector of labels identifying members whose plot symbols should be hatched.

hatchDensity

A number specifying the hatch density in lines per inch. Default: 25.

aff

A vector of labels identifying members whose plot symbols should be filled. (This is typically used in medical pedigrees to indicate affected members.)

carrier

A vector of labels identifying members whose plot symbols should be marked with a dot. (This is typically used in medical pedigrees to indicate unaffected carriers of the disease allele.)

deceased

A vector of labels indicating deceased pedigree members.

starred

A vector of labels indicating pedigree members that should be marked with a star in the pedigree plot.

textAnnot

A list specifying further text annotation around or inside the pedigree symbols. See Details for more information.

textInside, textAbove

Character vectors of text to be printed inside or above pedigree symbols. [Soft deprecated; replaced by textAnnot.]

fouInb

Either "autosomal" (default), "x" or NULL. If "autosomal" or "x", inbreeding coefficients are added to the plot above the inbred founders. If NULL, or if no founders are inbred, nothing is added.

alignment

List of alignment details, as returned by .pedAlignment().

annotation

List of annotation details as returned by .pedAnnotation().

cex

Expansion factor controlling font size. This also affects symbol sizes, which by default have the width of 2.5 characters. Default: 1.

symbolsize

Expansion factor for pedigree symbols. Default: 1.

margins

A numeric indicating the plot margins. If a single number is given, it is recycled to length 4.

addSpace

A numeric of length 4, indicating extra padding (in inches) around the pedigree inside the plot region. Default: 0.

xlim, ylim

Numeric vectors of length 2, used to set par("usr") explicitly. Rarely needed by end users.

vsep2

A logical; for internal use.

autoScale

A logical. It TRUE, an attempt is made to adjust cex so that the symbol dimensions are at least minsize inches. Default: FALSE.

minsize

A positive number, by default 0.15. (See autoScale.)

scaling

List of scaling parameters as returned by .pedScaling().

font, fam

Arguments passed on to text().

colUnder, colInside, colAbove

Colour vectors.

cex.main, col.main, font.main

Parameters passed on to title().

Details

The workflow of plot.ped(x, ...) is approximately as follows:

# Calculate plot parameters

align = .pedAlignment(x, ...)

annot = .pedAnnotation(x, ...)

scale = .pedScaling(align, annot, ...)

# Produce plot

.drawPed(align, annot, scale)

.annotatePed(align, annot, scale)

The labs argument control the individual ID labels printed below the pedigree symbols. By default the output of labels(x) is used, but there are several alternative forms:

• If labs is a vector with nonempty intersection with labels(x), only these individuals will be labelled. If the vector is named, then the names are used instead of the ID label. (See Examples.)

• If labs is the word "num", then all individuals are numerically labelled following the internal ordering.

• Use labs = NULL to remove all labels.

• If labs is a function, it is replaced with labs(x) and handled as above. (See Examples.)

The argument textAnnot allows customised annotation around and inside each symbol. This takes a list of lists, whose names may include "topleft", "topright", "left", "right", "bottomleft", "bottom", "bottomright" and "inside". Each inner list should contain a character vector as its first element (with the text to printed), followed by further arguments passed to text(). For example, textAnnot = list(left = list(c(A = "1"), cex = 2)) prints a large number "1" to the left of individual A (if such an individual exists in the pedigree. See Examples.

The arguments col, fill, lty and lwd can all be indicated in a number of ways:

• An unnamed vector. This will be recycled and applied to all members. For example, lty = 2 gives everyone a dashed outline.

• A named vector. Only pedigree members appearing in the names are affected. Example: fill = c("1" = "red", foo = "blue") fills individual 1 red and foo blue.

• A list of ID vectors, where the list names indicate the parameter values. Example: col = list(red = 1:2, blue = 3:5).

• List entries may also be functions, taking the pedigree x as input and producing a vector of ID labels. The many built-in functions in ped_subgroups are particularly handy here, e.g.: fill = list(red = founders, blue = leaves).

Examples

x = nuclearPed()

align = .pedAlignment(x)
annot = .pedAnnotation(x)
scale = .pedScaling(align, annot)

frame()
drawPed(align, annot, scale)