| Title: | Visualizing Pedigrees with 'ggplot2' and 'plotly' |
| Version: | 1.0.0.1 |
| Date/Publication: | 2025-11-30 22:30:02 UTC |
| Description: | Provides plotting functions for visualizing pedigrees in behavior genetics and kinship research. The package complements 'BGmisc' [Garrison et al. (2024) <doi:10.21105/joss.06203>] by rendering pedigrees using the 'ggplot2' framework and offers a modern alternative to the base-graphics pedigree plot in 'kinship2' [Sinnwell et al. (2014) <doi:10.1159/000363105>]. Features include support for duplicated individuals, complex mating structures, integration with simulated pedigrees, and layout customization. |
| License: | GPL-3 |
| URL: | https://github.com/R-Computing-Lab/ggpedigree/, https://r-computing-lab.github.io/ggpedigree/ |
| BugReports: | https://github.com/R-Computing-Lab/ggpedigree/issues |
| Depends: | R (≥ 4.1.0) |
| Imports: | BGmisc (≥ 1.4.1), ggplot2, rlang, dplyr, stringr, utils, plotly, reshape2, scales, tidyr |
| Suggests: | kinship2, quadprog, ggrepel, paletteer, mockery, patchwork, viridis, knitr, tidyverse, purrr, data.table, discord, OpenMx, NlsyLinks, rmarkdown, tibble, corrplot, showtext, sysfonts, readxl, withr, htmlwidgets, testthat (≥ 3.0.0), vdiffr |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.3 |
| Language: | en-US |
| LazyData: | true |
| Config/Needs/website: | rmarkdown |
| NeedsCompilation: | no |
| Packaged: | 2025-11-30 17:49:07 UTC; smaso |
| Author: | S. Mason Garrison 
[aut, cre, cph] |
| Maintainer: | S. Mason Garrison <garrissm@wfu.edu> |
| Repository: | CRAN |
ggpedigree: Visualizing Pedigrees with 'ggplot2' and 'plotly'
Description
Provides plotting functions for visualizing pedigrees in behavior genetics and kinship research. The package complements 'BGmisc' [Garrison et al. (2024) doi:10.21105/joss.06203] by rendering pedigrees using the 'ggplot2' framework and offers a modern alternative to the base-graphics pedigree plot in 'kinship2' [Sinnwell et al. (2014) doi:10.1159/000363105]. Features include support for duplicated individuals, complex mating structures, integration with simulated pedigrees, and layout customization.
Author(s)
Maintainer: S. Mason Garrison garrissm@wfu.edu (ORCID) [copyright holder]
See Also
Useful links:
Report bugs at https://github.com/R-Computing-Lab/ggpedigree/issues
Add annotates to ggplot Pedigree Plot
Description
Add annotates to ggplot Pedigree Plot
Usage
.addAnnotate(p, config, y_var_sym)
addAnnotate(p, config, y_var_sym)
Arguments
config |
A list of configuration overrides. Valid entries include:
|
Value
A ggplot object with added labels.
Add Labels to ggplot Pedigree Plot
Description
Add Labels to ggplot Pedigree Plot
Usage
.addLabels(plotObject, config)
addLabels(plotObject, config)
Arguments
plotObject |
A ggplot object. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
Value
A ggplot object with added labels.
Add Nodes to ggplot Pedigree Plot
Description
Add Nodes to ggplot Pedigree Plot
Usage
.addNodes(plotObject, config, focal_fill_column = NULL, status_column = NULL)
addNodes(plotObject, config, focal_fill_column = NULL, status_column = NULL)
Arguments
plotObject |
A ggplot object. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
focal_fill_column |
Character string specifying the column name for focal fill color. |
status_column |
Character string specifying the column name for affected status. Defaults to NULL. |
Add Overlay to ggplot Pedigree Plot
Description
Add Overlay to ggplot Pedigree Plot
Usage
.addOverlay(
plotObject,
config,
focal_fill_column = NULL,
status_column = NULL,
overlay_column = NULL
)
addOverlay(
plotObject,
config,
focal_fill_column = NULL,
status_column = NULL,
overlay_column = NULL
)
Arguments
plotObject |
A ggplot object. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
focal_fill_column |
Character string specifying the column name for focal fill color. |
status_column |
Character string specifying the column name for affected status. Defaults to NULL. |
overlay_column |
Character string specifying the column name for overlay alpha values. |
Value
A ggplot object with added overlay.
Add Scales to ggplot Pedigree Plot
Description
Add Scales to ggplot Pedigree Plot
Usage
.addScales(plotObject, config, status_column = NULL, focal_fill_column = NULL)
addScales(plotObject, config, status_column = NULL, focal_fill_column = NULL)
Arguments
plotObject |
A ggplot object. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
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. |
Value
A ggplot object with added scales.
Add Self Segments to ggplot Pedigree Plot
Description
Add Self Segments to ggplot Pedigree Plot
Usage
.addSelfSegment(plotObject, config, plot_connections)
addSelfSegment(plotObject, config, plot_connections)
Arguments
plotObject |
A ggplot object. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
Value
A ggplot object with added scales.
Adjust spacing in ggPedigree coordinate columns
Description
Uniformly expands or contracts the horizontal ('x_*') and vertical ('y_*') configuration settings for generation height and width.
Usage
.adjustSpacing(ds, config)
adjustSpacing(ds, config)
Arguments
ds |
A data frame containing the ggPedigree data. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
Value
A data frame with adjusted x and y positions.
Compute point along a curved segment (quadratic Bézier)
Description
Computes the x–y coordinates of a point along a curved segment connecting (x0, y0) to (x1, y1) using a quadratic Bézier construction. The control point is defined by an orthogonal offset from the straight-line midpoint, scaled by curvature * len and rotated by angle + shift (degrees). Vectorized over input coordinates and t.
Usage
.computeCurvedMidpoint(x0, y0, x1, y1, curvature, angle, shift = 0, t = 0.5)
computeCurvedMidpoint(x0, y0, x1, y1, curvature, angle, shift = 0, t = 0.5)
Arguments
x0 |
Numeric vector. X-coordinates of start points. |
y0 |
Numeric vector. Y-coordinates of start points. |
x1 |
Numeric vector. X-coordinates of end points. |
y1 |
Numeric vector. Y-coordinates of end points. |
curvature |
Curvature scale factor (as in *geom_curve*-style helpers): the control point is placed at a distance 'curvature * len' from the segment midpoint in the rotated-perpendicular direction. Changing the sign flips the bend to the opposite side (after rotation). |
angle |
Scalar numeric. Base rotation in degrees applied to the perpendicular before offsetting. |
shift |
Scalar numeric. Additional rotation in degrees (default 0). Effective rotation is angle + shift. |
t |
Numeric scalar or vector in [0, 1]. Bézier parameter where 0 is the start point, 1 is the end point; default 0.5. |
Details
* The unit perpendicular is constructed from the segment direction '(dx, dy)' as '(-uy, ux)' where '(ux, uy) = (dx, dy) / len'. * If an input pair yields 'len = 0' (identical endpoints), the unit direction is undefined and the resulting coordinates will be 'NA' due to division by zero; inputs should avoid zero-length segments. * Inputs of unequal length are recycled by base R. Prefer supplying conformable vectors to avoid unintended recycling.
Value
A data frame with columns x, y, and t representing the coordinates along the curved segment.
See Also
Related drawing helpers such as 'ggplot2::geom_curve()' for visual reference on curvature semantics.
Generate a symmetric key for two IDs
Description
This function generates a symmetric key for two IDs, ensuring that the order of the IDs does not matter.
Usage
.makeSymmetricKey(id1, id2, sep = ".")
makeSymmetricKey(id1, id2, sep = ".")
Arguments
id1 |
First ID |
id2 |
Second ID |
sep |
Separator to use between the IDs |
Value
A string representing the symmetric key
Prepare data for ggPhenotypeByDegree This function prepares the data frame for plotting by calculating necessary columns and ensuring required columns are present.
Description
Prepare data for ggPhenotypeByDegree This function prepares the data frame for plotting by calculating necessary columns and ensuring required columns are present.
Usage
.preparePhenotypeByDegreeData(
df,
y_var,
y_se = NULL,
y_stem_se = NULL,
y_ci_lb = NULL,
y_ci_ub = NULL,
config = list()
)
preparePhenotypeByDegreeData(
df,
y_var,
y_se = NULL,
y_stem_se = NULL,
y_ci_lb = NULL,
y_ci_ub = NULL,
config = list()
)
Arguments
df |
Data frame containing pairwise summary statistics. Required columns:
|
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:
|
Value
A modified data frame with additional columns for plotting.
Restore user-specified column names in a connections data frame
Description
Rename standard internal columns in a pedigree connections data frame back to user-specified names.
Usage
.restoreNames(
connections,
personID = "personID",
momID = "momID",
dadID = "dadID",
spouseID = "spouseID",
twinID = "twinID",
famID = "famID"
)
restoreNames(
connections,
personID = "personID",
momID = "momID",
dadID = "dadID",
spouseID = "spouseID",
twinID = "twinID",
famID = "famID"
)
Arguments
connections |
A data frame containing connection identifiers whose columns may currently be named with internal defaults such as 'personID', 'momID', 'dadID', 'spouseID', 'twinID', '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". |
twinID |
Character string specifying the column name for twin IDs. Defaults to "twinID". |
famID |
Character string specifying the column name for family IDs. Defaults to "famID". |
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)
Format
A data frame with 679 observations
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 -
twinID: ID of the twin, if applicable -
zygosity: Zygosity of the twin, if applicable. mz is monozygotic; dz is dizygotic
Add Focal Fill Column to Pedigree Data
Description
Adds a 'focal_fill' column to the pedigree data based on configuration input. Supports additive, mitochondrial, and line-based modes. If 'focal_fill_column' is specified, it takes priority over inferred modes.
Usage
addFocalFillColumn(
ds_ped,
config,
focal_fill_column = NULL,
famID = "famID",
matID = "matID",
patID = "patID",
personID = "personID",
fill_group_family = c("famID", "family", "family lineages", "family lines",
"family line"),
fill_group_maternal = c("maternal", "matID", "maternal line", "maternal lineages",
"maternal lines"),
fill_group_paternal = c("paternal", "patID", "paternal line", "paternal lineages",
"paternal lines")
)
Arguments
ds_ped |
A data frame already processed by 'transformPed()'. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
focal_fill_column |
Character string specifying the column name for focal fill color. |
famID |
Character string specifying the column name for family IDs. Defaults to "famID". |
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". |
personID |
Character string specifying the column name for individual IDs. Defaults to "personID". |
fill_group_family |
Character vector specifying fill types for family lineage. |
fill_group_maternal |
Character vector specifying fill types for maternal lineage. |
fill_group_paternal |
Character vector specifying fill types for paternal lineage. |
Value
A data frame with a 'focal_fill' column added if applicable.
Add Twins to ggplot Pedigree Plot
Description
Adds twin connections to the ggplot pedigree plot. This function modifies the 'plotObject' by adding segments to represent twin relationships.
Usage
addTwins(
plotObject,
connections,
config,
plot_connections,
personID = "personID"
)
Arguments
plotObject |
A ggplot object to which twin segments will be added. |
connections |
A data frame containing twin connection coordinates. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
plot_connections |
A data frame containing the coordinates for twin segments. |
personID |
Character string specifying the column name for individual IDs. Defaults to "personID". |
Value
A ggplot object with twin segments added.
Align pedigree with hints for plotting This function aligns a pedigree object using hints if provided, or defaults to the default alignment settings.
Description
Align pedigree with hints for plotting This function aligns a pedigree object using hints if provided, or defaults to the default alignment settings.
Usage
alignPedigreeWithHints(ped_ped, config)
Arguments
ped_ped |
A pedigree object created by 'pedigree()'. |
config |
A list of configuration options |
Value
A data frame with the aligned positions of individuals in the pedigree.
Align pedigree with additional relations
Description
This function aligns a pedigree object using relations if provided, or defaults to the default alignment settings.
Usage
alignPedigreeWithRelations(
ped,
personID,
dadID,
momID,
code_male,
sexVar,
config
)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID columns |
personID |
Character string specifying the column name for individual IDs. Defaults to "personID". |
dadID |
Character string specifying the column name for father IDs. Defaults to "dadID". |
momID |
Character string specifying the column name for mother IDs. Defaults to "momID". |
code_male |
Value used to indicate male sex. Defaults to NULL. |
sexVar |
Character. Name of the column in 'ped' for the sex variable. |
config |
List of configuration options:
|
Value
A data frame with the aligned positions of individuals in the pedigree.
build Config
Description
This function builds a configuration list for ggPedigree plots. It merges a default configuration with user-specified settings, ensuring all necessary parameters are set.
Usage
buildPlotConfig(default_config, config, function_name = "ggPedigree")
Arguments
default_config |
A list of default configuration parameters. |
config |
A list of user-specified configuration parameters. |
function_name |
The name of the function for which the configuration is being built. |
Value
A complete configuration list with all necessary parameters.
Build spouse segments
Description
Build spouse segments
Usage
buildSpouseSegments(ped, connections_for_FOO, use_hash = TRUE)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID columns |
connections_for_FOO |
A data frame containing the connections for the spouse segments from parent connections |
use_hash |
Logical. If TRUE, use the parent_hash to build segments. If FALSE, use the spouseID. |
Value
A data frame with the spouse segments
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"
)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID 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_midparent', 'y_midparent': midpoint between parents
'x_mid_sib', 'y_mid_sib': sibling group midpoint
'x_mid_spouse', 'y_mid_spouse': midpoint between spouses
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()
)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID 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:
|
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.
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)
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")
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"
)
Count siblings of each individual
Description
Count siblings of each individual
Usage
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")
Get fill column for ggPedigree
Description
This function creates a fill column for ggPedigree plots as a function of the focal person relative to everyone else in the tree.
Usage
createFillColumn(
ped,
focal_fill_personID = 2,
personID = "personID",
component = "additive",
config = list()
)
Arguments
ped |
A data frame containing the pedigree data. |
focal_fill_personID |
Numeric ID of the person to use as the focal point for fill. |
personID |
Character string specifying the column name for individual IDs. |
component |
Character string specifying the component type (e.g., "additive"). |
config |
A list of configuration options for customizing the fill column. |
Value
A data frame with two columns: 'fill' and 'personID'.
Format tooltip text
Description
Format tooltip text for ggplotly
Usage
formatTooltip(df, tooltip_columns, sep = ": ")
Arguments
df |
A data frame containing the data to be displayed in the tooltip. |
tooltip_columns |
A character vector of column names to be included in the tooltip. |
sep |
A character string containing the separator for the columns |
Value
A character vector of formatted tooltip text for each row in the data frame.
Generate a spouselist matrix
Description
Generate a spouselist matrix
Usage
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"
)
Shared Default Plotting Configuration
Description
Centralized configuration list used by all gg-based plotting functions. Returns a named list of default settings used by all gg-based plotting functions. This configuration can be overridden by supplying a list of key-value pairs to plotting functions such as 'ggPedigree()', 'ggRelatednessMatrix()', and 'ggPhenotypeByDegree()'. Each key corresponds to a configurable plot, layout, or aesthetic behavior.
Usage
getDefaultPlotConfig(
function_name = "getDefaultPlotConfig",
personID = "personID",
status_column = NULL,
alpha_default = 1,
apply_default_scales = TRUE,
apply_default_theme = TRUE,
segment_default_color = "black",
color_palette_default = c("#440154FF", "#FDE725FF", "#21908CFF"),
color_palette_low = "#000004FF",
color_palette_mid = "#56106EFF",
color_palette_high = "#FCFDBFFF",
color_scale_midpoint = 0.5,
color_scale_theme = "ggthemes::calc",
alpha = alpha_default,
plot_title = NULL,
plot_subtitle = NULL,
value_rounding_digits = 5,
code_male = 1,
code_na = NA,
code_female = 0,
label_include = TRUE,
label_column = "personID",
label_method = "geom_text",
label_max_overlaps = 25,
label_nudge_x = 0,
label_nudge_y = 0.15,
label_nudge_y_flip = TRUE,
label_segment_color = NA,
label_text_angle = 0,
label_text_size = 3,
label_text_color = "black",
label_text_family = "sans",
point_size = 4,
outline_include = FALSE,
outline_multiplier = 1.25,
outline_additional_size = 0,
outline_alpha = 1,
outline_color = "black",
tooltip_include = TRUE,
tooltip_columns = c("ID1", "ID2", "value"),
axis_x_label = NULL,
axis_y_label = NULL,
axis_text_angle_x = 90,
axis_text_angle_y = 0,
axis_text_size = 9,
axis_text_color = "black",
axis_text_family = "sans",
generation_height = 1,
generation_width = 1,
ped_packed = TRUE,
ped_align = TRUE,
ped_width = 15,
segment_linewidth = 0.5,
segment_linetype = 1,
segment_lineend = "round",
segment_linejoin = "round",
segment_offspring_color = segment_default_color,
segment_parent_color = segment_default_color,
segment_self_color = segment_default_color,
segment_sibling_color = segment_default_color,
segment_spouse_color = segment_default_color,
segment_mz_color = segment_default_color,
segment_mz_linetype = segment_linetype,
segment_mz_alpha = 1,
segment_mz_t = 0.6,
segment_self_linetype = "dotdash",
segment_self_linewidth = 0.5 * segment_linewidth,
segment_self_alpha = 0.5,
segment_self_angle = 90,
segment_self_curvature = -0.2,
sex_color_include = TRUE,
sex_legend_title = "Sex",
sex_shape_labels = c("Female", "Male", "Unknown"),
sex_color_palette = color_palette_default,
sex_shape_female = 16,
sex_shape_male = 15,
sex_shape_unknown = 18,
sex_shape_include = TRUE,
sex_legend_show = TRUE,
status_include = TRUE,
status_code_affected = 1,
status_code_unaffected = 0,
status_label_affected = "Affected",
status_label_unaffected = "Unaffected",
status_alpha_affected = 1,
status_alpha_unaffected = 0,
status_color_palette = c(color_palette_default[1], color_palette_default[2]),
status_color_affected = "black",
status_color_unaffected = color_palette_default[2],
status_shape_affected = 4,
status_legend_title = "Affected",
status_legend_show = FALSE,
overlay_shape = 4,
overlay_code_affected = 1,
overlay_code_unaffected = 0,
overlay_label_affected = "Affected",
overlay_label_unaffected = "Unaffected",
overlay_alpha_affected = 1,
overlay_alpha_unaffected = 0,
overlay_color = "black",
overlay_include = FALSE,
overlay_legend_title = "Overlay",
overlay_legend_show = FALSE,
focal_fill_include = FALSE,
focal_fill_legend_show = TRUE,
focal_fill_personID = 1,
focal_fill_legend_title = "Focal Fill",
focal_fill_high_color = "#FDE725FF",
focal_fill_mid_color = "#9F2A63FF",
focal_fill_low_color = "#0D082AFF",
focal_fill_scale_midpoint = color_scale_midpoint,
focal_fill_method = "gradient",
focal_fill_component = "additive",
focal_fill_n_breaks = NULL,
focal_fill_na_value = "black",
focal_fill_shape = 21,
focal_fill_force_zero = FALSE,
focal_fill_use_log = FALSE,
focal_fill_hue_range = c(0, 360),
focal_fill_chroma = 50,
focal_fill_lightness = 50,
focal_fill_hue_direction = "horizontal",
focal_fill_viridis_option = "D",
focal_fill_viridis_begin = 0,
focal_fill_viridis_end = 1,
focal_fill_viridis_direction = 1,
focal_fill_color_values = c("#052f60", "#e69f00", "#56b4e9", "#009e73", "#f0e442",
"#0072b2", "#d55e00", "#cc79a7"),
focal_fill_labels = c("Low", "Mid", "High"),
filter_n_pairs = 500,
filter_degree_min = 0,
filter_degree_max = 7,
drop_classic_kin = FALSE,
drop_non_classic_sibs = TRUE,
use_only_classic_kin = TRUE,
use_relative_degree = TRUE,
group_by_kin = TRUE,
match_threshold_percent = 10,
max_degree_levels = 12,
grouping_column = "mtdna_factor",
annotate_include = TRUE,
annotate_x_shift = -0.1,
annotate_y_shift = 0.005,
ci_include = TRUE,
ci_ribbon_alpha = 0.3,
tile_color_palette = c("white", "gold", "red"),
tile_interpolate = TRUE,
tile_color_border = NA,
tile_cluster = TRUE,
tile_geom = "geom_tile",
tile_na_rm = FALSE,
tile_linejoin = "mitre",
matrix_diagonal_include = TRUE,
matrix_upper_triangle_include = FALSE,
matrix_lower_triangle_include = TRUE,
matrix_sparse = FALSE,
matrix_isChild_method = "partialparent",
return_static = TRUE,
return_widget = FALSE,
return_interactive = FALSE,
return_midparent = FALSE,
hints = NULL,
relation = NULL,
debug = FALSE,
override_many2many = FALSE,
optimize_plotly = TRUE,
...
)
Arguments
function_name |
The name of the function calling this configuration. |
personID |
The column name for person identifiers in the data. |
status_column |
The column name for affected status in the data. |
alpha_default |
Default alpha transparency level. |
apply_default_scales |
Whether to apply default color scales. |
apply_default_theme |
Whether to apply default ggplot2 theme. |
segment_default_color |
A character string for the default color of segments in the plot. |
color_palette_default |
A character vector of default colors for the plot. |
color_palette_low |
Color for the low end of a gradient. |
color_palette_mid |
Color for the midpoint of a gradient. |
color_palette_high |
Color for the high end of a gradient. |
color_scale_midpoint |
Midpoint value for continuous color scales. |
color_scale_theme |
Name of the color scale used (e.g., "ggthemes::calc"). |
alpha |
Default alpha transparency for plot elements. |
plot_title |
Main title of the plot. |
plot_subtitle |
Subtitle of the plot. |
value_rounding_digits |
Number of digits to round displayed values. |
code_male |
Integer/string code for males in data. |
code_na |
optional Integer/string code for missing values in data. |
code_female |
optional Integer/string code for females in data. |
label_include |
Whether to display labels on plot points. |
label_column |
Column to use for text labels. |
label_method |
Method used for labeling (e.g., ggrepel, geom_text). |
label_max_overlaps |
Maximum number of overlapping labels. |
label_nudge_x |
Horizontal nudge for label text. |
label_nudge_y |
Vertical nudge for label text. |
label_nudge_y_flip |
TRUE. Whether to flip the nudge y value to be negative. The plot is reversed vertically, so this is needed to nudge labels up instead of down. |
label_segment_color |
Segment color for label connectors. |
label_text_angle |
Text angle for labels. |
label_text_size |
Font size for labels. |
label_text_color |
Color of the label text. |
label_text_family |
Font family for label text. |
point_size |
Size of points drawn in plot. |
outline_include |
Whether to include outlines around points. |
outline_multiplier |
Multiplier to compute outline size from point size. |
outline_additional_size |
Additional size added to outlines. |
outline_alpha |
Alpha transparency for point outlines. |
outline_color |
Color used for point outlines. |
tooltip_include |
Whether tooltips are shown in interactive plots. |
tooltip_columns |
Columns to include in tooltips. |
axis_x_label |
Label for the X-axis. |
axis_y_label |
Label for the Y-axis. |
axis_text_angle_x |
Angle of X-axis text. |
axis_text_angle_y |
Angle of Y-axis text. |
axis_text_size |
Font size of axis text. |
axis_text_color |
Color of axis text. |
axis_text_family |
Font family for axis text. |
generation_height |
Vertical spacing of generations. |
generation_width |
Horizontal spacing of generations. |
ped_packed |
Whether the pedigree should use packed layout. |
ped_align |
Whether to align pedigree generations. |
ped_width |
Plot width of the pedigree block. |
segment_linewidth |
Line width for segments. |
segment_linetype |
Line type for segments. |
segment_lineend |
Line end type for segments. |
segment_linejoin |
Line join type for segments. |
segment_offspring_color |
Color for offspring segments. |
segment_parent_color |
Color for parent segments. |
segment_self_color |
Color for self-loop segments. |
segment_sibling_color |
Color for sibling segments. |
segment_spouse_color |
Color for spouse segments. |
segment_mz_color |
Color for monozygotic twin segments. |
segment_mz_linetype |
Line type for MZ segments. |
segment_mz_alpha |
Alpha for MZ segments. |
segment_mz_t |
Tuning parameter for MZ segment layout. |
segment_self_linetype |
Line type for self-loop segments. |
segment_self_linewidth |
Width of self-loop segment lines. |
segment_self_alpha |
Alpha value for self-loop segments. |
segment_self_angle |
Angle of self-loop segment. |
segment_self_curvature |
Curvature of self-loop segment. |
sex_color_include |
Whether to color nodes by sex. |
sex_legend_title |
Title of the sex legend. |
sex_shape_labels |
Labels used in sex legend. |
sex_color_palette |
A character vector of colors for sex. |
sex_shape_female |
Shape for female nodes. |
sex_shape_male |
Shape for male nodes. |
sex_shape_unknown |
Shape for unknown sex nodes. |
sex_shape_include |
Whether to display the shape for sex variables |
sex_legend_show |
Whether to display sex in the legend |
status_include |
Whether to display affected status. |
status_code_affected |
Value that encodes affected status. |
status_code_unaffected |
Value that encodes unaffected status. |
status_label_affected |
Label for affected status. |
status_label_unaffected |
Label for unaffected status. |
status_alpha_affected |
Alpha for affected individuals. |
status_alpha_unaffected |
Alpha for unaffected individuals. Default is 0 (transparent). |
status_color_palette |
A character vector of colors for affected status. |
status_color_affected |
Color for affected individuals. |
status_color_unaffected |
Color for unaffected individuals. |
status_shape_affected |
Shape for affected individuals. |
status_legend_title |
Title of the status legend. |
status_legend_show |
Whether to show the status legend. |
overlay_shape |
Shape used for overlaying points in the plot. Default is 4 (cross). |
overlay_code_affected |
Code for affected individuals in overlay. Default is 1. |
overlay_code_unaffected |
Code for unaffected individuals in overlay. Default is 0. |
overlay_label_affected |
Label for affected individuals in overlay. Default is "Affected". |
overlay_label_unaffected |
Label for unaffected individuals in overlay. Default is "Unaffected". |
overlay_alpha_affected |
Alpha for affected individuals in overlay. Default is 1. |
overlay_alpha_unaffected |
Alpha for unaffected individuals in overlay. Default is 0. |
overlay_color |
Color for overlay points. Default is "black". |
overlay_include |
Whether to include overlay points in the plot. Default is FALSE. |
overlay_legend_title |
Title of the overlay legend. Default is "Overlay". |
overlay_legend_show |
Whether to show the overlay legend. Default is FALSE. |
focal_fill_include |
Whether to fill focal individuals. |
focal_fill_legend_show |
Whether to show legend for focal fill. |
focal_fill_personID |
ID of focal individual. |
focal_fill_legend_title |
Title of focal fill legend. |
focal_fill_high_color |
High-end color for focal gradient. |
focal_fill_mid_color |
Midpoint color for focal gradient. |
focal_fill_low_color |
Low-end color for focal gradient. |
focal_fill_scale_midpoint |
Midpoint for focal fill scale. |
focal_fill_method |
Method used for focal fill gradient. Options are 'steps', 'steps2', 'step', 'step2', 'viridis_c', 'viridis_d', 'viridis_b', 'manual', 'hue', 'gradient2', 'gradient'. |
focal_fill_component |
Component type for focal fill. |
focal_fill_n_breaks |
Number of breaks in focal fill scale. |
focal_fill_na_value |
Color for NA values in focal fill. |
focal_fill_shape |
Shape used for focal fill points. |
focal_fill_force_zero |
Whether to force zero to NA in focal fill. |
focal_fill_use_log |
Whether to use log scale for focal fill. |
focal_fill_hue_range |
Hue range for focal fill colors. |
focal_fill_chroma |
Chroma value for focal fill colors. |
focal_fill_lightness |
Lightness value for focal fill colors. |
focal_fill_hue_direction |
Direction of focal fill gradient. |
focal_fill_viridis_option |
Option for viridis color scale. |
focal_fill_viridis_begin |
Start of viridis color scale. |
focal_fill_viridis_end |
End of viridis color scale. |
focal_fill_viridis_direction |
Direction of viridis color scale (1 for left to right, -1 for right to left). |
focal_fill_color_values |
A character vector of colors for focal fill. |
focal_fill_labels |
Labels for focal fill colors. |
filter_n_pairs |
Threshold to filter maximum number of pairs. |
filter_degree_min |
Minimum degree value used in filtering. |
filter_degree_max |
Maximum degree value used in filtering. |
drop_classic_kin |
Whether to exclude classic kin categories. |
drop_non_classic_sibs |
Whether to exclude non-classic sibs. |
use_only_classic_kin |
Whether to restrict analysis to classic kinship. |
use_relative_degree |
Whether to use relative degrees instead of absolute. |
group_by_kin |
Whether to group output by kinship group. |
match_threshold_percent |
Kinbin matching threshold as a percentage. |
max_degree_levels |
Maximum number of degree levels to show. |
grouping_column |
Name of column used for grouping. |
annotate_include |
Whether to include annotations. |
annotate_x_shift |
Horizontal shift applied to annotation text. |
annotate_y_shift |
Vertical shift applied to annotation text. |
ci_include |
Whether to show confidence intervals. |
ci_ribbon_alpha |
Alpha level for CI ribbons. |
tile_color_palette |
Color palette for matrix plots. |
tile_interpolate |
Whether to interpolate colors in matrix tiles. |
tile_color_border |
Color border for matrix tiles. |
tile_cluster |
Whether to sort by clusters the matrix. |
tile_geom |
Geometry type for matrix tiles (e.g., "geom_tile", "geom_raster"). |
tile_na_rm |
Whether to remove NA values in matrix tiles. |
tile_linejoin |
Line join type for matrix tiles. |
matrix_diagonal_include |
Whether to include diagonal in matrix plots. |
matrix_upper_triangle_include |
Whether to include upper triangle in matrix plots. |
matrix_lower_triangle_include |
Whether to include lower triangle in matrix plots. |
matrix_sparse |
Whether matrix input is sparse. |
matrix_isChild_method |
Method used for isChild matrix derivation. |
return_static |
Whether to return a static plot. |
return_widget |
Whether to return a widget object. |
return_interactive |
Whether to return an interactive plot. |
return_midparent |
Whether to return midparent values in the plot. |
hints |
Optional hints to pass along to kinship2::autohint |
relation |
Optional relation to pass along to kinship2::pedigree |
debug |
Whether to enable debugging mode. |
override_many2many |
Whether to override many-to-many link logic. |
optimize_plotly |
Whether to optimize the plotly output for speed. |
... |
Additional arguments for future extensibility. |
Value
A named list of default plotting and layout parameters.
Compute midpoints across grouped coordinates
Description
A flexible utility function to compute x and y midpoints for groups of individuals using a specified method. Used to support positioning logic for sibling groups, parental dyads, or spousal pairs in pedigree layouts.
Usage
getMidpoints(
data,
group_vars,
x_vars,
y_vars,
x_out,
y_out,
method = "mean",
require_non_missing = group_vars
)
Arguments
data |
A 'data.frame' containing the coordinate and grouping variables. |
group_vars |
Character vector. Names of the grouping variables. |
x_vars |
Character vector. Names of the x-coordinate variables to be averaged. |
y_vars |
Character vector. Names of the y-coordinate variables to be averaged. |
x_out |
Character. Name of the output column for the x-coordinate midpoint. |
y_out |
Character. Name of the output column for the y-coordinate midpoint. |
method |
Character. Method for calculating midpoints. Options include:
|
require_non_missing |
Character vector. Names of variables that must not be missing for the row to be included. |
Value
A 'data.frame' grouped by 'group_vars' with new columns 'x_out' and 'y_out' containing midpoint coordinates.
Get coordinate positions of relatives for each individual
Description
Helper function used to retrieve the x and y coordinates of a specified relative (e.g., mom, dad, spouse) and join them into the main connection table. This supports relative-specific positioning in downstream layout functions like 'calculateConnections()'.
Usage
getRelativeCoordinates(
ped,
connections,
relativeIDvar,
x_name,
y_name,
personID = "personID",
multiple = "all",
only_unique = TRUE
)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID columns |
connections |
A 'data.frame' containing the individuals and their associated relative IDs. |
relativeIDvar |
Character. Name of the column in 'connections' for the relative ID variable. |
x_name |
Character. Name of the new column to store the x-coordinate of the relative. |
y_name |
Character. Name of the new column to store the y-coordinate of the relative. |
personID |
Character string specifying the column name for individual IDs. Defaults to "personID". |
multiple |
Character. Specifies how to handle multiple matches. Options are "all" or "any". |
only_unique |
Logical. If TRUE, return only unique rows. Defaults to TRUE. |
Value
A 'data.frame' with columns:
'personID', 'relativeIDvar'
'x_name', 'y_name': Coordinates of the specified relative
Optionally, 'newID' if present in 'ped'
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,
return_widget = FALSE,
config = list(),
debug = FALSE,
hints = NULL,
interactive = FALSE,
phantoms = FALSE,
...
)
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,
return_widget = FALSE,
config = list(),
debug = FALSE,
hints = NULL,
interactive = FALSE,
phantoms = FALSE,
...
)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID 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. |
tooltip_columns |
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. |
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. The list can include:
|
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. |
phantoms |
Logical. If TRUE, adds phantom parents for individuals without parents. |
... |
Additional arguments passed to 'ggplot2' functions. |
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))
Core Function for ggPedigree
Description
This function is the core implementation of the ggPedigree function. It handles the data preparation, layout calculation, and plotting of the pedigree diagram. It is not intended to be called directly by users.
Usage
ggPedigree.core(
ped,
famID = "famID",
personID = "personID",
momID = "momID",
dadID = "dadID",
spouseID = "spouseID",
matID = "matID",
patID = "patID",
twinID = "twinID",
focal_fill_column = NULL,
overlay_column = NULL,
status_column = NULL,
config = list(),
debug = FALSE,
hints = NULL,
function_name = "ggPedigree",
phantoms = FALSE,
...
)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID 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". |
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. |
status_column |
Character string specifying the column name for affected status. Defaults to NULL. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
debug |
Logical. If TRUE, prints debugging information. Default: FALSE. |
hints |
Data frame with hints for layout adjustments. Default: NULL. |
phantoms |
Logical. If TRUE, adds phantom parents for individuals without parents. |
... |
Additional arguments passed to 'ggplot2' functions. |
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",
patID = "patID",
matID = "matID",
twinID = "twinID",
status_column = NULL,
tooltip_columns = NULL,
focal_fill_column = NULL,
overlay_column = NULL,
config = list(optimize_plotly = TRUE),
debug = FALSE,
return_widget = TRUE,
phantoms = FALSE,
...
)
ggpedigreeInteractive(
ped,
famID = "famID",
personID = "personID",
momID = "momID",
dadID = "dadID",
patID = "patID",
matID = "matID",
twinID = "twinID",
status_column = NULL,
tooltip_columns = NULL,
focal_fill_column = NULL,
overlay_column = NULL,
config = list(optimize_plotly = TRUE),
debug = FALSE,
return_widget = TRUE,
phantoms = FALSE,
...
)
ggpedigreeinteractive(
ped,
famID = "famID",
personID = "personID",
momID = "momID",
dadID = "dadID",
patID = "patID",
matID = "matID",
twinID = "twinID",
status_column = NULL,
tooltip_columns = NULL,
focal_fill_column = NULL,
overlay_column = NULL,
config = list(optimize_plotly = TRUE),
debug = FALSE,
return_widget = TRUE,
phantoms = FALSE,
...
)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID 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". |
patID |
Character string specifying the column name for paternal lines Defaults to "patID". |
matID |
Character string specifying the column name for maternal lines Defaults to "matID". |
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. |
tooltip_columns |
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. |
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. |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
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). |
phantoms |
Logical. If TRUE, adds phantom parents for individuals without parents. |
... |
Additional arguments passed to 'ggplot2' functions. |
Value
A plotly htmlwidget (or plotly object if 'return_widget = FALSE')
Examples
library(BGmisc)
data("potter")
ggPedigreeInteractive(potter, famID = "famID", personID = "personID")
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,
...
)
Arguments
df |
Data frame containing pairwise summary statistics. Required columns:
|
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:
|
data_prep |
Logical; if TRUE, performs data preparation steps. |
... |
Additional arguments passed to 'ggplot2' functions. |
Value
A ggplot object containing the correlation plot.
Core plotting function for ggPhenotypeByDegree This function generates the core ggplot object based on the prepared data frame.
Description
Core plotting function for ggPhenotypeByDegree This function generates the core ggplot object based on the prepared data frame.
Usage
ggPhenotypeByDegree.core(
df,
y_var,
y_se,
y_stem_se,
y_ci_lb = NULL,
y_ci_ub = NULL,
config,
...
)
Arguments
df |
Data frame containing pairwise summary statistics. Required columns:
|
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:
|
... |
Additional arguments passed to 'ggplot2' functions. |
Value
A ggplot object containing the correlation plot.
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. |
tooltip_columns |
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:
- matrix_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
- matrix_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(
matrix_color_palette = c("white", "gold", "red"),
color_scale_midpoint = 0.5,
matrix_cluster = TRUE,
plot_title = "Relatedness Matrix",
axis_x_label = "Individuals",
axis_y_label = "Individuals",
axis_text_size = 8
)
)
Core Function for ggRelatednessMatrix
Description
This function is the core implementation of the ggRelatednessMatrix function. It handles the data preparation, layout calculation, and plotting of the pedigree diagram. It is not intended to be called directly by users.
Usage
ggRelatednessMatrix.core(mat, config = list(), ...)
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. |
... |
Additional arguments passed to ggplot2 layers. |
Align a pedigree for plotting
Description
This is the main function for aligning a pedigree structure for plotting. It arranges subjects by generation, positions them horizontally to minimize line crossings, handles spouse relationships, and produces the coordinate system needed for drawing the pedigree.
Usage
kinship2_align.pedigree(
ped,
packed = TRUE,
width = 10,
align = TRUE,
hints = ped$hints
)
Arguments
ped |
A pedigree object or pedigreeList object |
packed |
Logical, if TRUE uses compact packing algorithm (default TRUE) |
width |
Numeric, maximum width of the pedigree plot (default 10) |
align |
Logical or numeric. If TRUE, attempts to align spouses on same level. If numeric, a vector c(a1, a2) controlling alignment penalties (default TRUE) |
hints |
Optional list with 'order' and 'spouse' components to guide alignment. If NULL, kinship2_autohint is called to generate hints |
Details
This function handles the complete pedigree alignment process:
Determines generation levels using kinship2_kindepth
Generates or validates alignment hints using kinship2_autohint or kinship2_check.hint
Builds spouse relationships list
Processes founders and their descendants using kinship2_alignped1, kinship2_alignped2, kinship2_alignped3
Optimizes horizontal spacing using kinship2_alignped4
Identifies inbreeding loops and twin relationships
Value
For a single pedigree, a list containing:
n |
Vector of counts per generation level |
nid |
Matrix of subject IDs at each position |
pos |
Matrix of horizontal positions |
fam |
Matrix of family indices indicating parent connections |
spouse |
Matrix indicating spouse connections |
twins |
Optional matrix indicating twin relationships |
For a pedigreeList, returns the input with alignment information added.
Align pedigree - Process a single subject and their spouses
Description
This is an internal helper function for pedigree alignment. It processes a single subject (founder or not) along with their spouse(s), building up the alignment structure. This function is called recursively by kinship2_align.pedigree to construct the entire pedigree layout.
Usage
kinship2_alignped1(x, dad, mom, level, horder, packed, spouselist)
Arguments
x |
Integer vector of subject ID(s) to process |
dad |
Integer vector of father indices |
mom |
Integer vector of mother indices |
level |
Integer vector indicating the generation level of each subject |
horder |
Numeric vector of hint order for positioning subjects |
packed |
Logical, if TRUE uses compact packing algorithm |
spouselist |
Matrix defining spouse relationships |
Value
A list containing:
nid |
Matrix of subject IDs at each level and position |
pos |
Matrix of horizontal positions |
fam |
Matrix of family indices |
n |
Vector of counts per level |
spouselist |
Updated spouse list |
Align pedigree - Process a set of siblings
Description
This is an internal helper function for pedigree alignment. It processes a set of siblings, ordering them according to hints and calling kinship2_alignped1 for each sibling. The results are merged together using kinship2_alignped3.
Usage
kinship2_alignped2(x, dad, mom, level, horder, packed, spouselist)
Arguments
x |
Integer vector of sibling IDs to process |
dad |
Integer vector of father indices |
mom |
Integer vector of mother indices |
level |
Integer vector indicating the generation level of each subject |
horder |
Numeric vector of hint order for positioning subjects |
packed |
Logical, if TRUE uses compact packing algorithm |
spouselist |
Matrix defining spouse relationships |
Value
A list containing the aligned pedigree structure for the sibling group:
nid |
Matrix of subject IDs at each level and position |
pos |
Matrix of horizontal positions |
fam |
Matrix of family indices |
n |
Vector of counts per level |
spouselist |
Updated spouse list |
Merge two aligned pedigree structures
Description
This is an internal helper function for pedigree alignment. It takes two previously aligned pedigree structures (x1 and x2) and merges them side-by-side, handling overlapping subjects and adjusting positions appropriately.
Usage
kinship2_alignped3(x1, x2, packed, space = 1)
Arguments
x1 |
First aligned pedigree structure (list) |
x2 |
Second aligned pedigree structure (list) |
packed |
Logical, if TRUE uses compact packing; if FALSE adds spacing |
space |
Numeric, horizontal spacing between structures when packed=FALSE (default 1) |
Value
A list containing the merged pedigree structure:
n |
Vector of counts per level |
nid |
Matrix of subject IDs at each level and position |
pos |
Matrix of horizontal positions |
fam |
Matrix of family indices |
Compute optimal horizontal spacing for pedigree alignment
Description
This is an internal helper function for pedigree alignment. It uses quadratic programming to find optimal horizontal positions for subjects that minimize the distance between parents and children while keeping spouses together and respecting spacing constraints. Requires the quadprog package.
Usage
kinship2_alignped4(rval, spouse, level, width, align)
Arguments
rval |
Aligned pedigree structure from previous alignment steps |
spouse |
Logical matrix indicating spouse connections |
level |
Integer vector of generation levels |
width |
Numeric, maximum width of the pedigree plot |
align |
Logical or numeric vector. If logical, uses default alignment parameters. If numeric, should be a vector c(a1, a2) where a1 controls parent-child penalties and a2 controls spouse penalties |
Value
Matrix of optimized horizontal positions for each subject
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.
Usage
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 |
Calculate the bit size of a pedigree
Description
This function calculates the bit size of a pedigree, which is a measure of the information content. The bit size is calculated as 2 * (number of non-founders) - (number of founders). This is used in pedigree.shrink functions.
Usage
kinship2_bitSize(ped)
Arguments
ped |
A pedigree object |
Value
A list containing:
bitSize |
The bit size of the pedigree |
nFounder |
The number of founders in the pedigree |
nNonFounder |
The number of non-founders in the pedigree |
Examples
## Not run:
# Example requires a pedigree object
# ped <- pedigree(id=1:5, dadid=c(0,0,1,1,1), momid=c(0,0,2,2,2),
# sex=c(1,2,1,2,1))
# kinship2_bitSize(ped)
## End(Not run)
Check kinship2 hints for consistency
Description
This function checks the consistency of kinship2 hints, particularly focusing on the 'order' and 'spouse' components. It ensures that the order is numeric and matches the length of the 'sex' vector, and that marriages are valid male/female pairs without duplicates.
Usage
kinship2_check.hint(hints, sex)
Arguments
hints |
A list containing kinship2 hints, including 'order' and optionally 'spouse'. |
sex |
A character vector indicating the sex of each individual ('male' or 'female'). |
Details
Extracted from checks.Rnw This routine tries to remove inconsistencies in spousal hints. These and arise in autohint with complex pedigrees. One can have ABA (subject A is on both the left and the right of B), cycles, etc. Actually, these used to arise in autohint, I don't know if it's so after the recent rewrite. Users can introduce problems as well if they modify the hints.
Value
The original 'hints' list if all checks pass; otherwise, an error is raised.
Find all duplicated IDs on a level, and return
Description
Find all duplicated IDs on a level, and return
Usage
kinship2_duporder(idlist, plist, lev, ped)
Value
A matrix with one row per duplicated ID, columns 1 and 2
Calculate the depth (generation level) of subjects in a pedigree
Description
This function computes the depth of each subject in a pedigree, defined as the maximal number of generations of ancestors (distance to the farthest founder). Optionally aligns spouses to plot on the same generation level.
Usage
kinship2_kindepth(id, dad.id, mom.id, align = FALSE)
Arguments
id |
Either a pedigree/pedigreeList object, or a vector of subject IDs |
dad.id |
Vector of father IDs (required if 'id' is not a pedigree object) |
mom.id |
Vector of mother IDs (required if 'id' is not a pedigree object) |
align |
Logical, if TRUE attempts to align married couples at the same depth level for better visualization (default FALSE) |
Details
When 'align=TRUE', the function adjusts depths so that married couples appear on the same generation level when possible. This produces more aesthetically pleasing pedigree plots. The alignment algorithm handles marry-ins, multiple marriages, and inbreeding loops.
Value
Integer vector of depth values for each subject, where 0 = founder, 1 = child of founder, etc.
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"))
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 @aliases optimisePedigree |
Optimize Plotly Pedigree Plot
Description
Optimize a Plotly pedigree plot by rounding coordinates to reduce file size.
Usage
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.
Optimize Static Pedigree Plot
Description
Optimize a static pedigree plot by rounding coordinates to reduce file size and removing unnecessary variables from the data frame.
Usage
optimizeStaticPedigree(
p,
config = list(),
variable_drop = c("parent_hash", "couple_hash", "gen", "spousehint", "parent_fam",
"nid", "x_order", "y_order", "y_fam", "zygosity", "extra", "x_fam")
)
Arguments
p |
A ggplot object representing the pedigree plot. |
config |
A list of configuration parameters, including 'value_rounding_digits'. |
variable_drop |
A character vector of variable names to be removed from the data frame. Default variables to drop include "parent_hash", "couple_hash", "gen", "spousehint", "parent_fam", "nid", "x_order", "y_order", "y_fam", "zygosity", "extra", and "x_fam". |
Value
The optimized ggplot object with rounded coordinates and reduced data frame.
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, ...)
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
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
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,
...
)
Arguments
ped |
The simulated pedigree data.frame from function |
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 |
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 |
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 |
Value
A plot of the provided pedigree
Prepare Pedigree Data
Description
This function checks and prepares the pedigree data frame for use in ggPedigree.
Usage
preparePedigreeData(
ped,
famID = "famID",
personID = "personID",
momID = "momID",
dadID = "dadID",
matID = "matID",
patID = "patID",
config = list(focal_fill_include = TRUE, focal_fill_component = "maternal"),
fill_group_paternal = c("paternal", "patID", "paternal line", "paternal lineages",
"paternal lines"),
fill_group_maternal = c("maternal", "matID", "maternal line", "maternal lineages",
"maternal lines"),
fill_group_family = c("family", "famID", "family line", "family lineages",
"family lines"),
status_column = NULL,
phantoms = FALSE,
focal_fill_column = NULL
)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID 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". |
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". |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
fill_group_paternal |
A character vector specifying which paternal components to fill. |
fill_group_maternal |
A character vector specifying which maternal components to fill. |
fill_group_family |
A character vector specifying the family fill group names. |
status_column |
Character string specifying the column name for affected status. Defaults to NULL. |
phantoms |
Logical. If TRUE, adds phantom parents for individuals without parents. |
focal_fill_column |
Character string specifying the column name for focal fill color. |
Value
A data frame with the prepared pedigree data.
Process duplicate appearances of individuals in a pedigree layout
Description
Resolves layout conflicts when the same individual appears in multiple places (e.g., due to inbreeding loops). Keeps the layout point that is closest to a relevant relative (mom, dad, or spouse) and removes links to others to avoid confusion in visualization.
Usage
processExtras(ped, config = list())
Arguments
ped |
A data.frame containing pedigree layout info with columns including: 'personID', 'x_pos', 'y_pos', 'dadID', 'momID', and a logical column 'extra'. |
config |
A list of configuration options. Currently unused but passed through to internal helpers. |
Value
A modified 'ped' data.frame with updated coordinates and removed duplicates.
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). 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:
Usage
data(redsquirrels)
Format
## 'redsquirrels' 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
...
Details
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>
Process Pedigree Data
Description
This function processes the pedigree data frame to ensure it is in the correct format for ggPedigree. It checks for the presence of family, paternal, and maternal IDs, and fills in missing components based on the configuration.
Usage
transformPed(
ped,
famID = "famID",
personID = "personID",
momID = "momID",
dadID = "dadID",
matID = "matID",
patID = "patID",
config = list(focal_fill_include = TRUE, focal_fill_component = "maternal"),
fill_group_paternal = c("paternal", "patID", "paternal line", "paternal lineages",
"paternal lines"),
fill_group_maternal = c("maternal", "matID", "maternal line", "maternal lineages",
"maternal lines")
)
Arguments
ped |
A data frame containing the pedigree data. Needs personID, momID, and dadID 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". |
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". |
config |
A list of configuration options for customizing the plot. See getDefaultPlotConfig for details. The list can include:
|
fill_group_paternal |
A character vector specifying which paternal components to fill. |
fill_group_maternal |
A character vector specifying which maternal components to fill. |
Value
A data frame with the processed pedigree data.