Package 'BGmisc'

Description

Construct Adjacency Matrix for Parent-Child Relationships Using Beta Methods This function constructs an adjacency matrix for parent-child relationships using a method in beta testing. It identifies parent-child pairs based on the specified component of relatedness.

Usage

.adjBeta(
  ped,
  component,
  adjBeta_method = 5,
  parList = NULL,
  lastComputed = 0,
  lens = NULL,
  saveable = FALSE,
  resume = FALSE,
  save_path = NULL,
  verbose = FALSE,
  save_rate_parlist = NULL,
  update_rate = NULL,
  checkpoint_files = NULL,
  config,
  compress = config$compress,
  ...
)

Arguments

Description

This function constructs an adjacency matrix for parent-child relationships using a direct method. It identifies parent-child pairs based on the specified component of relatedness.

Usage

.adjDirect(
  ped,
  component,
  saveable,
  resume,
  save_path,
  verbose,
  lastComputed,
  checkpoint_files,
  update_rate,
  parList,
  lens,
  save_rate_parlist,
  config,
  compress = config$compress,
  ...
)

Arguments

Description

Construct Adjacency Matrix for Parent-Child Relationships Using Indexed Method

Usage

.adjIndexed(
  ped,
  component,
  saveable,
  resume,
  save_path,
  verbose,
  lastComputed,
  checkpoint_files,
  update_rate,
  parList,
  lens,
  save_rate_parlist,
  config,
  compress = config$compress
)

Arguments

Description

Assign parent values based on component type

Usage

.assignParentValue(component)

Arguments

Description

Compute the transpose multiplication for the relatedness matrix

Usage

.computeTranspose(
  r2,
  transpose_method = "tcrossprod",
  chunk_size = 1000L,
  verbose = FALSE,
  force_symmetric = FALSE,
  config = NULL,
  checkpoint_files = NULL
)

Arguments

Details

The algorithms and methodologies used in this function are further discussed and exemplified in the vignette titled "examplePedigreeFunctions". For more advanced scenarios and detailed explanations, consult this vignette.

Description

Load or compute the isChild matrix

Usage

.loadOrComputeIsChild(ped, checkpoint_files, config, compress = TRUE)

Arguments

Description

Post-process GEDCOM Data Frame

Usage

.postProcessGedcom.legacy(
  df_temp,
  remove_empty_cols = TRUE,
  combine_cols = TRUE,
  add_parents = TRUE,
  skinny = TRUE,
  verbose = FALSE
)

Arguments

Value

A data frame with processed information.

Description

Create a properly formatted parent row for the pedigree

Usage

addParentRow(template_row, newID, sex, momID = NA, dadID = NA, famID = NA)

Arguments

Value

A single-row dataframe for the new parent

Description

A function to add a new person to an existing pedigree data.frame.

Usage

addPersonToPed(
  ped,
  name = NULL,
  sex = NULL,
  momID = NA,
  dadID = NA,
  twinID = NULL,
  personID = NULL,
  zygosity = NULL,
  notes = NULL,
  url = NULL,
  overwrite = FALSE
)

Arguments

Value

A data.frame with the new person added to the existing pedigree.

Description

This function adds parents who appear in momID or dadID but are missing from ID

Usage

addRowlessParents(ped, verbose, validation_results)

Arguments

Description

This function takes a pedigree data frame, a specified phenotype column, and a vector of IDs to keep, and returns a matrix formatted for use in OpenMx models. The resulting matrix has one row and columns corresponding to the specified IDs, with values taken from the phenotype column of the pedigree.

Usage

alignPhenToMatrix(ped, phenotype, keep_ids, personID = "ID")

Arguments

Description

Iterates over a list of tag mappings and, if a tag matches the line, updates the record. Stops after the first match.

Usage

applyTagMappings(line, record, pattern_rows, tag_mappings)

Arguments

Value

A list with the updated record (record) and a logical flag (matched).

Description

This function processes connections between each two generations in a pedigree simulation. It marks individuals as parents, sons, or daughters based on their generational position and relationships. The function also handles the assignment of couple IDs, manages single and coupled individuals, and establishes parent-offspring links across generations.

Usage

buildBtwnGenerations(
  df_Fam,
  Ngen,
  sizeGens,
  verbose = FALSE,
  marR,
  sexR,
  kpc,
  rd_kpc,
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  code_male = "M",
  code_female = "F",
  beta = FALSE
)

Arguments

Details

The function iterates through each generation, starting from the second, to establish connections based on mating and parentage. For the first generation, it sets the parental status directly. For subsequent generations, it calculates the number of couples, the expected number of offspring, and assigns offspring to parents. It handles gender-based assignments for sons and daughters, and deals with the nuances of single individuals and couple formation. The function relies on external functions 'assignCoupleIds' and 'adjustKidsPerCouple' to handle specific tasks related to couple ID assignment and offspring number adjustments, respectively.

Value

The function updates the 'df_Fam' data frame in place, adding or modifying columns related to parental and offspring status, as well as assigning unique couple IDs. It does not return a value explicitly.

Description

This function constructs OpenMx models for multiple family groups based on provided relatedness matrices and observed data.

Usage

buildFamilyGroups(
  dat,
  obs_ids,
  Addmat = NULL,
  Nucmat = NULL,
  Extmat = NULL,
  Mtdmat = NULL,
  Amimat = NULL,
  Dmgmat = NULL,
  prefix = "fam",
  condenseMatrixSlots = TRUE
)

Arguments

Value

A list of OpenMx models for each family group.

Description

This function constructs an OpenMx model for a single family group based on provided relatedness matrices and observed data. The implied covariance is built as a weighted sum of the supplied relatedness matrices, where the weights are variance component parameters shared across groups via a parent ModelOne sub-model.

Usage

