Package 'ggpedigree' reference manual

Title:	Visualizing Pedigrees with 'ggplot2' and 'plotly'
Description:	Provides plotting functions for visualizing pedigrees and family trees. The package complements a behavior genetics package 'BGmisc' [Garrison et al. (2024) <doi:10.21105/joss.06203>] by rendering pedigrees using the 'ggplot2' framework. Features include support for duplicated individuals, complex mating structures, integration with simulated pedigrees, and layout customization. Due to the impending deprecation of kinship2, version 1.0 incorporates the layout helper functions from kinship2. The pedigree alignment algorithms are adapted from 'kinship2' [Sinnwell et al. (2014) <doi:10.1159/000363105>]. We gratefully acknowledge the original authors: Jason Sinnwell, Terry Therneau, Daniel Schaid, and Elizabeth Atkinson for their foundational work.
Authors:	S. Mason Garrison [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-4804-6003>)
Maintainer:	S. Mason Garrison <[email protected]>
License:	GPL (>= 3)
Version:	1.2.0.90
Built:	2026-06-12 17:57:13 UTC
Source:	https://github.com/r-computing-lab/ggpedigree

A pedigree of ice and fire

Description

A structured dataset of fictional characters derived from the Song of Ice and Fire universe by George R. R. Martin. The character relationships were partially based on a GEDCOM file publicly posted in the [Westeros.org forum](https://asoiaf.westeros.org/index.php?/topic/88863-all-the-family-trees/), and were updated based on publicly available summaries from [A Wiki of Ice and Fire](https://awoiaf.westeros.org/index.php/Main_Page). This dataset was created for educational and illustrative purposes, such as demonstrating pedigree construction, relationship tracing, and algorithmic logic in family-based data. It includes no narrative content or protected expression from the original works. No rights to the characters, names, or intellectual property of George R. R. Martin or HBO are claimed, and the dataset is not intended to represent any real individuals or families.

Usage

data(ASOIAF)
data(ASOIAF)

Format

A data frame with 679 observations on 9 variables.

Details

The variables are as follows:

id: Person identification variable
famID: Family identification variable
momID: ID of the mother
dadID: ID of the father
name: Name of the person
sex: Biological sex (M/F)
url: URL to a wiki page about the character
twinID: ID of the twin, if applicable
zygosity: Zygosity of the twin, if applicable. mz is monozygotic; dz is dizygotic

Examples

# Load the ASOIAF dataset
data(ASOIAF)
df_ASOIAF <- ASOIAF[ASOIAF$famID == 26, ] # Subset to House Tarth
# View the structure of the dataset
str(df_ASOIAF)

# Plot a pedigree for House Tarth
if (requireNamespace("ggplot2", quietly = TRUE)) {
  # Create a pedigree plot for House Tarth
  ggPedigree(df_ASOIAF,
    famID = "famID",
    personID = "id",
    momID = "momID",
    dadID = "dadID",
    config = list(
      add_phantoms = TRUE,
      code_male = "M"
    )
  )
}
# Load the ASOIAF dataset
data(ASOIAF)
df_ASOIAF <- ASOIAF[ASOIAF$famID == 26, ] # Subset to House Tarth
# View the structure of the dataset
str(df_ASOIAF)

# Plot a pedigree for House Tarth
if (requireNamespace("ggplot2", quietly = TRUE)) {
  # Create a pedigree plot for House Tarth
  ggPedigree(df_ASOIAF,
    famID = "famID",
    personID = "id",
    momID = "momID",
    dadID = "dadID",
    config = list(
      add_phantoms = TRUE,
      code_male = "M"
    )
  )
}

Calculate connections for a pedigree dataset

Description

Computes graphical connection paths for a pedigree layout, including parent-child, sibling, and spousal connections. Optionally processes duplicate appearances of individuals (marked as 'extra') to ensure relational accuracy.

Usage

calculateConnections(
  ped,
  config = list(),
  spouseID = "spouseID",
  personID = "personID",
  momID = "momID",
  famID = "famID",
  twinID = "twinID",
  dadID = "dadID"
)
calculateConnections(
  ped,
  config = list(),
  spouseID = "spouseID",
  personID = "personID",
  momID = "momID",
  famID = "famID",
  twinID = "twinID",
  dadID = "dadID"
)

Arguments

ped

A data frame containing the pedigree data. Needs personID, momID, dadID, and sex columns.

config

List of configuration parameters. Currently unused but passed through to internal helpers.

spouseID

Character string specifying the column name for spouse IDs. Defaults to "spouseID".

personID

Character string specifying the column name for individual IDs. Defaults to "personID".

momID

Character string specifying the column name for mother IDs. Defaults to "momID".

famID

Character string specifying the column name for family IDs. Defaults to "famID".

twinID

Character string specifying the column name for twin IDs. Defaults to "twinID".

dadID

Character string specifying the column name for father IDs. Defaults to "dadID".

Value

A 'data.frame' containing connection points and midpoints for graphical rendering. Includes:

'x_pos', 'y_pos': positions of focal individual
'x_dad', 'y_dad', 'x_mom', 'y_mom': parental positions (if available)
'x_spouse', 'y_spouse': spousal positions (if available)
'x_mid_parent', 'y_mid_parent': midpoint between parents
'x_mid_sib', 'y_mid_sib': sibling group midpoint
'x_mid_spouse', 'y_mid_spouse': midpoint between spouses

Examples

ped <- data.frame(
  personID = c("A", "B", "C", "D", "X"),
  momID = c(NA, "A", "A", "C", NA),
  dadID = c(NA, "X", "X", "B", NA),
  spouseID = c("X", "C", "B", NA, "A"),
  sex = c("F", "M", "F", "F", "M")
)

coords <- calculateCoordinates(ped, code_male = "M")
conns <- calculateConnections(coords, config = list(code_male = "M"))
names(conns)
head(conns$connections)

ped <- data.frame(
  personID = c("A", "B", "C", "D", "X"),
  momID = c(NA, "A", "A", "C", NA),
  dadID = c(NA, "X", "X", "B", NA),
  spouseID = c("X", "C", "B", NA, "A"),
  sex = c("F", "M", "F", "F", "M")
)

coords <- calculateCoordinates(ped, code_male = "M")
conns <- calculateConnections(coords, config = list(code_male = "M"))
names(conns)
head(conns$connections)

Calculate coordinates for plotting individuals in a pedigree

Description

Extracts and modifies the x and y positions for each individual in a pedigree data frame using the align.pedigree function from the 'kinship2' package. It returns a data.frame with positions for plotting.

Usage

calculateCoordinates(
  ped,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID",
  sexVar = "sex",
  twinID = "twinID",
  code_male = NULL,
  config = list()
)
calculateCoordinates(
  ped,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID",
  sexVar = "sex",
  twinID = "twinID",
  code_male = NULL,
  config = list()
)

Arguments

ped

A data frame containing the pedigree data. Needs personID, momID, dadID, and sex columns.

personID

Character string specifying the column name for individual IDs. Defaults to "personID".

momID

Character string specifying the column name for mother IDs. Defaults to "momID".

dadID

Character string specifying the column name for father IDs. Defaults to "dadID".

spouseID

Character. Name of the column in 'ped' for the spouse ID variable.

sexVar

Character. Name of the column in 'ped' for the sex variable.

twinID

Character string specifying the column name for twin IDs. Defaults to "twinID".

code_male

Value used to indicate male sex. Defaults to NULL.

config

List of configuration options:

code_male: Default is 1. Used by BGmisc::recodeSex().
ped_packed: Logical, default TRUE. Passed to 'kinship2_align.pedigree'.
ped_align: Logical, default TRUE. Align generations.
ped_width: Numeric, default 15. Controls spacing.

Value

A data frame with one or more rows per person, each containing:

'x_order', 'y_order': Grid indices representing layout rows and columns.
'x_pos', 'y_pos': Continuous coordinate positions used for plotting.
'nid': Internal numeric identifier for layout mapping.
'extra': Logical flag indicating whether this row is a secondary appearance.

Examples

# Load example data
data(potter, package = "BGmisc")

# Calculate coordinates for the pedigree
coords <- calculateCoordinates(
  ped = potter,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  code_male = 1
)

# View the coordinates
head(coords)

# Example with custom configuration
coords_custom <- calculateCoordinates(
  ped = potter,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  code_male = 1,
  config = list(
    ped_packed = FALSE,
    ped_width = 20
  )
)
# Load example data
data(potter, package = "BGmisc")

# Calculate coordinates for the pedigree
coords <- calculateCoordinates(
  ped = potter,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  config = list(
    code_male = 1
  )
)

# View the coordinates
head(coords)

# Example with custom configuration
coords_custom <- calculateCoordinates(
  ped = potter,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  config = list(
    ped_packed = FALSE,
    ped_width = 20
  )
)
# Load example data
data(potter, package = "BGmisc")

# Calculate coordinates for the pedigree
coords <- calculateCoordinates(
  ped = potter,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  code_male = 1
)

# View the coordinates
head(coords)

# Example with custom configuration
coords_custom <- calculateCoordinates(
  ped = potter,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  code_male = 1,
  config = list(
    ped_packed = FALSE,
    ped_width = 20
  )
)
# Load example data
data(potter, package = "BGmisc")

# Calculate coordinates for the pedigree
coords <- calculateCoordinates(
  ped = potter,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  config = list(
    code_male = 1
  )
)

# View the coordinates
head(coords)

# Example with custom configuration
coords_custom <- calculateCoordinates(
  ped = potter,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  config = list(
    ped_packed = FALSE,
    ped_width = 20
  )
)

Compute distance between two points

Description

This function calculates the distance between two points in a 2D space using Minkowski distance. It can be used to compute Euclidean or Manhattan distance. It is a utility function for calculating distances in pedigree layouts. Defaults to Euclidean distance if no method is specified.

Usage

computeDistance(method = "euclidean", x1, y1, x2, y2, p = NULL)
computeDistance(method = "euclidean", x1, y1, x2, y2, p = NULL)

Arguments

method

Character. Method of distance calculation. Options are "euclidean", "cityblock", and "Minkowski".

x1

Numeric. X-coordinate of the first point.

y1

Numeric. Y-coordinate of the first point.

x2

Numeric. X-coordinate of the second point.

y2

Numeric. Y-coordinate of the second point.

p

Numeric. The order of the Minkowski distance. If NULL, defaults to 2 for Euclidean and 1 for Manhattan. If Minkowski method is used, p should be specified.

Count offspring of each individual

Description

Count offspring of each individual

Usage

countOffspring(ped, personID = "ID", momID = "momID", dadID = "dadID")
countOffspring(ped, personID = "ID", momID = "momID", dadID = "dadID")

Arguments

ped

A data frame containing the pedigree information

personID

character. Name of the column in ped for the person ID variable

momID

character. Name of the column in ped for the mother ID variable

dadID

character. Name of the column in ped for the father ID variable

Value

A data frame with an additional column, offspring, that contains the number of offspring for each individual

Examples

library(BGmisc)
data("potter")
countOffspring(potter,
  personID = "personID",
  momID = "momID", dadID = "dadID"
)

library(BGmisc)
data("potter")
countOffspring(potter,
  personID = "personID",
  momID = "momID", dadID = "dadID"
)

Count siblings of each individual

Description

Count siblings of each individual

Usage

countSiblings(ped, personID = "ID", momID = "momID", dadID = "dadID")
countSiblings(ped, personID = "ID", momID = "momID", dadID = "dadID")

Arguments

ped

A data frame containing the pedigree information

personID

character. Name of the column in ped for the person ID variable

momID

character. Name of the column in ped for the mother ID variable

dadID

character. Name of the column in ped for the father ID variable

Value

A data frame with an additional column, siblings, that contains the number of siblings for each individual

Examples

library(BGmisc)
data("potter")
countSiblings(potter, personID = "personID")

library(BGmisc)
data("potter")
countSiblings(potter, personID = "personID")

Generate a spouselist matrix

Description

Generate a spouselist matrix

Usage

generateSpouseList(
  ped,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID"
)
generateSpouseList(
  ped,
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID"
)

Arguments

ped

A data frame containing the pedigree information

personID

Character. Name of the column in ped for the person ID variable

momID

Character. Name of the column in ped for the mother ID variable

dadID

Character. Name of the column in ped for the father ID variable

spouseID

Character. Name of the column in ped for the spouse ID variable

Value

A spouselist matrix

Examples

library(BGmisc)
data("potter")
generateSpouseList(potter,
  personID = "personID",
  momID = "momID", dadID = "dadID", spouseID = "spouseID"
)
library(BGmisc)
data("potter")
generateSpouseList(potter,
  personID = "personID",
  momID = "momID", dadID = "dadID", spouseID = "spouseID"
)

Plot a custom pedigree diagram

Description

Generates a ggplot2-based diagram of a pedigree using custom coordinate layout, calculated relationship connections, and flexible styling via 'config'. It processes the data using 'ped2fam()'. This function supports multiple families and optionally displays affected status and sex-based color/shape.

Usage

ggPedigree(
  ped,
  famID = "famID",
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID",
  matID = "matID",
  patID = "patID",
  twinID = "twinID",
  status_column = NULL,
  focal_fill_column = NULL,
  tooltip_columns = NULL,
  overlay_column = NULL,
  overlays = NULL,
  return_widget = FALSE,
  config = list(),
  debug = FALSE,
  hints = NULL,
  interactive = FALSE,
  code_male = NULL,
  sexVar = "sex",
  affected_fill_column = NULL,
  outline_color_column = NULL
)

ggpedigree(
  ped,
  famID = "famID",
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID",
  matID = "matID",
  patID = "patID",
  twinID = "twinID",
  status_column = NULL,
  focal_fill_column = NULL,
  tooltip_columns = NULL,
  overlay_column = NULL,
  overlays = NULL,
  return_widget = FALSE,
  config = list(),
  debug = FALSE,
  hints = NULL,
  interactive = FALSE,
  code_male = NULL,
  sexVar = "sex",
  affected_fill_column = NULL,
  outline_color_column = NULL
)
ggPedigree(
  ped,
  famID = "famID",
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID",
  matID = "matID",
  patID = "patID",
  twinID = "twinID",
  status_column = NULL,
  focal_fill_column = NULL,
  tooltip_columns = NULL,
  overlay_column = NULL,
  overlays = NULL,
  return_widget = FALSE,
  config = list(),
  debug = FALSE,
  hints = NULL,
  interactive = FALSE,
  code_male = NULL,
  sexVar = "sex",
  affected_fill_column = NULL,
  outline_color_column = NULL
)

ggpedigree(
  ped,
  famID = "famID",
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID",
  matID = "matID",
  patID = "patID",
  twinID = "twinID",
  status_column = NULL,
  focal_fill_column = NULL,
  tooltip_columns = NULL,
  overlay_column = NULL,
  overlays = NULL,
  return_widget = FALSE,
  config = list(),
  debug = FALSE,
  hints = NULL,
  interactive = FALSE,
  code_male = NULL,
  sexVar = "sex",
  affected_fill_column = NULL,
  outline_color_column = NULL
)

Arguments

ped

A data frame containing the pedigree data. Needs personID, momID, dadID, and sex columns.

famID

Character string specifying the column name for family IDs. Defaults to "famID".

personID

Character string specifying the column name for individual IDs. Defaults to "personID".

momID

Character string specifying the column name for mother IDs. Defaults to "momID".

dadID

Character string specifying the column name for father IDs. Defaults to "dadID".

spouseID

Character string specifying the column name for spouse IDs. Defaults to "spouseID".

matID

Character string specifying the column name for maternal lines Defaults to "matID".

patID

Character string specifying the column name for paternal lines Defaults to "patID".

twinID

Character string specifying the column name for twin IDs. Defaults to "twinID".

status_column

Character string specifying the column name for affected status. Defaults to NULL.

focal_fill_column

Character string specifying the column name for focal fill color.

Character vector of column names to show when hovering. Defaults to c("personID", "sex"). Additional columns present in 'ped' can be supplied – they will be added to the Plotly tooltip text. Defaults to NULL, which uses the default tooltip columns.

overlay_column

Character string specifying the column name for overlay alpha values. For a single overlay, this is the simplest interface. For multiple overlays, use the overlays parameter instead.

overlays

A list of overlay specifications for adding multiple independent overlay layers. Each element should be a list with at minimum a column entry, plus optional entries: code_affected, shape, color, size, stroke, mode. Unspecified entries inherit from the overlay_* config defaults. When overlays is provided, overlay_column is ignored. Example: overlays = list(list(column = "DECES", shape = "cross"), list(column = "PROBAND", shape = 8, color = "red"))

return_widget

Logical; if TRUE (default) returns a plotly htmlwidget. If FALSE, returns the underlying plotly object (useful for further customization before printing).

config

A list of configuration options for customizing the plot. See getDefaultPlotConfig for details of each option. The list can include:

code_male: Integer or string. Value identifying males in the sex column. (typically 0 or 1) Default: 1
segment_spouse_color, segment_self_color: Character. Line colors for respective connection types.
segment_sibling_color, segment_parent_color, segment_offspring_color: Character. Line colors for respective connection types.
label_text_size, point_size, segment_linewidth: Numeric. Controls text size, point size, and line thickness.
generation_height: Numeric. Vertical spacing multiplier between generations. Default: 1.
shape_unknown, shape_female, shape_male, status_shape_affected: Integers. Shape codes for plotting each group.
sex_shape_labels: Character vector of labels for the sex variable. (default: c("Female", "Male", "Unknown"))
unaffected, affected: Values indicating unaffected/affected status.
sex_color_include: Logical. If TRUE, uses color to differentiate sex.
label_max_overlaps: Maximum number of overlaps allowed in repelled labels.
label_segment_color: Color used for label connector lines.

debug

Logical. If TRUE, prints debugging information. Default: FALSE.

hints

Data frame with hints for layout adjustments. Default: NULL.

interactive

Logical. If TRUE, generates an interactive plot using 'plotly'. Default: FALSE.

code_male

Integer or string. Value identifying males in the sex column. (typically 0 or 1) Default: 1

sexVar

Character string specifying the column name for sex. Defaults to "sex".

affected_fill_column

Character string specifying the column name for conditional affected fill. When provided, individuals matching the 'affected_fill_code_affected' config will have their symbols filled. Default is NULL.

outline_color_column

Character string specifying the column name for outline color control. When provided, individuals matching 'outline_color_code_affected' config will have colored outlines (e.g., blue for included). Default is NULL.

Value

A 'ggplot' object rendering the pedigree diagram.

Examples

library(BGmisc)
data("potter")
ggPedigree(potter, famID = "famID", personID = "personID")

data("hazard")
ggPedigree(hazard, famID = "famID", personID = "ID", config = list(code_male = 0))

library(BGmisc)
data("potter")
ggPedigree(potter, famID = "famID", personID = "personID")

data("hazard")
ggPedigree(hazard, famID = "famID", personID = "ID", config = list(code_male = 0))

Interactive pedigree plot (Plotly wrapper around ggPedigree)

Description

Generates an interactive HTML widget built on top of the static ggPedigree output. All layout, styling, and connection logic are inherited from ggPedigree(); this function simply augments the plot with Plotly hover, zoom, and pan functionality.

Usage

ggPedigreeInteractive(
  ped,
  famID = "famID",
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID",
  matID = "matID",
  patID = "patID",
  twinID = "twinID",
  status_column = NULL,
  tooltip_columns = NULL,
  focal_fill_column = NULL,
  overlay_column = NULL,
  overlays = NULL,
  config = list(optimize_plotly = TRUE),
  debug = FALSE,
  return_widget = TRUE,
  hints = NULL,
  code_male = NULL,
  sexVar = "sex",
  affected_fill_column = NULL,
  outline_color_column = NULL
)
ggPedigreeInteractive(
  ped,
  famID = "famID",
  personID = "personID",
  momID = "momID",
  dadID = "dadID",
  spouseID = "spouseID",
  matID = "matID",
  patID = "patID",
  twinID = "twinID",
  status_column = NULL,
  tooltip_columns = NULL,
  focal_fill_column = NULL,
  overlay_column = NULL,
  overlays = NULL,
  config = list(optimize_plotly = TRUE),
  debug = FALSE,
  return_widget = TRUE,
  hints = NULL,
  code_male = NULL,
  sexVar = "sex",
  affected_fill_column = NULL,
  outline_color_column = NULL
)

Arguments

ped

A data frame containing the pedigree data. Needs personID, momID, dadID, and sex columns.

famID

Character string specifying the column name for family IDs. Defaults to "famID".

personID

Character string specifying the column name for individual IDs. Defaults to "personID".

momID

Character string specifying the column name for mother IDs. Defaults to "momID".

dadID

Character string specifying the column name for father IDs. Defaults to "dadID".

spouseID

Character string specifying the column name for spouse IDs. Defaults to "spouseID".

matID

Character string specifying the column name for maternal lines Defaults to "matID".

patID

Character string specifying the column name for paternal lines Defaults to "patID".

twinID

Character string specifying the column name for twin IDs. Defaults to "twinID".

status_column

Character string specifying the column name for affected status. Defaults to NULL.

focal_fill_column

Character string specifying the column name for focal fill color.

overlay_column

Character string specifying the column name for overlay alpha values. For a single overlay, this is the simplest interface. For multiple overlays, use the overlays parameter instead.

overlays

config

A list of configuration options for customizing the plot. See getDefaultPlotConfig for details of each option. The list can include:

code_male: Integer or string. Value identifying males in the sex column. (typically 0 or 1) Default: 1
segment_spouse_color, segment_self_color: Character. Line colors for respective connection types.
segment_sibling_color, segment_parent_color, segment_offspring_color: Character. Line colors for respective connection types.
label_text_size, point_size, segment_linewidth: Numeric. Controls text size, point size, and line thickness.
generation_height: Numeric. Vertical spacing multiplier between generations. Default: 1.
shape_unknown, shape_female, shape_male, status_shape_affected: Integers. Shape codes for plotting each group.
sex_shape_labels: Character vector of labels for the sex variable. (default: c("Female", "Male", "Unknown"))
unaffected, affected: Values indicating unaffected/affected status.
sex_color_include: Logical. If TRUE, uses color to differentiate sex.
label_max_overlaps: Maximum number of overlaps allowed in repelled labels.
label_segment_color: Color used for label connector lines.

debug

Logical. If TRUE, prints debugging information. Default: FALSE.

return_widget

Logical; if TRUE (default) returns a plotly htmlwidget. If FALSE, returns the underlying plotly object (useful for further customization before printing).

hints

Data frame with hints for layout adjustments. Default: NULL.

code_male

Integer or string. Value identifying males in the sex column. (typically 0 or 1) Default: 1

sexVar

Character string specifying the column name for sex. Defaults to "sex".

affected_fill_column

outline_color_column

Value

A plotly htmlwidget (or plotly object if 'return_widget = FALSE')

Examples

library(BGmisc)
data("potter")
ggPedigreeInteractive(potter, famID = "famID", personID = "personID")


data(hazard)
ggPedigreeInteractive(
  hazard,
  famID = "famID",
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  config = list(
    code_male = 0,
    status_column = "affected",
    label_nudge_y = .25,
    label_include = TRUE,
    tooltip_include = TRUE,
    label_method = "geom_text",
    sex_color_include = TRUE
  ),
  tooltip_columns = c("personID", "birthYr", "onsetYr", "deathYr")
) |>
  plotly::layout(
    title = "Hazard Pedigree (interactive)",
    hoverlabel = list(bgcolor = "white"),
    margin = list(l = 50, r = 50, t = 50, b = 50)
  ) |>
  plotly::config(displayModeBar = TRUE)
library(BGmisc)
data("potter")
ggPedigreeInteractive(potter, famID = "famID", personID = "personID")


data(hazard)
ggPedigreeInteractive(
  hazard,
  famID = "famID",
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  config = list(
    code_male = 0,
    status_column = "affected",
    label_nudge_y = .25,
    label_include = TRUE,
    tooltip_include = TRUE,
    label_method = "geom_text",
    sex_color_include = TRUE
  ),
  tooltip_columns = c("personID", "birthYr", "onsetYr", "deathYr")
) |>
  plotly::layout(
    title = "Hazard Pedigree (interactive)",
    hoverlabel = list(bgcolor = "white"),
    margin = list(l = 50, r = 50, t = 50, b = 50)
  ) |>
  plotly::config(displayModeBar = TRUE)

Plot correlation of genetic relatedness by phenotype

Description

This function plots the phenotypic correlation as a function of genetic relatedness.

Usage

ggPhenotypeByDegree(
  df,
  y_var,
  y_se = NULL,
  y_stem_se = NULL,
  y_ci_lb = NULL,
  y_ci_ub = NULL,
  config = list(),
  data_prep = TRUE,
  ...
)
ggPhenotypeByDegree(
  df,
  y_var,
  y_se = NULL,
  y_stem_se = NULL,
  y_ci_lb = NULL,
  y_ci_ub = NULL,
  config = list(),
  data_prep = TRUE,
  ...
)

Arguments

df

Data frame containing pairwise summary statistics. Required columns:

addRel_min: Minimum relatedness per group
addRel_max: Maximum relatedness per group
n_pairs: Number of pairs at that relatedness
cnu: Indicator for shared nuclear environment (1 = yes, 0 = no)
mtdna: Indicator for shared mitochondrial DNA (1 = yes, 0 = no)

y_var

Name of the y-axis variable column (e.g., "r_pheno_rho").

y_se

Name of the standard error column (e.g., "r_pheno_se").

y_stem_se

Optional; base stem used to construct SE ribbon bounds. (e.g., "r_pheno")

y_ci_lb

Optional; lower bound for confidence interval (e.g., "r_pheno_ci_lb").

y_ci_ub

Optional; upper bound for confidence interval (e.g., "r_pheno_ci_ub").

config

A list of configuration overrides. Valid entries include:

filter_n_pairs: Minimum number of pairs to include (default: 500)
filter_degree_min: Minimum degree of relatedness (default: 0)
filter_degree_max: Maximum degree of relatedness (default: 7)
plot_title: Plot title
plot_subtitle: Plot subtitle
color_scale: Paletteer color scale name (e.g., "ggthemes::calc")
use_only_classic_kin: If TRUE, only classic kin are shown
group_by_kin: If TRUE, use classic kin × mtDNA for grouping
drop_classic_kin: If TRUE, remove classic kin rows
drop_non_classic_sibs: If TRUE, remove non-classic sibs (default: TRUE)
annotate_include: If TRUE, annotate mother/father/sibling points
annotate_x_shift: Relative x-axis shift for annotations
annotate_y_shift: Relative y-axis shift for annotations
point_size: Size of geom_point points (default: 1)
use_relative_degree: If TRUE, x-axis uses degree-of-relatedness scaling
grouping_column: Grouping column name (default: mtdna_factor)
value_rounding_digits: Number of decimal places for rounding (default: 2)
match_threshold_percent: Tolerance % for matching known degrees
max_degree_levels: Maximum number of degrees to consider

data_prep

Logical; if TRUE, performs data preparation steps.

...

Additional arguments passed to 'ggplot2' functions.

Value

A ggplot object containing the correlation plot.

Examples

## Not run: 
ggPhenotypeByDegree(
  df = df,
  y_var = "USA_flag_10_polychorFunction_rho",
  y_stem_se = "USA_flag_10_polychorFunction",
  y_se = "USA_flag_10_polychorFunction_se"
)

## End(Not run)
## Not run: 
ggPhenotypeByDegree(
  df = df,
  y_var = "USA_flag_10_polychorFunction_rho",
  y_stem_se = "USA_flag_10_polychorFunction",
  y_se = "USA_flag_10_polychorFunction_se"
)

## End(Not run)

Plot a relatedness matrix as a heatmap (ggpedigree style)

Description

Plots a relatedness matrix using ggplot2 with config options.

Usage

ggRelatednessMatrix(
  mat,
  config = list(),
  interactive = FALSE,
  tooltip_columns = NULL,
  personID = "personID",
  ...
)
ggRelatednessMatrix(
  mat,
  config = list(),
  interactive = FALSE,
  tooltip_columns = NULL,
  personID = "personID",
  ...
)

Arguments

mat

A square numeric matrix of relatedness values (precomputed, e.g., from ped2add).

config

A list of graphical and display parameters. See Details for available options.

interactive

Logical; if TRUE, returns an interactive plotly object.

A character vector of column names to include in tooltips.

personID

Character; name of the column containing unique person identifiers.

...

Additional arguments passed to ggplot2 layers.

Details

Config options include:

tile_color_palette: A vector of colors for the heatmap (default: Reds scale)
color_scale_midpoint: Numeric midpoint for diverging color scale (default: 0.25)
plot_title: Plot title
tile_cluster: Logical; should rows/cols be clustered (default: TRUE)
axis_x_label, axis_y_label: Axis labels
axis_text_size: Axis text size

Value

A ggplot object displaying the relatedness matrix as a heatmap.

Examples

# Example relatedness matrix
set.seed(123)
mat <- matrix(runif(100, 0, 1), nrow = 10)
rownames(mat) <- paste0("ID", 1:10)
colnames(mat) <- paste0("ID", 1:10)

# Plot the relatedness matrix
ggRelatednessMatrix(mat,
  config = list(
    tile_color_palette = c("white", "gold", "red"),
    color_scale_midpoint = 0.5,
    tile_cluster = TRUE,
    plot_title = "Relatedness Matrix",
    axis_x_label = "Individuals",
    axis_y_label = "Individuals",
    axis_text_size = 8
  )
)
# Example relatedness matrix
set.seed(123)
mat <- matrix(runif(100, 0, 1), nrow = 10)
rownames(mat) <- paste0("ID", 1:10)
colnames(mat) <- paste0("ID", 1:10)

# Plot the relatedness matrix
ggRelatednessMatrix(mat,
  config = list(
    tile_color_palette = c("white", "gold", "red"),
    color_scale_midpoint = 0.5,
    tile_cluster = TRUE,
    plot_title = "Relatedness Matrix",
    axis_x_label = "Individuals",
    axis_y_label = "Individuals",
    axis_text_size = 8
  )
)

Automatically generate alignment hints for pedigree plotting

Description

This function automatically generates alignment hints for pedigree plotting. Hints control the relative horizontal positioning of subjects within their generation and the placement of spouse pairs. The function handles twins, multiple marriages, and complex pedigree structures. It is a somewhat optimized version of kinship2's autohint.

Usage

kinship2_autohint(ped, hints, packed = TRUE, align = FALSE)
kinship2_autohint(ped, hints, packed = TRUE, align = FALSE)

Arguments

ped

A pedigree object

hints

Optional existing hints (list with 'order' and optionally 'spouse' components)

packed

Logical, if TRUE uses compact packing algorithm (default TRUE)

align

Logical, if TRUE attempts to align spouses on the same level (default FALSE)

Details

The function is called automatically by kinship2_align.pedigree if no hints are provided. It analyzes the pedigree structure, identifies twins, handles multiple marriages, and determines optimal subject ordering to minimize crossing lines and produce aesthetically pleasing plots.

Full documentation is available in the align_code_details vignette.

Value

A list containing:

order

Numeric vector of relative ordering hints for subjects

spouse

Matrix of spouse pair information

plotPedigree A wrapped function to plot simulated pedigree from function `simulatePedigree`. This function require the installation of package `kinship2`.

Description

plotPedigree A wrapped function to plot simulated pedigree from function simulatePedigree. This function require the installation of package kinship2.

Usage

kinship2_plotPedigree(
  ped,
  code_male = NULL,
  verbose = FALSE,
  affected = NULL,
  cex = 0.5,
  col = 1,
  symbolsize = 1,
  branch = 0.6,
  packed = TRUE,
  align = c(1.5, 2),
  width = 8,
  density = c(-1, 35, 65, 20),
  mar = c(2.1, 1, 2.1, 1),
  angle = c(90, 65, 40, 0),
  keep.par = FALSE,
  pconnect = 0.5,
  ...
)

plotPedigree(...)
kinship2_plotPedigree(
  ped,
  code_male = NULL,
  verbose = FALSE,
  affected = NULL,
  cex = 0.5,
  col = 1,
  symbolsize = 1,
  branch = 0.6,
  packed = TRUE,
  align = c(1.5, 2),
  width = 8,
  density = c(-1, 35, 65, 20),
  mar = c(2.1, 1, 2.1, 1),
  angle = c(90, 65, 40, 0),
  keep.par = FALSE,
  pconnect = 0.5,
  ...
)

plotPedigree(...)

Arguments

ped

The simulated pedigree data.frame from function simulatePedigree. Or a pedigree dataframe with the same colnames as the dataframe simulated from function simulatePedigree.

code_male

This optional input allows you to indicate what value in the sex variable codes for male. Will be recoded as "M" (Male). If NULL, no recoding is performed.

verbose

logical If TRUE, prints additional information. Default is FALSE.

affected

This optional parameter can either be a string specifying the column name that indicates affected status or a numeric/logical vector of the same length as the number of rows in 'ped'. If NULL, no affected status is assigned.

cex

The font size of the IDs for each individual in the plot.

col

The color of the symbols in the plot.

symbolsize

The size of the symbols in the plot.

branch

The length of the branches in the plot.

packed

logical. If TRUE, the pedigree is drawn in a more compact form.

align

A numeric vector of length 2 indicating the alignment penalties for parents and spouses.

width

The width of the plot.

density

A numeric vector indicating the shading density for different affected statuses.

mar

A numeric vector of length 4 indicating the margins of the plot.

angle

A numeric vector indicating the shading angles for different affected statuses.

keep.par

logical. If TRUE, the current graphical parameters are preserved.

pconnect

A numeric value indicating the proportion of the pedigree to connect.

...

Additional arguments passed to kinship2::plot.pedigree

Value

A plot of the provided pedigree

Deprecated

'plotPedigree()' is deprecated; use 'kinship2_plotPedigree()' instead.

Optimize Pedigree Plot

Description

Optimize a pedigree plot by rounding coordinates to reduce file size.

Usage

optimizePedigree(p, config = list(), plot_type = c("plotly", "static"))
optimizePedigree(p, config = list(), plot_type = c("plotly", "static"))

Arguments

p

A plotly or ggplot object representing the pedigree plot.

config

A list of configuration parameters, including 'value_rounding_digits'.

plot_type

A string indicating the type of plot: "plotly" or "static". Default is "plotly". @return The optimized plot object with rounded coordinates. @keywords internal

Optimize Plotly Pedigree Plot

Description

Optimize a Plotly pedigree plot by rounding coordinates to reduce file size.

Usage

optimizePlotlyPedigree(p, config = list())
optimizePlotlyPedigree(p, config = list())

Arguments

p

A plotly object representing the pedigree plot.

config

A list of configuration parameters, including 'value_rounding_digits'.

Value

The optimized plotly object with rounded coordinates.

Create a pedigree or pedigreeList object

Description

Create a pedigree or pedigreeList object

Usage

pedigree(
  id,
  dadid,
  momid,
  sex,
  affected,
  status,
  relation,
  famid,
  missid,
  max_message_n = 5
)

## S3 method for class 'pedigreeList'
x[..., drop = FALSE]

## S3 method for class 'pedigree'
x[..., drop = FALSE]

## S3 method for class 'pedigree'
print(x, ...)

## S3 method for class 'pedigreeList'
print(x, ...)
pedigree(
  id,
  dadid,
  momid,
  sex,
  affected,
  status,
  relation,
  famid,
  missid,
  max_message_n = 5
)

## S3 method for class 'pedigreeList'
x[..., drop = FALSE]

## S3 method for class 'pedigree'
x[..., drop = FALSE]

## S3 method for class 'pedigree'
print(x, ...)

## S3 method for class 'pedigreeList'
print(x, ...)

Arguments

id

Identification variable for individual

dadid

Identification variable for father. Founders' parents should be coded to NA, or another value specified by missid.

momid

Identification variable for mother. Founders' parents should be coded to NA, or another value specified by missid.

sex

Gender of individual noted in ‘id’. Either character ("male","female", "unknown","terminated") or numeric (1="male", 2="female", 3="unknown", 4="terminated") data is allowed. For character data the string may be truncated, and of arbitrary case.

affected

A variable indicating affection status. A multi-column matrix can be used to give the status with respect to multiple traits. Logical, factor, and integer types are converted to 0/1 representing unaffected and affected, respectively. NAs are considered missing.

status

Censor/Vital status (0="censored", 1="dead")

relation

A matrix with 3 required columns (id1, id2, code) specifying special relationship between pairs of individuals. Codes: 1=Monozygotic twin, 2=Dizygotic twin, 3=Twin of unknown zygosity, 4=Spouse. (The last is necessary in order to place a marriage with no children into the plot.) If famid is given in the call to create pedigrees, then famid needs to be in the last column of the relation matrix. Note for tuples of >= 3 with a mixture of zygosities, the plotting is limited to showing pairwise zygosity of adjacent subjects, so it is only necessary to specify the pairwise zygosity, in the order the subjects are given or appear on the plot.

famid

An optional vector of family identifiers. If it is present the result will contain individual pedigrees for each family in the set, which can be extacted using subscripts. Individuals need to have a unique id within family.

missid

The founders are those with no father or mother in the pedigree. The dadid and momid values for these subjects will either be NA or the value of this variable. The default for missid is 0 if the id variable is numeric, and "" (empty string) otherwise.

max_message_n

max number of individuals to list in error messages

x

pedigree object in print and subset methods

...

optional arguments passed to internal functions

drop

logical, used in subset function for dropping dimensionality

Value

An object of class pedigree or pedigreeList Containing the following items: famid id findex mindex sex affected status relation

Author(s)

Terry Therneau

Kluane Red Squirrel Data

Description

A tidy data frame of life‐history and reproductive metrics for 7,799 individual red squirrels from the Kluane Red Squirrel Project (1987–present).

Usage

data(redsquirrels)

data(redsquirrels_full)
data(redsquirrels)

data(redsquirrels_full)

Format

## 'redsquirrels_full' A data frame with 7799 rows and 16 columns:

personID: Unique identifier for each squirrel
momID, dadID: Unique identifiers for each squirrel's parents
sex: Biological sex of the squirrel
famID: Unique identifier for each family. Derived from ped2fam
byear: Birth year of the squirrel
dyear: Death year of the squirrel
lrs: lifetime reproductive success for the squirrel
ars_mean: Mean annual reproductive success for the squirrel
ars_max: Maximum ARS value for the squirrel
ars_med: Median ARS value for the squirrel
ars_min: Minimum ARS value for the squirrel
ars_sd: Standard deviation of ARS values for the squirrel
ars_n: Number of ARS values for the squirrel
year_first: First year of ARS data for the squirrel
year_last: Last year of ARS data for the squirrel

...

## 'redsquirrels' A data frame with 5251 rows and 16 columns: A subset of redsquirrels_full intended for convenient analysis and examples. (Same variables as redsquirrels_full, with fewer rows.)

An object of class tbl_df (inherits from tbl, data.frame) with 7799 rows and 16 columns.

Details

#' This package provides two related datasets:

redsquirrels_full: the complete dataset from the published source
redsquirrels: a more workable subset derived from redsquirrels_full

Each row corresponds to one squirrel with associated pedigree links and reproductive success summaries.

The original data are published under a CC0 1.0 Universal Public Domain Dedication:

McFarlane, S. Eryn; Boutin, Stan; Humphries, Murray M. et al. (2015). Data from: Very low levels of direct additive genetic variance in fitness and fitness components in a red squirrel population [Dataset]. Dryad. <https://doi.org/10.5061/dryad.n5q05>

Source

<https://doi.org/10.5061/dryad.n5q05>

Examples


# Load the red squirrels datasets
data(redsquirrels)
data(redsquirrels_full)

# View the structure of the dataset(s)
str(redsquirrels)
str(redsquirrels_full)

# Plot a pedigree for a single family
if (requireNamespace("ggplot2", quietly = TRUE)) {
  # Select one family to plot
  family_data <- subset(redsquirrels, famID == 160)

  # Create a pedigree plot
  ggPedigree(family_data,
    personID = "personID",
    momID = "momID",
    dadID = "dadID",
    sex = "sex",
    config = list(
      add_phantoms = TRUE,
      code_male = "M"
    )
  )
}
# Load the red squirrels datasets
data(redsquirrels)
data(redsquirrels_full)

# View the structure of the dataset(s)
str(redsquirrels)
str(redsquirrels_full)

# Plot a pedigree for a single family
if (requireNamespace("ggplot2", quietly = TRUE)) {
  # Select one family to plot
  family_data <- subset(redsquirrels, famID == 160)

  # Create a pedigree plot
  ggPedigree(family_data,
    personID = "personID",
    momID = "momID",
    dadID = "dadID",
    sex = "sex",
    config = list(
      add_phantoms = TRUE,
      code_male = "M"
    )
  )
}

Wars of the Roses Pedigree Data

Description

A pedigree dataset representing the familial relationships among key figures in the historical War of the Roses, a series of English civil wars for control of the throne of England fought between the houses of Lancaster and York during the 15th century. This dataset includes information on individuals' parentage, birth and death years, and titles, allowing for the exploration of lineage, alliances, and succession during this tumultuous period in English history.

Usage

data(warsofroses)
data(warsofroses)

Format

A data frame with many observations on 6 variables.

Details

The variables are as follows:

id: Person identification variable
momID: ID of the mother
dadID: ID of the father
name: Name of the person
sex: Biological sex
url: URL to a wiki page about the character

Source

<https://en.wikipedia.org/wiki/Wars_of_the_Roses#Family_tree>

Package 'ggpedigree'

Help Index

A pedigree of ice and fire

Description

Usage

Format

Details

Examples

Calculate connections for a pedigree dataset

Description

Usage

Arguments

Value

See Also

Examples

Calculate coordinates for plotting individuals in a pedigree

Description

Usage

Arguments

Value

Examples

Compute distance between two points

Description

Usage

Arguments

Count offspring of each individual

Description

Usage

Arguments

Value

Examples

Count siblings of each individual

Description

Usage

Arguments

Value

Examples

Generate a spouselist matrix

Description

Usage

Arguments

Value

Examples

Plot a custom pedigree diagram

Description

Usage

Arguments

Value

See Also

Examples

Interactive pedigree plot (Plotly wrapper around ggPedigree)

Description

Usage

Arguments

Value

See Also

Examples

Plot correlation of genetic relatedness by phenotype

Description

Usage

Arguments

Value

See Also

Examples

Plot a relatedness matrix as a heatmap (ggpedigree style)

Description

Usage

Arguments

Details

Value

See Also

Examples

Automatically generate alignment hints for pedigree plotting

Description

Usage

Arguments

Details

Value

plotPedigree A wrapped function to plot simulated pedigree from function simulatePedigree. This function require the installation of package kinship2.

Description

plotPedigree A wrapped function to plot simulated pedigree from function `simulatePedigree`. This function require the installation of package `kinship2`.