buildOneFamilyGroup(
  group_name,
  Addmat = NULL,
  Nucmat = NULL,
  Extmat = NULL,
  Mtdmat = NULL,
  Amimat = NULL,
  Dmgmat = NULL,
  full_df_row,
  obs_ids,
  condenseMatrixSlots = TRUE
)

Arguments

Value

An OpenMx model for the specified family group.

Description

This function builds an OpenMx model for a pedigree with specified variance components. It requires the OpenMx package.

Usage

buildPedigreeModelCovariance(
  vars = list(ad2 = 0.5, dd2 = 0.3, cn2 = 0.2, ce2 = 0.4, mt2 = 0.1, am2 = 0.25, ee2 =
    0.6),
  Vad = TRUE,
  Vdd = FALSE,
  Vcn = TRUE,
  Vce = TRUE,
  Vmt = TRUE,
  Vam = FALSE,
  Ver = TRUE,
  lbound = 1e-10
)

Arguments

Value

An OpenMx model representing the pedigree with specified variance components.

Description

This function constructs an OpenMx pedigree model by combining variance component parameters and family group models. It auto-detects which variance components are referenced in the group algebras and creates only those parameters.

Usage

buildPedigreeMx(
  model_name,
  vars,
  group_models,
  ci = FALSE,
  condenseMatrixSlots = TRUE
)

Arguments

Value

An OpenMx pedigree model combining variance components and family groups.

Description

This function iterates through generations in a pedigree simulation, assigning IDs, creating data frames, determining sexes, and managing pairing within each generation.

Usage

buildWithinGenerations(
  beta = FALSE,
  sizeGens,
  marR,
  sexR,
  Ngen,
  verbose = FALSE,
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  code_male = "M",
  code_female = "F",
  fam_shift = 1L
)

Arguments

Value

A data frame representing the simulated pedigree, including columns for family ID ('fam'),

Description

calcAllGens A function to calculate the number of individuals in each generation. This is a supporting function for simulatePedigree.

Usage

calcAllGens(kpc, Ngen, marR)

allGens(kpc, Ngen, marR)

Arguments

Value

Returns a vector containing the number of individuals in every generation.

Description

calcFamilySize A function to calculate the total number of individuals in a pedigree given parameters. This is a supporting function for function simulatePedigree

Usage

calcFamilySize(kpc, Ngen, marR)

famSizeCal(kpc, Ngen, marR)

Arguments

Value

Returns a numeric value indicating the total pedigree size.

Description

calcFamilySizeByGen An internal supporting function for simulatePedigree.

Usage

calcFamilySizeByGen(kpc, Ngen, marR)

sizeAllGens(kpc, Ngen, marR)

Arguments

Value

Returns a vector including the number of individuals in every generation.

Description

Compute confidence intervals (CIs) for correlation coefficients using either Fisher's $r \rightarrow z$ approach (Raykov-style on the $z$ scale) or a Wald CI on the $r$ scale. Standard errors are first **adjusted** by a design-effect factor when available, and optionally for double entry. The adjusted standard errors are used for all calculations, including CIs, z-tests, and p-values.

Usage

calculateCIs(
  tbl,
  rho_var,
  se_var,
  doubleentered = FALSE,
  method = "raykov",
  adjust_base = 1,
  design_effect_m = NULL,
  design_effect_rho = NULL,
  design_effect_m_col = NULL,
  design_effect_rho_col = NULL,
  conf_level = 0.95
)

Arguments

Value

A modified version of tbl with additional columns for the confidence intervals and related statistics. Everything uses adjusted standard errors, including confidence intervals, z-tests, and p-values.

Note

Double-entry handling and design effects are governed by doubleentered, design_effect_m/design_effect_rho (or their *_col variants), and adjust_base. The "doubleentered*" method values simply provide convenient aliases: they toggle doubleentered to TRUE only when the user hasn't explicitly set it, and map to "raykov" or "wald" as described.

Examples

tbl <- data.frame(rho = c(0.5, 0.7, 0.3), se = c(0.1, 0.2, 0.05))
calculateCIs(tbl, rho_var = "rho", se_var = "se", method = "raykov")

Description

Use Falconer's formula to solve for H using the observed correlations for two groups of any two levels of relatednesses.

Usage

calculateH(r1, r2, obsR1, obsR2)

Arguments

Details

This generalization of Falconer's formula provides a method to calculate heritability by using the observed correlations for two groups of any two relatednesses. This function solves for H using the formula:

$H^2 = \frac{obsR1 - obsR2}{r1 - r2}$

where r1 and r2 are the relatedness coefficients for the first and second group, respectively, and obsR1 and obsR2 are the observed correlations.

Value

Heritability estimates ('heritability_estimates').

Description

This function calculates the relatedness coefficient between two individuals based on their shared ancestry, as described by Wright (1922).

Usage

calculateRelatedness(
  generations = 2,
  path = NULL,
  full = TRUE,
  maternal = FALSE,
  empirical = FALSE,
  segregating = TRUE,
  total_a = 6800 * 1e+06,
  total_m = 16500,
  weight_a = 1,
  weight_m = 1,
  denom_m = FALSE,
  ...
)

related_coef(...)

Arguments

Details

The relatedness coefficient between two people (b & c) is defined in relation to their common ancestors: $r_{bc} = \sum \left(\frac{1}{2}\right)^{n+n'+1} (1+f_a)$

Value

Relatedness Coefficient ('coef'): A measure of the genetic relationship between two individuals.

Examples

## Not run: 
# For full siblings, the relatedness coefficient is expected to be 0.5:
calculateRelatedness(generations = 1, full = TRUE)
# For half siblings, the relatedness coefficient is expected to be 0.25:
calculateRelatedness(generations = 1, full = FALSE)

## End(Not run)

Description

This function takes a pedigree object and performs two main tasks: 1. Checks for the uniqueness of individual IDs. 2. Optionally repairs non-unique IDs based on a specified logic.

Usage

checkIDs(ped, verbose = FALSE, repair = FALSE)

Arguments

Value

Depending on 'repair' value, either returns a list containing validation results or a repaired dataframe

Examples

## Not run: 
ped <- data.frame(ID = c(1, 2, 2, 3), dadID = c(NA, 1, 1, 2), momID = c(NA, NA, 2, 2))
checkIDs(ped, verbose = TRUE, repair = FALSE)

## End(Not run)

Description

This function checks for duplicated individual IDs in a pedigree.

Usage

checkIDuniqueness(ped, verbose = FALSE)

Arguments

Value

A list containing the results of the check

Description

This function takes a pedigree object and performs two main tasks: 1. Checks for the validity of parent IDs, specifically looking for instances where only one parent ID is missing. 2. Optionally repairs the missing parent IDs based on a specified logic.

Usage

checkParentIDs(
  ped,
  verbose = FALSE,
  repair = FALSE,
  repairsex = repair,
  addphantoms = repair,
  parentswithoutrow = repair,
  famID = "famID",
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  code_male = NULL,
  code_female = NULL
)

Arguments

Value

Depending on the value of 'repair', either a list containing validation results or a repaired dataframe is returned.

Examples

## Not run: 
ped <- data.frame(ID = 1:4, dadID = c(NA, 1, 1, 2), momID = c(NA, NA, 2, 2))
checkParentIDs(ped, verbose = TRUE, repair = FALSE)

## End(Not run)

Description

Validates sex coding consistency for a given parental role (momID or dadID).

Usage

checkParentSex(ped, parent_col, sex_col = "sex", verbose = FALSE)

Arguments

Value

A list containing role, unique sex codes, modal sex, inconsistent parents, and linked children.

Description

Checks for structural issues in pedigree networks, including: - Individuals with more than two parents. - Presence of cyclic parent-child relationships.

Usage

checkPedigreeNetwork(
  ped,
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  verbose = FALSE
)

Arguments

Value

List containing detailed validation results.

Examples

## Not run: 
results <- checkPedigreeNetwork(ped,
  personID = "ID",
  momID = "momID", dadID = "dadID", verbose = TRUE
)

## End(Not run)

Description

This function checks and optionally modifies the coding of the biological 'sex' variable in a pedigree dataset. It serves two primary purposes: 1. Recodes the 'sex' variable based on specified codes for males and females, if provided. 2. Identifies and optionally repairs inconsistencies in sex coding that could break the algorithm for constructing genetic pedigrees.

Usage

checkSex(
  ped,
  code_male = NULL,
  code_female = NULL,
  code_unknown = NULL,
  verbose = FALSE,
  repair = FALSE,
  momID = "momID",
  dadID = "dadID"
)

Arguments

Details

The validation process identifies: - The unique sex codes present in the dataset. - Whether individuals listed as fathers or mothers have inconsistent sex codes. - Instances where an individual's recorded sex does not align with their parental role.

If 'repair = TRUE', the function standardizes sex coding by: - Assigning individuals listed as fathers the most common male code in the dataset. - Assigning individuals listed as mothers the most common female code.

This function uses the terms 'male' and 'female' in a biological context, referring to chromosomal and other biologically-based characteristics necessary for constructing genetic pedigrees. The biological aspect of sex used in genetic analysis (genotype) is distinct from the broader, richer concept of gender identity (phenotype).

We recognize the importance of using language and methodologies that affirm and respect the full spectrum of gender identities. The developers of this package express unequivocal support for folx in the transgender and LGBTQ+ communities.

Value

Depending on the value of 'repair', either a list containing validation results or a repaired dataframe is returned.

Examples

## Not run: 
ped <- data.frame(ID = c(1, 2, 3), sex = c("M", "F", "M"))
checkSex(ped, code_male = "M", verbose = TRUE, repair = FALSE)

## End(Not run)

Description

This function checks for within-row duplicates in a pedigree.

Usage

checkWithinRowDuplicates(ped, verbose = FALSE)

Arguments

Value

A list containing the results of the check

Description

This function combines the 'name_given' and 'name_given_pieces' columns in a data frame. If both columns have non-missing values that differ, a warning is issued and the original 'name_given' is retained. If one column is missing, the other is used. The same logic applies to the 'name_surn' and 'name_surn_pieces' columns.

Usage

collapseNames(verbose, df_temp)

Arguments

Value

A data frame with the combined columns.

Description

This function processes one or more sparse relationship components (additive, mitochondrial, and common nuclear) and converts them into kinship link pairs. The resulting related pairs are either returned as a data frame or written to disk in CSV format.

Usage

com2links(
  rel_pairs_file = "dataRelatedPairs.csv",
  ad_ped_matrix = NULL,
  mit_ped_matrix = mt_ped_matrix,
  mt_ped_matrix = NULL,
  cn_ped_matrix = NULL,
  write_buffer_size = 1000,
  update_rate = 1000,
  gc = TRUE,
  writetodisk = TRUE,
  verbose = FALSE,
  legacy = FALSE,
  outcome_name = "data",
  drop_upper_triangular = TRUE,
  include_all_links_1ped = FALSE,
  ...
)

Arguments

Value

A data frame of related pairs if writetodisk is FALSE; otherwise, writes the results to disk.

Description

comp2vech Turn a variance component relatedness matrix into its half-vectorization

Usage

comp2vech(x, include.zeros = FALSE)

Arguments

Details

This function is a wrapper around the vech function, extending it to allow for blockwise matrices and specific classes. It facilitates the conversion of a variance component relatedness matrix into a half-vectorized form.

Value

The half-vectorization of the relatedness component matrix.

Examples

comp2vech(list(matrix(c(1, .5, .5, 1), 2, 2), matrix(1, 2, 2)))

Description

Compute Parent Adjacency Matrix with Multiple Approaches

Usage

computeParentAdjacency(
  ped,
  component,
  adjacency_method = "direct",
  saveable,
  resume,
  save_path,
  verbose = FALSE,
  lastComputed = 0,
  checkpoint_files,
  update_rate,
  parList,
  lens,
  save_rate_parlist,
  adjBeta_method = NULL,
  config,
  compress = config$compress,
  ...
)

Arguments

Details

The algorithms and methodologies used in this function are further discussed and exemplified in the vignette titled "examplePedigreeFunctions". For more advanced scenarios and detailed explanations, consult this vignette.

Description

This function takes an OpenMx model and applies the mxCondenseMatrixSlots wrapper to optimize memory usage for large matrices. This can be particularly beneficial when working with large pedigree models that include multiple relatedness matrices.

Usage

condenseMatrixSlots(model)

Arguments

Value

An OpenMx model with condensed matrix slots, or NULL if the input model is NULL.

Description

Counts the number of lines in a file (passed as a data frame with column "X1") that match various GEDCOM patterns. Returns a list with counts for each pattern.

Usage

countPatternRows(file)

Arguments

Value

A list with counts of specific GEDCOM tag occurrences.

Description

This function creates a data frame for a specific generation within the simulated pedigree. It initializes the data frame with default values for family ID, individual ID, generation number, paternal ID, maternal ID, spouse ID, and sex. All individuals are initially set with NA for paternal, maternal, spouse IDs, and sex, awaiting further assignment.

Usage

createGenDataFrame(
  sizeGens,
  genIndex,
  idGen,
  family_id_prefix = "fam",
  beta = FALSE
)

createGenDataFrame_beta(sizeGens, genIndex, idGen, family_id_prefix = "fam")

Arguments

Value

A data frame representing the initial structure for the individuals in the specified generation before any relationships (parental, spousal) are defined. The columns include family ID ('fam'), individual ID (‘id'), generation number ('gen'), father’s ID (‘pat'), mother’s ID ('mat'), spouse's ID ('spID'), and sex ('sex'), with NA values for paternal, maternal, and spouse IDs, and sex.

Examples

sizeGens <- c(3, 5, 4) # Example sizes for 3 generations
genIndex <- 2 # Creating data frame for the 2nd generation
idGen <- 101:105 # Example IDs for the 2nd generation
df_Ngen <- createGenDataFrame(sizeGens, genIndex, idGen)
print(df_Ngen)

Description

This internal function assigns sexes to the offspring in a generation based on the specified sex ratio.

Usage

determineSex(idGen, sexR, code_male = "M", code_female = "F", beta = FALSE)

determineSex_beta(idGen, sexR, code_male = "M", code_female = "F")

Arguments

Value

Vector of sexes ("M" for male, "F" for female) for the offspring.

Description

#' This function identifies and removes duplicate entries in a pedigree data frame based on a list of specified IDs. If multiple rows share the same ID and are identical, only one instance is retained. The function returns the modified pedigree data frame along with a log of changes made.

Usage

dropIdenticalDuplicateIDs(ped, ids, changes = NULL)

Arguments

Description

A function to drop a person from his/her parents in the simulated pedigree data.frame. The person can be dropped by specifying his/her ID or by specifying the generation which the randomly to-be-dropped person is in. The function can separate one pedigree into two pedigrees. Separating into small pieces should be done by running the function multiple times. This is a supplementary function for simulatePedigree.

Usage

dropLink(
  ped,
  ID_drop = NA_integer_,
  gen_drop = 2,
  sex_drop = NA_character_,
  n_drop = 1,
  verbose = FALSE
)

Arguments

Value

a pedigree with the dropped person's 'dadID' and 'momID' set to NA.

Description

Function to find the biggest families in a pedigree This function finds the biggest families in a pedigree. It is supposed to be used internally by the summarize_pedigree function.

Usage

findBiggest(foo_summary_dt, n_fooest = 5, n_foo_total = nrow(foo_summary_dt))

Arguments

Value

a data.table containing the biggest families in the pedigree.

Description

Identifies individuals who are structural "leaves" in the pedigree network — those who can potentially be removed without substantially altering the connectivity of the larger tree.

Usage

findLeaves(
  ped,
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  include_terminal = TRUE,
  include_founder_singletons = TRUE,
  keep_var = NULL,
  keep_vals = NULL,
  verbose = FALSE
)

Arguments

Details

Two types of leaves are identified:

• Terminal nodes: individuals with outdegree 0, meaning they have no children recorded in the pedigree. Controlled by include_terminal.

• Founder singletons: individuals with indegree 0 and outdegree 1, meaning they are founders (no recorded parents) who appear as a parent of exactly one child. Controlled by include_founder_singletons.

In the directed pedigree graph used by ped2graph, edges run from parent to child. Consequently, indegree reflects the number of recorded parents and outdegree reflects the number of recorded children.

Value

A character vector of person IDs that are leaf nodes.

See Also

trimPedigree to iteratively remove the identified leaves.

Examples

## Not run: 
ped <- data.frame(
  ID    = 1:6,
  dadID = c(NA, NA, 1, 1, 3, NA),
  momID = c(NA, NA, 2, 2, 4, NA)
)
findLeaves(ped)

## End(Not run)

Description

Function to find the oldest individuals in a pedigree This function finds the oldest families in a pedigree. It is supposed to be used internally by the summarize_pedigree function.

Usage

findOldest(
  foo_summary_dt,
  byr = "byr",
  n_fooest = 5,
  n_foo_total = nrow(foo_summary_dt)
)

Arguments

Value

a data.table containing the oldest families in the pedigree.

Description

fitComponentModel Fit the estimated variance components of a model to covariance data

Usage

fitComponentModel(covmat, ...)

Arguments

Details

This function fits the estimated variance components of a model to given covariance data. The rank of the component matrices is checked to ensure that the variance components are all identified. Warnings are issued if there are inconsistencies.

Value

A regression (linear model fitted with lm). The coefficients of the regression represent the estimated variance components.

Examples

## Not run: 
# install.packages("OpenMX")
data(twinData, package = "OpenMx")
sellVars <- c("ht1", "ht2")
mzData <- subset(twinData, zyg %in% c(1), c(selVars, "zyg"))
dzData <- subset(twinData, zyg %in% c(3), c(selVars, "zyg"))

fitComponentModel(
  covmat = list(cov(mzData[, selVars], use = "pair"), cov(dzData[, selVars], use = "pair")),
  A = list(matrix(1, nrow = 2, ncol = 2), matrix(c(1, 0.5, 0.5, 1), nrow = 2, ncol = 2)),
  C = list(matrix(1, nrow = 2, ncol = 2), matrix(1, nrow = 2, ncol = 2)),
  E = list(diag(1, nrow = 2), diag(1, nrow = 2))
)

## End(Not run)

Description

This function constructs and fits an OpenMx model for a pedigree using specified variance components and family group models.

Usage

fitPedigreeModel(
  model_name = "PedigreeModel",
  vars = list(ad2 = 0.5, dd2 = 0.3, cn2 = 0.2, ce2 = 0.4, mt2 = 0.1, am2 = 0.25, ee2 =
    0.6),
  data = NULL,
  group_models = NULL,
  Addmat = NULL,
  Nucmat = NULL,
  Extmat = NULL,
  Mtdmat = NULL,
  Amimat = NULL,
  Dmgmat = NULL,
  tryhard = TRUE,
  intervals = TRUE,
  extraTries = 10,
  condenseMatrixSlots = TRUE
)

Arguments

Value

A fitted OpenMx model.

Description

Fuse MZ twin pairs in a pedigree dataset for path tracing This function identifies MZ twin pairs in the pedigree dataset and merges their IDs for path tracing purposes. The second twin in each pair is made a founder (with NA parents), and all children of the second twin are redirected to the first twin. This allows for correct relatedness calculations without diagonal or downstream artifacts.

Usage

fuseTwins(
  ped,
  df_twins = NULL,
  mz_id_pairs = NULL,
  mz_row_pairs = NULL,
  config = list(verbose = FALSE),
  test_df_twins = FALSE,
  beta = FALSE
)

Arguments

Value

A modified version of the input pedigree data.frame with MZ twin pairs fused for path tracing. If test_df_twins is TRUE, returns the data frame of identified twin pairs instead.

Description

Returns a single numeric value representing how many generations apart two individuals are, according to the chosen method.

Usage

getGenDist(
  ped,
  id1,
  id2,
  method = c("rank", "path", "mrca_min", "mrca_max", "mrca_all"),
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  max_gen = 25L,
  ...
)

Arguments

Value

A single numeric value, or NA if no genealogical path exists.

See Also

ped2genDist, ped2genDistFocal

Description

A dataset simulated to have an age-related hazard. There are two extended families that are sampled from the same population.

Usage

data(hazard)

Format

A data frame with 43 rows and 14 variables

Details

The variables are as follows:

• FamID: ID of the extended family

• ID: Person identification variable

• sex: Sex of the ID: 1 is female; 0 is male

• dadID: ID of the father

• momID: ID of the mother

• affected: logical. Whether the person is affected or not

• DA1: Binary variable signifying the meaninglessness of life

• DA2: Binary variable signifying the fundamental unknowability of existence

• birthYr: Birth year for person

• onsetYr: Year of onset for person

• deathYr: Death year for person

• available: logical. Whether

• Gen: Generation of the person

• proband: logical. Whether the person is a proband or not

Description

identifyComponentModel Determine if a variance components model is identified

Usage

identifyComponentModel(..., verbose = TRUE)

Arguments

Details

This function checks the identification status of a given variance components model by examining the rank of the concatenated matrices of the components. If any components are not identified, their names are returned in the output.

Value

A list of length 2 containing:

• identified: TRUE if the model is identified, FALSE otherwise.

• nidp: A vector of non-identified parameters, specifying the names of components that are not simultaneously identified.

Examples

identifyComponentModel(A = list(matrix(1, 2, 2)), C = list(matrix(1, 2, 2)), E = diag(1, 2))

Description

A dataset created purely from imagination that includes several types of inbreeding. Different kinds of inbreeding occur in each extended family.

The types of inbreeding are as follows:

• Extended Family 1: Sister wives - Children with the same father and different mothers who are sisters.

• Extended Family 2: Full siblings have children.

• Extended Family 3: Half siblings have children.

• Extended Family 4: First cousins have children.

• Extended Family 5: Father has child with his daughter.

• Extended Family 6: Half sister wives - Children with the same father and different mothers who are half sisters.

• Extended Family 7: Uncle-niece and Aunt-nephew have children.

• Extended Family 8: A father-son pairs has children with a corresponding mother-daughter pair.

Although not all of the above structures are technically inbreeding, they aim to test pedigree diagramming and path tracing algorithms. This dataset is not intended to represent any real individuals or families.

The variables are as follows:

• ID: Person identification variable

• sex: Sex of the ID: 1 is female; 0 is male

• dadID: ID of the father

• momID: ID of the mother

• FamID: ID of the extended family

• Gen: Generation of the person

• proband: Always FALSE

Usage

data(inbreeding)

Format

A data frame (and ped object) with 134 rows and 7 variables

Description

Creates a named list with all GEDCOM initialized to NA_character_.

Usage

initializeRecord(all_var_names)

Arguments

Value

A named list representing an empty individual record.

Description

evenInsert A function to insert m elements evenly into a length n vector.

Usage

insertEven(m, n, verbose = FALSE)

evenInsert(m, n, verbose = FALSE)

Arguments

Details

The function takes two vectors, m and n, and inserts the elements of m evenly into n. If the length of m is greater than the length of n, the vectors are swapped, and the insertion proceeds. The resulting vector is a combination of m and n, with the elements of m evenly distributed within n.

Value

Returns a numeric vector with the elements of m evenly inserted into n.

See Also

SimPed for the main function that uses this supporting function.

Description

A function to create inbred mates in the simulated pedigree data.frame. Inbred mates can be created by specifying their IDs or the generation the inbred mate should be created. When specifying the generation, inbreeding between siblings or 1st cousin needs to be specified. This is a supplementary function for simulatePedigree.

Usage

makeInbreeding(
  ped,
  ID_mate1 = NA_integer_,
  ID_mate2 = NA_integer_,
  verbose = FALSE,
  gen_inbred = 2,
  type_inbred = "sib",
  prefer_unmated = FALSE
)

Arguments

Details

This function creates inbred mates in the simulated pedigree data.frame. This function's purpose is to evaluate the effect of inbreeding on model fitting and parameter estimation. In case it needs to be said, we do not condone inbreeding in real life. But we recognize that it is a common practice in some fields to create inbred strains for research purposes.

Value

Returns a data.frame with some inbred mates.

Description

A function to impute twins in the simulated pedigree data.frame. Twins can be imputed by specifying their IDs or by specifying the generation the twin should be imputed. This is a supplementary function for simulatePedigree.

Usage

makeTwins(
  ped,
  ID_twin1 = NA_integer_,
  ID_twin2 = NA_integer_,
  gen_twin = 2,
  verbose = FALSE,
  zygosity = "MZ",
  twin_sex = "R"
)

Arguments

Value

Returns a data.frame with MZ twins information added as a new column.

Description

This function scans the data frame and creates a mapping of family IDs to the corresponding parent IDs.

Usage

mapFAMS2parents(df_temp, mom_sex = "F", dad_sex = "M")

Arguments

Value

A list mapping family IDs to parent information.

Description

This subfunction marks individuals in a generation as potential sons, daughters, or parents based on their relationships and assigns unique couple IDs. It processes the assignment of roles and relationships within and between generations in a pedigree simulation.

Usage

markPotentialChildren(
  df_Ngen,
  i,
  Ngen,
  sizeGens,
  CoupleF,
  code_male = "M",
  code_female = "F",
  beta = FALSE
)

markPotentialChildren_beta(
  df_Ngen,
  i,
  Ngen,
  sizeGens,
  CoupleF,
  code_male = "M",
  code_female = "F"
)

Arguments

Value

Modifies 'df_Ngen' in place by updating or adding columns related to individual roles ('ifparent', 'ifson', 'ifdau') and couple IDs ('coupleId'). The updated data frame is also returned for integration into the larger pedigree data frame ('df_Fam').

Description

Extracts full name information from a GEDCOM "NAME" line and updates the record accordingly.

Usage

parseNameLine(line, record)

Arguments

Value

The updated record with parsed name information.

Description

Take a pedigree and turn it into an additive genetics relatedness matrix

Usage

ped2add(
  ped,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  chunk_size = 1000L,
  keep_ids = NULL,
  adjacency_method = "direct",
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  save_rate_gen = save_rate,
  save_rate_parlist = 1e+05 * save_rate,
  save_path = "checkpoint/",
  compress = TRUE,
  mz_twins = FALSE,
  mz_method = "addtwins",
  force_symmetric = TRUE,
  ...
)

Arguments

Details

The algorithms and methodologies used in this function are further discussed and exemplified in the vignette titled "examplePedigreeFunctions". For more advanced scenarios and detailed explanations, consult this vignette.

Description

Add a focal-person additive relatedness column to a pedigree

Usage

ped2addFocal(
  ped,
  focal_id,
  personID = "ID",
  col_name = NULL,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  chunk_size = 1000L,
  keep_ids = NULL,
  adjacency_method = "direct",
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  save_rate_gen = save_rate,
  save_rate_parlist = 1e+05 * save_rate,
  save_path = "checkpoint/",
  compress = TRUE,
  mz_twins = FALSE,
  mz_method = "addtwins",
  force_symmetric = TRUE,
  ...
)

Arguments

See Also

ped2focal

Description

Take a pedigree and turn it into an extended environmental relatedness matrix

Usage

ped2ce(
  ped,
  personID = "ID",
  keep_ids = NULL,
  sparse = FALSE,
  verbose = FALSE,
  ...
)

Arguments

Details

The algorithms and methodologies used in this function are further discussed and exemplified in the vignette titled "examplePedigreeFunctions". For more advanced scenarios and detailed explanations, consult this vignette.

Description

Take a pedigree and turn it into a common nuclear environmental matrix

Usage

ped2cn(
  ped,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  keep_ids = NULL,
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  adjacency_method = "direct",
  save_rate_gen = save_rate,
  save_rate_parlist = 1000 * save_rate,
  save_path = "checkpoint/",
  compress = TRUE,
  force_symmetric = FALSE,
  ...
)

Arguments

Details

The algorithms and methodologies used in this function are further discussed and exemplified in the vignette titled "examplePedigreeFunctions". For more advanced scenarios and detailed explanations, consult this vignette.

Description

Add a focal-person common nuclear relatedness column to a pedigree

Usage

ped2cnFocal(
  ped,
  focal_id,
  personID = "ID",
  col_name = NULL,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  chunk_size = 1000L,
  keep_ids = NULL,
  adjacency_method = "direct",
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  save_rate_gen = save_rate,
  save_rate_parlist = 1e+05 * save_rate,
  save_path = "checkpoint/",
  compress = TRUE,
  force_symmetric = FALSE,
  ...
)

Arguments

See Also

ped2focal

Description

Take a pedigree and turn it into a relatedness matrix

Usage

ped2com(
  ped,
  component,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  chunk_size = 1000L,
  keep_ids = NULL,
  adjacency_method = "direct",
  isChild_method = "partialparent",
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  save_rate_gen = save_rate,
  save_rate_parlist = 1e+05 * save_rate,
  update_rate = 100,
  save_path = "checkpoint/",
  adjBeta_method = NULL,
  compress = TRUE,
  mz_twins = TRUE,
  mz_method = "addtwins",
  beta = FALSE,
  force_symmetric = FALSE,
  ...
)

Arguments

Details

The algorithms and methodologies used in this function are further discussed and exemplified in the vignette titled "examplePedigreeFunctions". For more advanced scenarios and detailed explanations, consult this vignette.

Description

This function adds an extended family ID variable to a pedigree by segmenting that dataset into independent extended families using the weakly connected components algorithm.

Usage

ped2fam(
  ped,
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  famID = "famID",
  twinID = "twinID",
  overwrite = TRUE,
  ...
)

Arguments

Details

The general idea of this function is to use person ID, mother ID, and father ID to create an extended family ID such that everyone with the same family ID is in the same (perhaps very extended) pedigree. That is, a pair of people with the same family ID have at least one traceable relation of any length to one another.

This function works by turning the pedigree into a mathematical graph using the igraph package. Once in graph form, the function uses weakly connected components to search for all possible relationship paths that could connect anyone in the data to anyone else in the data.

Value

A pedigree dataset with one additional column for the newly created extended family ID

Description

Builds a relatedness matrix for the pedigree and extracts the column corresponding to a single focal individual, appending it as a new column on the pedigree data frame. The full matrix is computed so that relatedness is propagated correctly through all ancestors; only the focal column is retained in the output.

Individuals included in the matrix (all individuals when no keep_ids filter is applied, or those listed in keep_ids) receive their computed relatedness value; genuine zeros remain 0. Individuals excluded by keep_ids are coded as NA. The focal person's own self-relatedness (the matrix diagonal) is preserved as-is.

Usage

ped2focal(
  ped,
  component,
  focal_id,
  personID = "ID",
  col_name = NULL,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  chunk_size = 1000L,
  keep_ids = NULL,
  adjacency_method = "direct",
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  save_rate_gen = save_rate,
  save_rate_parlist = 1e+05 * save_rate,
  save_path = "checkpoint/",
  compress = TRUE,
  mz_twins = FALSE,
  mz_method = "addtwins",
  force_symmetric = TRUE,
  ...
)

Arguments

Value

The input ped data frame with one additional column giving the relatedness of each individual to focal_id for the requested component.

See Also

ped2com, ped2addFocal

Description

Take a pedigree and turn it into a generation relatedness matrix. It computes the rank of the generation matrix, which is the number of generations separating two individuals

Usage

ped2gen(
  ped,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  keep_ids = NULL,
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  adjacency_method = "direct",
  save_rate_gen = save_rate,
  save_rate_parlist = 1000 * save_rate,
  save_path = "checkpoint/",
  compress = TRUE,
  force_symmetric = FALSE,
  ...
)

Arguments

Details

The algorithms and methodologies used in this function are further discussed and exemplified in the vignette titled "examplePedigreeFunctions". For more advanced scenarios and detailed explanations, consult this vignette.

Description

Returns an n x n matrix of generational distances between all pairs of individuals in ped. Pairs with no genealogical path receive NA.

Uses ped2com with component = "distance" to build the ancestor distance matrix via the same adjacency construction and power iteration used by all other pedigree components, then reduces it to pairwise distances with vectorised outer + pmin/pmax.

Usage

ped2genDist(
  ped,
  method = c("rank", "path", "mrca_min", "mrca_max", "mrca_all"),
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  max_gen = 25L,
  ...
)

Arguments

Value

A numeric matrix with row and column names set to individual IDs.

See Also

getGenDist, ped2genDistFocal

Description

Appends a new column to ped containing the generational distance between each individual and the focal person. Unrelated individuals receive NA.

Usage

ped2genDistFocal(
  ped,
  focal_id,
  method = c("rank", "path", "mrca_min", "mrca_max", "mrca_all"),
  col_name = NULL,
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  max_gen = 25L,
  ...
)

Arguments

Value

The input ped with one additional column.

See Also

getGenDist, ped2genDist

Description

Add a focal-person generation relatedness column to a pedigree. It computes the rank of the generation matrix, which is the number of generations separating two individuals

Usage

ped2genFocal(
  ped,
  focal_id,
  personID = "ID",
  col_name = NULL,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  chunk_size = 1000L,
  keep_ids = NULL,
  adjacency_method = "direct",
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  save_rate_gen = save_rate,
  save_rate_parlist = 1e+05 * save_rate,
  save_path = "checkpoint/",
  compress = TRUE,
  force_symmetric = FALSE,
  ...
)

Arguments

See Also

ped2focal

Description

Turn a pedigree into a graph

Usage

ped2graph(
  ped,
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  twinID = "twinID",
  directed = TRUE,
  adjacent = c("parents", "mothers", "fathers"),
  ...
)

Arguments

Details

The general idea of this function is to represent a pedigree as a graph using the igraph package.

Once in graph form, several common pedigree tasks become much simpler.

The adjacent argument allows for different kinds of graph structures. When using parents for adjacency, the graph shows all parent-child relationships. When using mother for adjacency, the graph only shows mother-child relationships. Similarly when using father for adjacency, only father-child relationships appear in the graph. Construct extended families from the parent graph, maternal lines from the mothers graph, and paternal lines from the fathers graph.

Value

A graph

Description

Add a maternal line ID variable to a pedigree

Usage

ped2maternal(
  ped,
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  matID = "matID",
  twinID = "twinID",
  ...
)

Arguments

Details

Under various scenarios it is useful to know which people in a pedigree belong to the same maternal lines. This function first turns a pedigree into a graph where adjacency is defined by mother-child relationships. Subsequently, the weakly connected components algorithm finds all the separate maternal lines and gives them an ID variable.

See Also

[ped2fam()] for creating extended family IDs, and [ped2paternal()] for creating paternal line IDs

Description

Take a pedigree and turn it into a mitochondrial relatedness matrix

Usage

ped2mit(
  ped,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  keep_ids = NULL,
  adjacency_method = "direct",
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  save_rate_gen = save_rate,
  save_rate_parlist = 1e+05 * save_rate,
  save_path = "checkpoint/",
  compress = TRUE,
  force_symmetric = FALSE,
  ...
)

Arguments

Details

The algorithms and methodologies used in this function are further discussed and exemplified in the vignette titled "examplePedigreeFunctions". For more advanced scenarios and detailed explanations, consult this vignette.

Description

Add a focal-person mitochondrial relatedness column to a pedigree

Usage

ped2mitFocal(
  ped,
  focal_id,
  personID = "ID",
  col_name = NULL,
  max_gen = 25,
  sparse = TRUE,
  verbose = FALSE,
  gc = FALSE,
  flatten_diag = FALSE,
  standardize_colnames = TRUE,
  transpose_method = "tcrossprod",
  chunk_size = 1000L,
  keep_ids = NULL,
  adjacency_method = "direct",
  saveable = FALSE,
  resume = FALSE,
  save_rate = 5,
  save_rate_gen = save_rate,
  save_rate_parlist = 1e+05 * save_rate,
  save_path = "checkpoint/",
  compress = TRUE,
  force_symmetric = FALSE,
  ...
)

Arguments

See Also

ped2focal

Description

Add a paternal line ID variable to a pedigree

Usage

ped2paternal(
  ped,
  personID = "ID",
  momID = "momID",
  dadID = "dadID",
  patID = "patID",
  twinID = "twinID",
  ...
)

Arguments

Details

Under various scenarios it is useful to know which people in a pedigree belong to the same paternal lines. This function first turns a pedigree into a graph where adjacency is defined by father-child relationships. Subsequently, the weakly connected components algorithm finds all the separate paternal lines and gives them an ID variable.

See Also

[ped2fam()] for creating extended family IDs, and [ped2maternal()] for creating maternal line IDs

Description

This function optionally adds parent information, combines duplicate columns, and removes empty columns from the GEDCOM data frame. It is called by readGedcom() if post_process = TRUE.

Usage

postProcessGedcom(
  df_temp,
  remove_empty_cols = TRUE,
  combine_cols = TRUE,
  parse_dates = FALSE,
  add_parents = TRUE,
  skinny = TRUE,
  verbose = FALSE
)

Arguments

Value

The post-processed data frame.

Description

A dataset created for educational and illustrative use, containing a fictional pedigree modeled after characters from the Harry Potter series. This data is structured for use in software demonstrations involving pedigree diagrams, inheritance structures, and kinship modeling. This dataset is not intended to represent any real individuals or families. It includes no narrative content or protected expression from the original works and is provided solely for educational purposes. This dataset is not endorsed by or affiliated with the creators or copyright holders of the Harry Potter series.

Usage

data(potter)

Format

A data frame (and ped object) with 36 rows and 10 variables

Details

The variables are as follows:

• personID: Person identification variable

• famID: Family identification variable

• name: Name of the person

• first_name: First name of the person

• surname: Last name of the person

• gen: Generation of the person

• momID: ID of the mother

• dadID: ID of the father

• spouseID: ID of the spouse

• sex: Sex of the ID: 1 is male; 0 is female

• twinID: ID of the twin, if applicable

• zygosity: Zygosity of the twin, if applicable. mz is monozygotic; dz is dizygotic

IDs in the 100s momIDs and dadIDs are for people not in the dataset.

Description

Function to prepare the pedigree for summarization This function prepares the pedigree for summarization by ensuring that the necessary IDs are present and that the pedigree is built correctly.

Usage

prepSummarizePedigrees(
  ped,
  type,
  verbose = FALSE,
  famID,
  personID,
  momID,
  dadID,
  matID,
  patID
)

Arguments

Description

Extracts event details (e.g., date, place, cause, latitude, longitude) from a block of GEDCOM lines. For "birth": expect DATE on line i+1, PLAC on i+2, LATI on i+4, LONG on i+5. For "death": expect DATE on line i+1, PLAC on i+2, CAUS on i+3, LATI on i+4, LONG on i+5.

Usage

processEventLine(event, block, i, record, pattern_rows)

Arguments

Value

The updated record with parsed event information.#

Description

This function adds mother and father IDs to individuals in the data frame

Usage

processParents(df_temp, datasource, person_id_col = "personID")

Arguments

Value

The updated data frame with parent IDs added.

Description

Ingests a GEDCOM genealogy file, identifies individual records, and parses person-level identifiers, names, life events, attributes, and family relationships into a structured data frame. Optional post-processing can infer parental IDs from family relationships, reconcile redundant name fields, and remove uninformative columns from the parsed output.

Usage

readGedcom(
  file_path,
  verbose = FALSE,
  add_parents = TRUE,
  remove_empty_cols = TRUE,
  combine_cols = TRUE,
  skinny = FALSE,
  parse_dates = FALSE,
  update_rate = 1000,
  post_process = TRUE,
  ...
)

readGed(
  file_path,
  verbose = FALSE,
  add_parents = TRUE,
  remove_empty_cols = TRUE,
  combine_cols = TRUE,
  skinny = FALSE,
  parse_dates = FALSE,
  update_rate = 1000,
  post_process = TRUE,
  ...
)

readgedcom(
  file_path,
  verbose = FALSE,
  add_parents = TRUE,
  remove_empty_cols = TRUE,
  combine_cols = TRUE,
  skinny = FALSE,
  parse_dates = FALSE,
  update_rate = 1000,
  post_process = TRUE,
  ...
)

Arguments