Package {nprcgenekeepr}

Type:	Package
Title:	Genetic Tools for Colony Management
Version:	3.0.0
Description:	Provides genetic tools for colony management and implements a derivation of the work in Amanda Vinson and Michael J Raboin (2015) https://pmc.ncbi.nlm.nih.gov/articles/PMC4671785/ "A Practical Approach for Designing Breeding Groups to Maximize Genetic Diversity in a Large Colony of Captive Rhesus Macaques ('Macaca' 'mulatta')". It provides a 'Shiny' application with an exposed API. The application supports these main groups of functions: (1) Quality control of studbooks contained in text files or 'Excel' workbooks and of pedigrees within 'LabKey' Electronic Health Records (EHR); (2) Creation of pedigrees from a list of animals using the 'LabKey' EHR integration; (3) Creation and display of an age by sex pyramid plot of the living animals within the designated pedigree; (4) Generation of genetic value analysis reports; and (5) Creation of potential breeding groups with and without proscribed sex ratios and defined maximum kinships. Further tabs cover mate pair analysis, genetic diversity, marker genetics, potential parents, cross-center identity mapping, de-identified export, and genetic-health trends.
URL:	https://rmsharp.github.io/nprcgenekeepr/, https://github.com/rmsharp/nprcgenekeepr
BugReports:	https://github.com/rmsharp/nprcgenekeepr/issues
Depends:	R (≥ 4.1.0)
Imports:	anytime, bslib, data.table, DT, futile.logger, ggplot2, htmlTable, lifecycle, lubridate, Matrix, openxlsx, plotrix, quadprog, readxl, Rlabkey (≥ 3.2.0), sessioninfo, shiny, shinyBS, stringi, utils, visNetwork
Suggests:	chromote, dplyr, shinytest2, htmltools, htmlwidgets, kableExtra, kinship2, knitr, markdown, mockery, pkgdown, rmarkdown, spelling, testthat, withr, yaml
Language:	en-US
Encoding:	UTF-8
License:	MIT + file LICENSE
LazyData:	TRUE
VignetteBuilder:	knitr
Config/renv/profiles/dev/dependencies:	checkhelper, devtools, httpuv, qpdf, markdown, pak, roxygen2, spelling, usethis
Config/Needs/website:	quarto
Config/Needs/coverage:	covr
Config/Needs/dev:	devtools, roxygen2
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-10-31 18:04:17 UTC; rmsharp
Author:	Michael Raboin [aut], Terry Therneau [aut], Amanda Vinson [aut, dtc], R. Mark Sharp [aut, cre, cph, dtc], Matthew Schultz [aut], Southwest National Primate Research Center [fnd] (NIH grant P51 RR13986, work up to and including version 1.0), Oregon National Primate Research Center [fnd] (NIH grant P51 OD011092, work up to and including version 1.0)
Maintainer:	R. Mark Sharp <rmsharp@me.com>
Repository:	CRAN
Date/Publication:	2026-11-01 23:40:02 UTC

nprcgenekeepr: Genetic Tools for Colony Management

Description

Provides genetic tools for colony management and implements a derivation of the work in Amanda Vinson and Michael J Raboin (2015) https://pmc.ncbi.nlm.nih.gov/articles/PMC4671785/ "A Practical Approach for Designing Breeding Groups to Maximize Genetic Diversity in a Large Colony of Captive Rhesus Macaques ('Macaca' 'mulatta')". It provides a 'Shiny' application with an exposed API. The application supports these main groups of functions: (1) Quality control of studbooks contained in text files or 'Excel' workbooks and of pedigrees within 'LabKey' Electronic Health Records (EHR); (2) Creation of pedigrees from a list of animals using the 'LabKey' EHR integration; (3) Creation and display of an age by sex pyramid plot of the living animals within the designated pedigree; (4) Generation of genetic value analysis reports; and (5) Creation of potential breeding groups with and without proscribed sex ratios and defined maximum kinships. Further tabs cover mate pair analysis, genetic diversity, marker genetics, potential parents, cross-center identity mapping, de-identified export, and genetic-health trends.

Author(s)

Maintainer: R. Mark Sharp rmsharp@me.com (ORCID) [copyright holder, data contributor]

Authors:

• R. Mark Sharp rmsharp@me.com (ORCID) [copyright holder, data contributor]

• Michael Raboin

• Terry Therneau

• Amanda Vinson [data contributor]

• Matthew Schultz (ORCID)

Other contributors:

• Southwest National Primate Research Center (NIH grant P51 RR13986, work up to and including version 1.0) [funder]

• Oregon National Primate Research Center (NIH grant P51 OD011092, work up to and including version 1.0) [funder]

See Also

Useful links:

• https://rmsharp.github.io/nprcgenekeepr/

• https://github.com/rmsharp/nprcgenekeepr

• Report bugs at https://github.com/rmsharp/nprcgenekeepr/issues

Compute per-allele population frequency at one locus from a genotype matrix

Description

Internal helper for markerParentageLikelihood (issue #147 Slice 1, D9). Mirrors markerExpectedHeterozygosity's own inline "parse alleles out of the lo/hi genotype string, tabulate" pattern, factored into a small, independent, non-exported helper rather than modifying that (or any other) already-shipped statistical function's internals as a side effect of this feature (see this slice's own design document, D9, for why a fourth independent reimplementation was chosen over a shared extraction touching three existing files).

Usage

.markerAlleleFrequencyTable(genotypeMatrix, locus)

Arguments

Value

A named numeric vector, allele -> frequency, computed from the non-NA cells at locus only. A locus monomorphic among genotyped individuals returns a length-1 vector; a locus with no genotyped individual returns numeric(0).

Build a local pedigree copy with each flagged (id, role) slot blanked

Description

Internal helper for markerParentageLikelihood (issue #155, docs/planning/issue155-parentage-likelihood-candidate-lookup-plan.md D1). getPotentialParents only ever builds a candidate list for an animal with at least one missing (NA) parent slot; a flagged animal whose recorded parent is present but Mendelian-inconsistent has both slots non-NA by definition, so it never appears in getPotentialParents's own candidate search. This helper returns a local, unmutated-in-place copy of pedigree with exactly the named (id, role) slot(s) set to NA, so pedigree merely looks like a genuinely-missing-parent case to getPotentialParents – which is called completely unmodified against it, reusing its full demographic-eligibility engine (breeding-age floor, gestation window, proven-breeder preference) at 100\ never changed – the copy is scoped only to the caller's own getPotentialParents call argument.

Usage

.markerFlaggedSlotPedigree(pedigree, ids, roles)

Arguments

Value

A copy of pedigree, un-mutated except for the named slot(s). A duplicated pedigree$id is left un-blanked – which row is "the" flagged animal is undefined for an ambiguous id, so this falls through to the same fail-soft, zero-candidates posture as an id genuinely absent from pedigree, rather than silently blanking every matching row (mirrors scoreOnePair()'s own defensive nrow(pedRow) == 1L pattern a few lines above in this file).

Count opposite-homozygote (Mendelian-conflict) loci between two genotype rows

Description

Internal helper extracted from markerParentageExclusion (issue #147 Slice 1, D7) so markerParentageLikelihood can reuse the identical "informative conflict" comparison against an arbitrary candidate parent, rather than forking a second, independently-written comparison routine. Behavior-preserving: markerParentageExclusion()'s own exported signature, behavior, and test suite are unaffected by this extraction (see the golden-master regression test in test_markerParentageExclusion.R).

Usage

.markerOppositeHomozygoteCount(genoA, genoB)

Arguments

Value

A list with exclusionCount (integer; NA_integer_ if nLoci is 0) and nLoci (integer, the number of jointly non-missing loci compared).

Probability a parent transmits the reference allele

Description

Internal helper for markerParentageLikelihood (issue #147 Slice 1, D2). For reference allele refAllele, the value is the fraction of the parent's two alleles equal to refAllele: a parent homozygous for refAllele transmits it with probability 1; a heterozygous parent, 0.5; a parent homozygous for any other allele, 0. At a multiallelic locus all non-reference alleles are lumped together.

Usage

.markerTransmissionProbability(genoStr, refAllele)

Arguments

Value

A numeric scalar in {0, 0.5, 1}.

Offspring genotype probability given two allele-transmission sources

Description

Internal helper for markerParentageLikelihood (issue #147 Slice 1, D2). Computes the probability of an offspring's genotype given two independent sources of one transmitted allele each – either could be a real parent's own .markerTransmissionProbability, or the population reference-allele frequency standing in for an unrelated/unknown source (H2, or an untyped second parent under dyad conditioning). This one function covers all four H1/dyad, H1/trio, H2/dyad, and H2/trio cases simply by which t1/t2 values are passed in – verified at this session's Pre-RED to reduce exactly to Hardy-Weinberg genotype frequencies when both t1 and t2 equal the population frequency.

Usage

.markerTwoSourceGenotypeProbability(t1, t2, genoStr, refAllele)

Arguments

Value

A numeric scalar probability in [0, 1].

Parse per-animal MHC haplotype designations into a long call table

Description

Internal parse rule for MHC haplotype reporting (issue #148 design plan D3, ratified S704): NA or an empty string is a MISSING call; a designation matching ^(.+)\?$ is an UNCERTAIN (provisional) call of the haplotype with the trailing ? stripped; anything else is a certain call. Labels are otherwise opaque (design plan D9): a bare "?" has no label part to strip, so it is treated as a certain call of the literal label "?", not judged. Total function over checkMhcHaplotypeFile-validated input – no error paths. Values are not trimmed: a whitespace-only value, or whitespace followed by ?, is not treated as missing (for example " ?" gives the haplotype " " and uncertain TRUE), so trimming is assumed to happen upstream.

Usage

.parseMhcHaplotypeCalls(genotype)

Arguments

Value

A data.frame with one row per (animal x designation column), i.e. 2 rows per animal, ordered as all haplotype1 rows followed by all haplotype2 rows (not interleaved per animal): id (character), haplotype (character; the designation with any trailing ? stripped, or NA when missing), uncertain (logical), missing (logical).

Add an NA value for animals with no relative

Description

This allows kin to be used with setdiff when there are no relatives otherwise an error would occur because kin[['animal_with_no_relative']] would not be found. See the following: in groupAddAssign

Usage

addAnimalsWithNoRelative(kin, candidates)

Arguments

Details

available[[i]] <- setdiff(available[[i]], kin[[id]])

Value

The named list of high-kinship relatives (one element per animal Id, each value a character vector of that Id's high-kinship relatives) with an added element set to NA for each candidate that has no relative.

Examples

library(nprcgenekeepr)
qcPed <- nprcgenekeepr::qcPed
ped <- qcStudbook(qcPed,
  minSireAge = 2, minDamAge = 2, reportChanges = FALSE,
  reportErrors = FALSE
)
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen, sparse = FALSE)
currentGroups <- list(1L)
currentGroups[[1]] <- examplePedigree$id[1:3]
candidates <- examplePedigree$id[examplePedigree$status == "ALIVE"]
threshold <- 0.015625
kin <- getAnimalsWithHighKinship(kmat, ped, threshold, currentGroups,
  ignore = list(c("F", "F")), minAge = 1.0
)
# Filtering out candidates related to current group members
conflicts <- unique(c(
  unlist(kin[unlist(currentGroups)]),
  unlist(currentGroups)
))
candidates <- setdiff(candidates, conflicts)
kin <- addAnimalsWithNoRelative(kin, candidates)
length(kin) # should be 591
kin[["0DAV0I"]] # should have 34 IDs

Add back second parents to a trimmed pedigree

Description

Uses the ped dataframe, which has full complement of parents and the uPed dataframe, which has all uninformative parents removed to add back single parents to the uPed dataframe where one parent is known. The parents are added back to the pedigree as an ID record with NA for both sire and dam of the added back ID.

Usage

addBackSecondParents(uPed, ped)

Arguments

Value

A pedigree with single parents added. It is a data.table once any record is added and a plain dataframe when none is.

Examples

examplePedigree <- nprcgenekeepr::examplePedigree
breederPed <- qcStudbook(examplePedigree,
  minSireAge = 2, minDamAge = 2,
  reportChanges = FALSE,
  reportErrors = FALSE
)
probands <- breederPed$id[!(is.na(breederPed$sire) &
  is.na(breederPed$dam)) &
  is.na(breederPed$exit)]
ped <- getProbandPedigree(probands, breederPed)
nrow(ped)
p <- removeUninformativeFounders(ped)
nrow(p)
p <- addBackSecondParents(p, ped)
nrow(p)

Add genotype data to pedigree file

Description

Assumes genotype has been opened by checkGenotypeFile

Usage

addGenotype(ped, genotype)

Arguments

Details

The two allele columns are coerced to character internally so the name-keyed allele dictionary is both built and indexed by allele label. This keeps the integer encoding consistent even when the allele columns are supplied as factors (a factor would otherwise be indexed by its integer codes). The allele columns are taken by position (columns 2 and 3 of genotype), not by name. The result is the output of a full outer merge() on id, so genotype ids that are absent from ped are added as extra rows.

Value

A plain data.frame (not a special pedigree class) with the rows of ped plus integer columns first and second holding the allele codes (numbered from 10001).

Examples

library(nprcgenekeepr)
rhesusPedigree <- nprcgenekeepr::rhesusPedigree
rhesusGenotypes <- nprcgenekeepr::rhesusGenotypes
pedWithGenotypes <- addGenotype(
  ped = rhesusPedigree,
  genotype = rhesusGenotypes
)

Add ego records with NA parent IDs

Description

Add ego records with NA parent IDs

Usage

addIdRecords(ids, fullPed, partialPed)

Arguments

Value

Pedigree with Ego records added having NAs for parent IDs. It is a data.table once any record is added and a plain dataframe when none is.

Examples

uPedOne <- data.frame(
  id = c("d1", "s2", "d2", "o1", "o2", "o3", "o4"),
  sire = c("s0", "s4", NA, "s1", "s1", "s2", "s2"),
  dam = c("d0", "d4", NA, "d1", "d2", "d2", "d2"),
  sex = c("F", "M", "F", "F", "F", "F", "M"),
  stringsAsFactors = FALSE
)
pedOne <- data.frame(
  id = c("s1", "d1", "s2", "d2", "o1", "o2", "o3", "o4"),
  sire = c(NA, "s0", "s4", NA, "s1", "s1", "s2", "s2"),
  dam = c(NA, "d0", "d4", NA, "d1", "d2", "d2", "d2"),
  sex = c("M", "F", "M", "F", "F", "F", "F", "M"),
  stringsAsFactors = FALSE
)
pedOne[!pedOne$id %in% uPedOne$id, ]
newPed <- addIdRecords(ids = "s1", pedOne, uPedOne)
pedOne[!pedOne$id %in% newPed$id, ]
newPed[newPed$id == "s1", ]

Add parents

Description

Pedigree curation function Given a pedigree, find any IDs listed in the "sire" or "dam" columns that lack their own line entry and generate one.

Usage

addParents(ped)

Arguments

Details

This must be run after addUIds since the IDs made there are used by addParents

Value

An updated pedigree with entries added as necessary. Entries have the id and sex specified; all remaining columns except recordStatus are filled with NA. A recordStatus column is added (replacing any existing one) with "original" for the existing records and "added" for the new ones.

Examples

pedTwo <- data.frame(
  id = c("d1", "s2", "d2", "o1", "o2", "o3", "o4"),
  sire = c(NA, NA, NA, "s1", "s1", "s2", "s2"),
  dam = c(NA, NA, NA, "d1", "d2", "d2", "d2"),
  sex = c("F", "M", "F", "F", "F", "F", "M"),
  stringsAsFactors = FALSE
)
newPed <- addParents(pedTwo)
newPed

Build a group data frame with ID, sex, and age

Description

Build a group data frame with ID, sex, and age

Usage

addSexAndAgeToGroup(ids, ped)

Arguments

Details

An empty ids vector yields a zero-row data frame that still contains all three columns (ids, sex, age), with sex an empty factor, so the returned schema does not depend on the number of ids supplied.

Value

A data frame with columns ids, sex and age (current age). Every id must occur exactly once in ped$id; an id that is missing from or duplicated in ped causes an error rather than an NA.

Examples

library(nprcgenekeepr)
data("qcBreeders")
data("qcPed")
df <- addSexAndAgeToGroup(ids = qcBreeders, ped = qcPed)
head(df)

Add placeholder IDs for unknown parents

Description

This must be run prior to addParents since the IDs made herein are used by addParents

Usage

addUIds(ped, format = getAutoIdFormat())

Arguments

Details

The generated placeholder IDs default to the form Unnnn (a leading "U" plus a zero-padded integer), so they are alphanumeric and never contain a period ("."), honoring the ID rule enforced at data input by qcStudbook. The format is configurable via setAutoIdFormat (default "U%04d"). A candidate ID that is already in the pedigree is skipped, so a placeholder never duplicates the ID of a real animal.

Value

The updated pedigree in which each missing sire or dam of a single-parent record is replaced by a generated placeholder ID.

Examples

pedTwo <- data.frame(
  id = c("s1", "d1", "s2", "d2", "o1", "o2", "o3", "o4"),
  sire = c(NA, "s0", "s4", NA, "s1", "s1", "s2", "s2"),
  dam = c("d0", "d0", "d4", NA, "d1", "d2", "d2", "d2"),
  sex = c("M", "F", "M", "F", "F", "F", "F", "M"),
  stringsAsFactors = FALSE
)
newPed <- addUIds(pedTwo)
newPed[newPed$id == "s1", ]
pedThree <-
  data.frame(
    id = c("s1", "d1", "s2", "d2", "o1", "o2", "o3", "o4"),
    sire = c("s0", "s0", "s4", NA, "s1", "s1", "s2", "s2"),
    dam = c(NA, "d0", "d4", NA, "d1", "d2", "d2", "d2"),
    sex = c("M", "F", "M", "F", "F", "F", "F", "M"),
    stringsAsFactors = FALSE
  )
newPed <- addUIds(pedThree)
newPed[newPed$id == "s1", ]

Count each allele in a vector

Description

Part of Genetic Value Analysis

Usage

alleleFreq(alleles, ids = NULL)

Arguments

Details

If ids are provided, the function will only count the unique alleles for an individual (homozygous alleles will be counted as 1).

Value

A data.frame with columns allele (a factor) and freq. This is a table of allele counts within the population.

Examples

library(nprcgenekeepr)
data("ped1Alleles")
ids <- ped1Alleles$id
alleles <- ped1Alleles[, !(names(ped1Alleles) %in% c("id", "parent"))]
aF <- alleleFreq(alleles[[1]], ids = NULL)
aF[aF$freq >= 10, ]

Main Application Server for nprcgenekeepr

Description

Server function for the main GeneKeepR Shiny application. Initializes all modules and manages shared reactive state between them.

Usage

appServer(input, output, session)

Arguments

Details

The server handles:

• Configuration loading from site-specific config files

• Navigation button handlers for the home page

• Dynamic tab management for QC errors and changed columns

• Module initialization and data flow between modules

Value

No return value, called for side effects. As a 'Shiny' server function, appServer() is invoked by the 'Shiny' runtime to wire up the application's reactive outputs, observers, and module servers for a running GeneKeepR session.

See Also

appUI for the corresponding UI function

modInputServer for data input module

modPedigreeServer for pedigree browser module

modGeneticValueServer for genetic value analysis

shouldShowChangedColsTab for changed columns tab logic

loadSiteConfig for site configuration loading

Main Application UI for nprcgenekeepr

Description

Main Application UI for nprcgenekeepr

Usage

appUI(siteInfo = NULL)

Arguments

Value

A shiny.tag.list object (as produced by shiny::tagList()) describing the complete GeneKeepR user interface; pass it as the ui argument to shiny::shinyApp() or shiny::runApp().

Append a colony snapshot to a snapshot history

Description

Pure merge for the longitudinal colony snapshot workflow (issue #167): takes a validated snapshot history (or NULL / a zero-row history for a first snapshot) and one new snapshot row, and returns the merged, date-ordered history. It writes nothing — script users persist the result themselves (e.g. write.csv(..., row.names = FALSE)), and the Shiny application writes only through a user-initiated download.

Usage

appendColonySnapshot(history, snapshot)

Arguments

Details

The new snapshot must carry the same schemaVersion as the history, and its (snapshotDate, membershipRule) pair must not already be present — the pair identifies a snapshot uniquely. The same date under a different membership rule is legal.

Value

The merged history, ordered by snapshotDate.

Examples

history <- checkSnapshotHistory(readSnapshotHistory(system.file(
  "extdata", "examples", "example_snapshot_history.csv",
  package = "nprcgenekeepr"
)))
snapshot <- history[3L, ]
snapshot$snapshotDate <- as.Date("2026-07-15")
appendColonySnapshot(history, snapshot)

Apply outside-information kinship overrides to a kinship matrix

Description

Writes pairwise kinship coefficients from outside information into a computed kinship matrix, replacing the pedigree-derived value for the named pairs. Each (id1, id2, kinship) row sets both kmat[id1, id2] and its symmetric twin kmat[id2, id1]; all other cells are unchanged. This is a direct cell replacement – it does not propagate to descendant rows. A successful call reports the number of overrides applied with a message().

Usage

applyKinshipOverrides(kmat, overrides)

Arguments

Details

kmat must be a dense, symmetric, id-named base R matrix (the object kinship returns); a sparse Matrix object is out of contract. The function is strict: it stop()s on an id absent from the matrix and on a value above the exact positive-semi-definiteness bound sqrt(kmat[id1, id1] * kmat[id2, id2]). Soft, run-preserving handling of ids outside the analysis set is the caller's responsibility – reportGV warn-drops non-member ids before calling this. This function's own algorithm – writing outside-information overrides onto an already-computed matrix – is never applied inside kinship itself (it has several callers, including two simulations that must not take current-kinship overrides). This is a different kind of adjustment than kinship's own twinRelations parameter: a declared MZ-twin pair's genetic identity is a structural pedigree fact, like sire/dam/sex, not outside information overriding a pedigree-derived computation – both simulations pass a known twin pair through unchanged, so twin identity needs no shielding of the kind overrides require. See docs/planning/twin-relations-kinship-computation-plan.md §2.3.

Value

kmat with the override cells replaced (symmetric).

Examples

ped <- nprcgenekeepr::qcPed
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen)
overrides <- data.frame(
  id1 = ped$id[1], id2 = ped$id[2], kinship = 0.25,
  stringsAsFactors = FALSE
)
kmat <- applyKinshipOverrides(kmat, overrides)

Assign parent alleles randomly

Description

Assign parent alleles randomly

Usage

assignAlleles(alleles, parentType, parent, id, n)

Arguments

Value

The original list alleles passed into the function with newly randomly assigned alleles to each id based on dam and sire genotypes.

Examples

alleles <- list(alleles = list(), counter = 1)
alleles <- assignAlleles(alleles,
  parentType = "sire", parent = NA,
  id = "o1", n = 4
)
alleles
alleles <- assignAlleles(alleles,
  parentType = "dam", parent = NA,
  id = "o1", n = 4
)
alleles

Rebuild earlier colony snapshots from a pedigree's birth and exit dates

Description

Builds one Genetic-Health Trends snapshot for each past date from the birth and exit dates already in a pedigree, so a trend can be drawn without waiting seasons for recorded snapshots (issue #170). Each row is the same 27-column row createColonySnapshot makes and passes checkSnapshotHistory, filed under its own membership rule, "reconstructedLiving", so rebuilt rows form a line of their own and never mix with recorded ones.

Usage

backfillColonySnapshots(
  ped,
  dates = NULL,
  guIter,
  guThresh,
  from = NULL,
  to = NULL,
  by = "year",
  existingHistory = NULL,
  minAnimals = 2L,
  updateProgress = NULL,
  ...
)

Arguments

Details

The dates. Give dates, or leave it out for a series of by steps (one year by default) from from to to. Unless you give them, the series starts at the first 1 January with at least minAnimals living animals and ends at the last 1 January on or before the latest birth or exit date in the pedigree. minAnimals only moves that default start: a date you name, in dates or as from, is never refused for having few animals.

Who was alive. For each date the pedigree is copied and every exit date after that date is blanked, because the demographic effective-size estimators read the exit column as it stands (see calcNeSexRatio): without the blanking an animal that was alive on the date but has left since would not count as a living breeder. The population is the real animals alive on the date. An animal is alive from its birth date; one with no birth date is alive from the birth of its first offspring that has a date (it was born before that offspring). It is alive until its exit date. An animal with no exit date counts only when the studbook lists it as living, the test the application applies today (status ALIVE, or no exit date when the pedigree has no status column), so an animal whose status is UNKNOWN never counts. Generated stand-in parents never enter the population. The pedigree is trimmed to that population and its ancestors (trimPedigree), analyzed with reportGV, and summarized with createColonySnapshot. For the date a pedigree was exported, the row equals the snapshot the application records for that pedigree.

What each date rests on. The support table says how many animals were counted, how many of them were placed through an offspring, how many more the studbook does not rule out (animals with no birth date that are not counted and had not left), and how much of the parentage is recorded. No threshold refuses a date; read these figures beside the trend. Where few sires are recorded the sex-ratio effective size reads low because of the missing records, not because of the colony.

Dates that fail. A date that cannot be analyzed (for example one on which fewer than two animals were alive) does not stop the others. It is listed in skipped with the message of the error, and one warning says how many dates failed. When no date can be built, the function stops and names the dates. A date whose "reconstructedLiving" row is already in existingHistory is not rebuilt; it is listed in skipped without a warning.

Twin pairs. A twinRelations table (see checkTwinRelations) is used on each date as far as that date's animals allow. Declared identical ("MZ twin") animals form groups, as in kinship, so the pairs A-B and B-C make the group A, B and C. On a date the groups are cut to the animals in that date's pedigree, which holds the animals alive then and their ancestors; a group left with two or more animals is applied and the others are left out. An animal missing from the pedigree on a date cannot change anyone's kinship that day, so a twin born later, or one who left and has no descendants, no longer makes the date fail. An identifier that is in no pedigree at all is a mistake and stops the function before any date is built.

Limits: today's parentage and today's genotypes are used for every date, so a parent identified later is treated as known earlier; the effective sizes follow the definition of a living breeder in calcNeSexRatio; and two close dates can differ only by gene-drop sampling.

Value

A list of three data.frames. history: the rebuilt snapshots (and the rows of existingHistory, if given), in date order, in the 27-column snapshot-history schema. support: one row for each date in the run, with snapshotDate, nLiving (the animals counted), nPlacedByOffspring (of those, the ones with no birth date), nPossiblyAlive, pctSireKnown and pctDamKnown (the percentage of the living animals whose sire or dam is recorded, that is neither blank nor a generated stand-in; NA when nobody was alive). skipped: the dates not rebuilt, with snapshotDate and reason.

See Also

createColonySnapshot, appendColonySnapshot, checkSnapshotHistory

Examples

ped <- nprcgenekeepr::qcPed
result <- backfillColonySnapshots(ped,
  dates = as.Date(c("2005-01-01", "2010-01-01")),
  guIter = 10L, guThresh = 1L
)
result$history[, c("snapshotDate", "membershipRule", "nAnimals")]
result$support

## a yearly series, added to the history above: the dates already there
## are not rebuilt
series <- backfillColonySnapshots(ped,
  from = "2005-01-01", to = "2008-01-01",
  guIter = 10L, guThresh = 1L, existingHistory = result$history
)
series$history[, c("snapshotDate", "nAnimals")]
series$skipped

Pivot a long-format marker genotype table into a wide genotype matrix

Description

Converts a validated long-format marker genotype table (see checkMarkerGenotypeFile) into a wide id x locus character matrix, the input shape markerKinship consumes.

Usage

buildMarkerGenotypeMatrix(genotype)

Arguments

Details

Row and column order follow first appearance in genotype, not a string sort – a string sort would place "L10" before "L2" for any panel with more than nine loci, silently scrambling locus order. If genotype has more than one row for the same id x locus, the last row silently overwrites the others, so run checkMarkerGenotypeFile first.

Value

A character matrix with one row per unique id and one column per unique locus. Each cell holds that individual's two alleles at that locus, sorted (by string collation, so locale-dependent for mixed-case alleles) and joined by "/" (e.g. "A/B"), or NA when that individual has no genotype record at that locus. A record with a missing allele gives NA, the same as a record that is not in the file; checkMarkerGenotypeFile does not reject such rows.

See Also

checkMarkerGenotypeFile, markerKinship

Examples

library(nprcgenekeepr)
markerGenotype <- data.frame(
  id = c("A", "A", "B", "B"),
  locus = c("L1", "L2", "L1", "L2"),
  allele1 = c("A", "A", "A", "A"),
  allele2 = c("A", "B", "B", "B"),
  stringsAsFactors = FALSE
)
buildMarkerGenotypeMatrix(markerGenotype)

Count each individual's rare alleles per simulation

Description

Part of Genetic Value Analysis

Usage

calcA(alleles, threshold = 1L, byID = FALSE)

Arguments

Value

A matrix with named rows indicating the number of rare alleles (0, 1 or 2) an animal had during each round of simulation (indicated in columns).

References

Ballou JD, Lacy RC. 1995. Identifying genetically important individuals for management of genetic variation in pedigreed populations, p 77-111. In: Ballou JD, Gilpin M, Foose TJ, editors. Population management for survival and recovery. New York (NY): Columbia University Press.

MacCluer JW, et al. 1986. Pedigree analysis by computer simulation. Zoo Biology 5:147-160.

See Also

Other genetic value analysis: calcFE(), calcFEFG(), calcFG(), calcFGSE(), calcGU(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

library(nprcgenekeepr)
rare <- calcA(nprcgenekeepr::ped1Alleles, threshold = 3, byID = FALSE)

Calculate animal ages

Description

Part of Pedigree Curation

Usage

calcAge(birth, exit)

Arguments

Details

Given vectors of birth and exit dates, calculate an individuals age. If no exit date is provided, the calculation is based on the current date.

Value

A numeric vector (NA allowed) indicating age in years, rounded to one decimal place, from "birth" to "exit" or the current date if "exit" is NA. If birth has length zero, it is returned unchanged (a Date, not numeric, vector).

Examples

library(nprcgenekeepr)
qcPed <- nprcgenekeepr::qcPed
originalAge <- qcPed$age ## ages calculated at time of data collection
currentAge <- calcAge(qcPed$birth, qcPed$exit) ## assumes no changes in
## colony

Calculate founder equivalents

Description

Part of the Genetic Value Analysis

Usage

calcFE(ped)

Arguments

Details

The pedigree must have no partial parentage (every animal has both parents known or both unknown); calcFE stops with an error otherwise.

Value

The founder equivalents FE = 1 / sum(p ^ 2), where p is the vector of founder mean contributions to the current descendants.

References

Lacy RC. 1989. Analysis of founder representation in pedigrees: founder equivalents and founder genome equivalents. Zoo Biol 8:111-123.

See Also

Other genetic value analysis: calcA(), calcFEFG(), calcFG(), calcFGSE(), calcGU(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

## Example from Analysis of Founder Representation in Pedigrees: Founder
## Equivalents and Founder Genome Equivalents.
## Zoo Biology 8:111-123, (1989) by Robert C. Lacy
library(nprcgenekeepr)
ped <- data.frame(
  id = c("A", "B", "C", "D", "E", "F", "G"),
  sire = c(NA, NA, "A", "A", NA, "D", "D"),
  dam = c(NA, NA, "B", "B", NA, "E", "E"),
  stringsAsFactors = FALSE
)
ped["gen"] <- findGeneration(ped$id, ped$sire, ped$dam)
ped$population <- getGVPopulation(ped, NULL)
pedFactors <- data.frame(
  id = c("A", "B", "C", "D", "E", "F", "G"),
  sire = c(NA, NA, "A", "A", NA, "D", "D"),
  dam = c(NA, NA, "B", "B", NA, "E", "E"),
  stringsAsFactors = TRUE
)
pedFactors["gen"] <- findGeneration(
  pedFactors$id, pedFactors$sire,
  pedFactors$dam
)
pedFactors$population <- getGVPopulation(pedFactors, NULL)
fe <- calcFE(ped)
feFactors <- calcFE(pedFactors)

Calculate founder equivalents and founder genome equivalents

Description

Part of the Genetic Value Analysis

Usage

calcFEFG(ped, alleles)

Arguments

Value

The list containing the founder equivalents, FE = 1 / sum(p ^ 2), and the founder genome equivalents, FG = 1 / sum( (p ^ 2) / r) where p is the vector of founder mean contributions to the current descendants and r is the mean number of founder alleles retained in the gene dropping experiment.

FE is deterministic and always returned. FG is NA (with a warning) when a contributing founder (p > 0) is retained in zero of the gene-drop iterations (r == 0), which would otherwise collapse FG silently to 0; raise the number of iterations. See calcFGSE for the sampling standard error of FG.

References

Lacy RC. 1989. Analysis of founder representation in pedigrees: founder equivalents and founder genome equivalents. Zoo Biol 8:111-123.

See Also

Other genetic value analysis: calcA(), calcFE(), calcFG(), calcFGSE(), calcGU(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

data(lacy1989Ped)
## Example from Analysis of Founder Representation in Pedigrees: Founder
## Equivalents and Founder Genome Equivalents.
## Zoo Biology 8:111-123, (1989) by Robert C. Lacy

library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
alleles <- lacy1989PedAlleles
pedFactors <- data.frame(
  id = as.factor(ped$id),
  sire = as.factor(ped$sire),
  dam = as.factor(ped$dam),
  gen = ped$gen,
  population = ped$population,
  stringsAsFactors = TRUE
)
allelesFactors <- geneDrop(pedFactors$id, pedFactors$sire, pedFactors$dam,
  pedFactors$gen,
  genotype = NULL, n = 1000,
  updateProgress = NULL
)
feFg <- calcFEFG(ped, alleles)
feFgFactors <- calcFEFG(pedFactors, allelesFactors)

Calculate founder genome equivalents

Description

Part of the Genetic Value Analysis

Usage

calcFG(ped, alleles)

Arguments

Value

The founder genome equivalents, FG = 1 / sum( (p ^ 2) / r) where p is the vector of founder mean contributions to the current descendants and r is the mean number of founder alleles retained in the gene dropping experiment.

Returns NA with a warning when a contributing founder (p > 0) is retained in zero of the gene-drop iterations (r == 0): that term is p^2 / 0 = Inf, which would otherwise collapse FG silently to 0. Raise the number of iterations. See calcFGSE for the sampling standard error of FG.

References

Lacy RC. 1989. Analysis of founder representation in pedigrees: founder equivalents and founder genome equivalents. Zoo Biol 8:111-123.

See Also

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFGSE(), calcGU(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

## Example from Analysis of Founder Representation in Pedigrees: Founder
## Equivalents and Founder Genome Equivalents.
## Zoo Biology 8:111-123, (1989) by Robert C. Lacy

library(nprcgenekeepr)
ped <- data.frame(
  id = c("A", "B", "C", "D", "E", "F", "G"),
  sire = c(NA, NA, "A", "A", NA, "D", "D"),
  dam = c(NA, NA, "B", "B", NA, "E", "E"),
  stringsAsFactors = FALSE
)
ped["gen"] <- findGeneration(ped$id, ped$sire, ped$dam)
ped$population <- getGVPopulation(ped, NULL)
pedFactors <- data.frame(
  id = c("A", "B", "C", "D", "E", "F", "G"),
  sire = c(NA, NA, "A", "A", NA, "D", "D"),
  dam = c(NA, NA, "B", "B", NA, "E", "E"),
  stringsAsFactors = TRUE
)
pedFactors["gen"] <- findGeneration(
  pedFactors$id, pedFactors$sire,
  pedFactors$dam
)
pedFactors$population <- getGVPopulation(pedFactors, NULL)
alleles <- geneDrop(ped$id, ped$sire, ped$dam, ped$gen,
  genotype = NULL,
  n = 1000, updateProgress = NULL
)
allelesFactors <- geneDrop(pedFactors$id, pedFactors$sire, pedFactors$dam,
  pedFactors$gen,
  genotype = NULL, n = 1000,
  updateProgress = NULL
)
fg <- calcFG(ped, alleles)
fgFactors <- calcFG(pedFactors, allelesFactors)

Calculate the standard error of founder genome equivalents

Description

Part of the Genetic Value Analysis

Usage

calcFGSE(ped, alleles)

Arguments

Details

Founder genome equivalents (calcFG) is a Monte Carlo estimate: FG = 1 / sum(p^2 / r), where the founder contributions p are deterministic but the mean allelic retention values r (calcRetention) are averages over the gene-drop iterations, so FG carries sampling error that shrinks as the number of iterations grows. Unlike genome uniqueness (a mean, whose standard error is a column variance), FG is a nonlinear function of r, so its standard error is obtained by the delta method (first-order linearization).

With S = sum(p_f^2 / r_f) and FG = 1 / S, the gradient is dFG/dr_f = FG^2 * p_f^2 / r_f^2. Writing R for the founder-by- iteration retention matrix (each column an independent gene drop), the influence series y_k = sum_f (dFG/dr_f) * R[f, k] has sd(y) / sqrt(K) equal to the full delta-method standard error, including the within-iteration covariance among founders. This influence form is used because it folds in that covariance automatically and never forms the founder-by-founder covariance matrix.

Founders are matched between p and r by name (not position), so the result is correct even when the founders are not in sorted pedigree order.

A contributing founder (p > 0) that is retained in zero of the iterations (r == 0) makes FG undefined (the same degeneracy that calcFG reports as NA); in that case this function returns NA with a warning advising more iterations. Founders that do not contribute to the current population (p == 0) are dropped, so the standard error refers to exactly the founder set FG is computed from.

Value

A single numeric value: the Monte Carlo sampling standard error of the colony founder-genome-equivalent estimate, on the same scale as calcFG. NA (with a warning) when a contributing founder has zero retention.

See Also

calcFG, calcFEFG, calcRetention, calcGUSE, reportGV

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFG(), calcGU(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

library(nprcgenekeepr)
data("lacy1989Ped")
data("lacy1989PedAlleles")
calcFGSE(lacy1989Ped, lacy1989PedAlleles)

Calculate genome uniqueness for each population ID

Description

Part of Genetic Value Analysis

Usage

calcGU(alleles, threshold = 1L, byID = FALSE, pop = NULL)

Arguments

Details

The following functions calculate genome uniqueness according to the equation described in Ballou & Lacy.

It should be noted, however that this function differs slightly in that it does not distinguish between founders and non-founders in calculating the statistic.

Ballou & Lacy describe genome uniqueness as "the proportion of simulations in which an individual receives the only copy of a founder allele." We have interpreted this as meaning that genome uniqueness should only be calculated for living, non-founder animals. Alleles possessed by living founders are not considered when calculating genome uniqueness.

We have a differing view on this, since a living founder can still contribute to the population. The function below calculates genome uniqueness for all living animals and considers all alleles. It does not ignore living founders and their alleles.

Our results for genome uniqueness will, therefore differ slightly from those returned by Pedscope. Pedscope calculates genome uniqueness only for non-founders and ignores the contribution of any founders in the population. This will cause Pedscope's genome uniqueness estimates to possibly be slightly higher for non-founders than what this function will calculate.

The estimates of genome uniqueness for founders within the population calculated by this function should match the "founder genome uniqueness" measure calculated by Pedscope.

Note that calcGU computes this statistic for every animal and still includes living founders' alleles; it is unchanged. The genetic value report (reportGV) separately applies a colony decline-to-credit policy that reports genome uniqueness as 0 for unknown-origin both-unknown ("Undetermined") animals.

Value

Dataframe rows: id, col: gu A single-column table of genome uniqueness values as percentages. Rownames are set to 'id' values that are part of the population.

References

Ballou JD, Lacy RC. 1995. Identifying genetically important individuals for management of genetic variation in pedigreed populations, p 77-111. In: Ballou JD, Gilpin M, Foose TJ, editors. Population management for survival and recovery. New York (NY): Columbia University Press.

MacCluer JW, et al. 1986. Pedigree analysis by computer simulation. Zoo Biology 5:147-160.

See Also

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFG(), calcFGSE(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

library(nprcgenekeepr)
ped1Alleles <- nprcgenekeepr::ped1Alleles
gu_1 <- calcGU(ped1Alleles, threshold = 1, byID = FALSE, pop = NULL)
gu_2 <- calcGU(ped1Alleles, threshold = 3, byID = FALSE, pop = NULL)
gu_3 <- calcGU(ped1Alleles,
  threshold = 3, byID = FALSE,
  pop = ped1Alleles$id[20:60]
)

Calculate the standard error of genome uniqueness

Description

Part of Genetic Value Analysis

Usage

calcGUSE(alleles, threshold = 1L, byID = FALSE, pop = NULL)

Arguments

Details

Genome uniqueness (calcGU) is a Monte Carlo estimate: it is the average, over the gene-drop iterations, of the proportion of an animal's two allele copies that are population-rare. Because it is an average over independent simulated iterations, it carries sampling error that shrinks as the number of iterations grows.

For animal i let m_ik = rare[i, k] / 2 be the per-iteration value in iteration k (so the mean of m_ik over the K iterations equals gu_i / 100). This function returns the exact Monte Carlo standard error of that mean, on the same percentage scale as calcGU:

guSE_i = 100 \times \sqrt{\frac{var(m_{i\cdot})}{K}}

The standard error is computed from the same per-iteration rare-allele matrix (calcA) that calcGU averages, so it is correct for any threshold / byID without a closed-form approximation. An animal whose rare-allele count does not vary across iterations has a standard error of 0.

Value

Dataframe rows: id, col: guSE A single-column table of genome-uniqueness standard errors as percentages. Rownames are set to 'id' values that are part of the population.

See Also

calcGU, calcA, reportGV

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFG(), calcFGSE(), calcGU(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

library(nprcgenekeepr)
ped1Alleles <- nprcgenekeepr::ped1Alleles
guSE <- calcGUSE(ped1Alleles, threshold = 3, byID = FALSE, pop = NULL)

Calculate gene diversity from founder genome equivalents

Description

Part of the Genetic Value Analysis

Usage

calcGeneDiversity(fg)

Arguments

Details

Gene diversity is the expected heterozygosity retained relative to the founding gene pool, GD = 1 - 1 / (2 * FG), where FG is the founder genome equivalents (see calcFG). It summarizes how much of the founders' allelic diversity still survives: it is 0 when FG = 0.5 (the smallest value FG takes in practice) and approaches (never reaches) 1 as FG grows.

GD is a diversity proportion, not a count of effective individuals, and it is computed over the same analysis set as FG. NA propagates: when FG is NA (the zero-retention degeneracy calcFG() reports), GD is NA.

Value

The gene diversity GD = 1 - 1 / (2 * fg): a single number below 1 (realized values lie in [0, 1)), or NA when fg is NA.

References

Gene diversity is derived here from the founder genome equivalents (calcFG) of Lacy RC. 1989. Analysis of founder representation in pedigrees: founder equivalents and founder genome equivalents. Zoo Biol 8:111-123.

See Also

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFG(), calcFGSE(), calcGU(), calcGUSE(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

calcGeneDiversity(20) # 0.975
calcGeneDiversity(52.75) # gene diversity at the qcPed FG

Calculate bias-adjusted sample excess kurtosis

Description

Part of the Genetic Value Analysis

Usage

calcKurtosis(x, na.rm = TRUE)

Arguments

Details

The bias-adjusted Fisher-Pearson standardized EXCESS kurtosis coefficient, G2 = ((n + 1) * g2 + 6) * (n - 1) / ((n - 2) * (n - 3)), where g2 = m4 / m2^2 - 3 and m2/m4 are the second/fourth central sample moments of x – the "Method 2" adjustment of Joanes and Gill (1998), the same convention SPSS, SAS, and Excel report by default and the type = 2 option in the e1071 CRAN package. Excess (not raw) kurtosis: a normal distribution reads 0. Positive values indicate heavier tails / a sharper peak than normal; negative, lighter tails / a flatter peak.

Returns NA when na.rm = FALSE and x contains an NA, when x has fewer than 4 non-NA values (n <= 3, the adjustment term divides by (n - 2) * (n - 3)) or has zero variance (all remaining values identical) – both would otherwise divide by zero.

Value

The bias-adjusted sample excess kurtosis, a single number; NA when degenerate (see Details).

References

Joanes, D.N. and Gill, C.A. (1998) "Comparing measures of sample skewness and kurtosis." Journal of the Royal Statistical Society: Series D (The Statistician), 47(1), 183-189.

See Also

calcSkewness

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFG(), calcFGSE(), calcGU(), calcGUSE(), calcGeneDiversity(), calcNeSexRatio(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

calcKurtosis(c(1, 2, 3, 4, 100)) # 4.986866, heavy-tailed
calcKurtosis(c(1, 2, 3, 4, 5)) # -1.2, flatter than normal

Calculate the demographic sex-ratio effective population size

Description

Part of the Genetic Value Analysis

Usage

calcNeSexRatio(ped)

Arguments

Details

The sex-ratio effective size, Ne = 4 * nMale * nFemale / (nMale + nFemale), is the effective population size implied by an unequal breeding sex ratio, where nMale and nFemale are the numbers of current living breeders that are known male and known female. It quantifies the diversity lost when many of one sex are bred to few of the other (as in a harem colony): it equals the census count when the sexes are balanced and falls toward four times the rarer sex as the ratio skews.

The breeders are the current living breeders of ped (living animals that appear as a sire or dam, excluding auto-generated unknown parents), independent of which animals are selected as probands – a different population than the analysis-set founder statistics (calcFE, calcFG, calcGeneDiversity). Only animals with a known sex ("M" or "F") are counted; unknown and hermaphrodite breeders are excluded. When either sex is absent among the living breeders (nMale == 0 or nFemale == 0, including no living breeders at all), the result is 0: a single breeding sex contributes no diversity from sex balance.

Like all effective-size estimators this idealizes a Wright-Fisher population (constant size, discrete generations, random union of gametes within each sex); a managed colony departs from those assumptions, so read the result as a sex-ratio index rather than a literal head count.

Value

The sex-ratio effective size, a single non-negative number; 0 when either breeding sex is absent among the living breeders.

References

Crow, J. F. and Kimura, M. (1970) An Introduction to Population Genetics Theory. Harper and Row, New York.

See Also

calcGeneDiversity

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFG(), calcFGSE(), calcGU(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeVariance(), calcRetention(), calcSkewness()

Examples

ped <- data.frame(
  id = c("s1", "d1", "d2", "k1", "k2"),
  sire = c(NA, NA, NA, "s1", "s1"),
  dam = c(NA, NA, NA, "d1", "d2"),
  sex = c("M", "F", "F", "M", "F"),
  exit = c(NA, NA, NA, NA, NA),
  stringsAsFactors = FALSE
)
calcNeSexRatio(ped) # 4 * 1 * 2 / (1 + 2) = 2.666667

Calculate the variance effective population size

Description

Part of the Genetic Value Analysis

Usage

calcNeVariance(ped)

Arguments

Details

The variance effective size measures the diversity lost to unequal family sizes – typically the dominant reducer of effective size in a harem colony, where a few breeders produce most of the offspring. It is the mean-adjusted Crow & Kimura (1970) form

N_e = \frac{N \bar{k} - 1}{\bar{k} - 1 + V_k / \bar{k}}

where N is the number of current living breeders, \bar{k} the mean number of lifetime offspring among them, and V_k the variance of those offspring counts. This general form makes no constant-size assumption and reduces to the classic (4N - 2) / (Vk + 2) at exact replacement (\bar{k} = 2); it is preferred over that bare form, which assumes \bar{k} \approx 2 and misstates the effective size when the mean family size departs from replacement.

The breeders are the current living breeders of ped (living animals that appear as a sire or dam, excluding auto-generated unknown parents), independent of which animals are selected as probands – a different population than the analysis-set founder statistics (calcFE, calcFG, calcGeneDiversity). Unlike the sex-ratio effective size (calcNeSexRatio), breeders of every sex are counted. When fewer than two living breeders are present the variance is undefined and the result is NA.

Like all effective-size estimators this idealizes a Wright-Fisher population (constant size, discrete generations, random union of gametes); a managed colony departs from those assumptions, so read the result as a family-size-variance index rather than a literal head count.

Value

The variance effective size, a single number; NA when there are fewer than two living breeders.

References

Crow, J. F. and Kimura, M. (1970) An Introduction to Population Genetics Theory. Harper and Row, New York.

See Also

calcNeSexRatio, calcGeneDiversity

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFG(), calcFGSE(), calcGU(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcRetention(), calcSkewness()

Examples

ped <- data.frame(
  id = c("s1", "d1", "k1", "k2", "k3"),
  sire = c(NA, NA, "s1", "s1", "s1"),
  dam = c(NA, NA, "d1", "d1", "d1"),
  sex = c("M", "F", "M", "F", "F"),
  exit = c(NA, NA, NA, NA, NA),
  stringsAsFactors = FALSE
)
calcNeVariance(ped) # 2 breeders, equal families: (2*3-1)/(3-1) = 2.5

Calculate allelic retention

Description

Part of Genetic Value Analysis

Usage

calcRetention(ped, alleles)

Arguments

Value

A named one-dimensional array with one value per founder: the proportion of the gene-drop simulations (a number from 0 to 1, not a count) in which the founder's allele is retained in the population's descendants.

References

Lacy RC. 1989. Analysis of founder representation in pedigrees: founder equivalents and founder genome equivalents. Zoo Biol 8:111-123.

See Also

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFG(), calcFGSE(), calcGU(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcSkewness()

Examples

library(nprcgenekeepr)
data("lacy1989Ped")
data("lacy1989PedAlleles")
ped <- lacy1989Ped
alleles <- lacy1989PedAlleles
retention <- calcRetention(ped, alleles)

Calculate bias-adjusted sample skewness

Description

Part of the Genetic Value Analysis

Usage

calcSkewness(x, na.rm = TRUE)

Arguments

Details

The bias-adjusted Fisher-Pearson standardized skewness coefficient, G1 = g1 * sqrt(n * (n - 1)) / (n - 2), where g1 = m3 / m2^1.5 and m2/m3 are the second/third central sample moments of x – the "Method 2" adjustment of Joanes and Gill (1998), the same convention SPSS, SAS, and Excel report by default and the type = 2 option in the e1071 CRAN package. A positive value indicates a longer right tail; negative, a longer left tail; 0, a symmetric distribution.

Returns NA when na.rm = FALSE and x contains an NA, when x has fewer than 3 non-NA values (n <= 2, the adjustment term divides by n - 2) or has zero variance (all remaining values identical) – both would otherwise divide by zero.

Value

The bias-adjusted sample skewness, a single number; NA when degenerate (see Details).

References

Joanes, D.N. and Gill, C.A. (1998) "Comparing measures of sample skewness and kurtosis." Journal of the Royal Statistical Society: Series D (The Statistician), 47(1), 183-189.

See Also

calcKurtosis

Other genetic value analysis: calcA(), calcFE(), calcFEFG(), calcFG(), calcFGSE(), calcGU(), calcGUSE(), calcGeneDiversity(), calcKurtosis(), calcNeSexRatio(), calcNeVariance(), calcRetention()

Examples

calcSkewness(c(1, 2, 3, 4, 100)) # 2.232396, a long right tail
calcSkewness(c(1, 2, 3, 4, 5)) # 0, symmetric

Compare two colony snapshots metric by metric

Description

Computes per-metric deltas between two snapshots of a longitudinal colony snapshot history (issue #167). The two snapshots must belong to the same membership-rule series: a snapshot is identified by its (snapshotDate, membershipRule) pair, and trend comparisons are only meaningful like with like. The result carries one row per numeric schema column — the 18 metric columns plus the 3 composition counts (nAnimals, nMales, nFemales), whose deltas make membership churn between the two snapshots visible.

Usage

calcSnapshotDeltas(history, from, to, membershipRule = NULL)

Arguments

Details

The comparabilityFlag column surfaces provenance differences between the two snapshots rather than refusing them: it is NA_character_ when the snapshots are comparable and otherwise names each differing provenance field with both values. A guIter difference flags the gene-drop-derived metrics (fg, fgSE, neGD, and the gu aggregates); a guThresh difference flags only the gu aggregates (the threshold reaches only the genome-uniqueness computation); a packageVersion difference flags every row.

Value

A data.frame with columns metric, from, to, delta (to - from), and comparabilityFlag, one row per numeric schema column in schema order.

Examples

history <- checkSnapshotHistory(readSnapshotHistory(system.file("extdata",
  "examples", "example_snapshot_history.csv",
  package = "nprcgenekeepr"
)))
deltas <- calcSnapshotDeltas(history,
  from = "2025-01-15", to = "2025-07-15",
  membershipRule = "wholePedigree"
)

Calculate the sex ratio of a set of animals

Description

The Males are counted when the ped$sex value is "M". Females are counted when the ped$sex value is not "M". This means animals with ambiguous sex are counted with the females.

Usage

calculateSexRatio(ids, ped, additionalMales = 0L, additionalFemales = 0L)

Arguments

Value

Numeric value of the sex ratio of the animals provided, expressed as the number of non-males per male. It is Inf when there are no males (and no males are added) but at least one non-male; 0 when ids is empty, no females are added and males are added; and NA when ids is empty and nothing is added.

Examples

library(nprcgenekeepr)
data("qcBreeders")
data("pedWithGenotype")
available <- c(
  "JGPN6K", "8KM1MP", "I9TQ0T", "Q0RGP7", "VFS0XB", "CQC133",
  "2KULR3", "HOYW0S", "FHV13N", "OUM6QF", "6Z7MD9", "CFPEEU",
  "HLI95R", "RI0O7F", "7M51X5", "DR5GXB", "170ZTZ", "C1ICXL"
)
nonMales <- c(
  "JGPN6K", "8KM1MP", "I9TQ0T", "Q0RGP7", "CQC133",
  "2KULR3", "HOYW0S", "FHV13N", "OUM6QF", "6Z7MD9", "CFPEEU",
  "HLI95R", "RI0O7F", "7M51X5", "DR5GXB", "170ZTZ", "C1ICXL"
)
male <- "VFS0XB"
calculateSexRatio(ids = male, ped = pedWithGenotype)
calculateSexRatio(ids = nonMales, ped = pedWithGenotype)
calculateSexRatio(ids = available, ped = pedWithGenotype)
calculateSexRatio(
  ids = available, ped = pedWithGenotype,
  additionalMales = 1L
)
calculateSexRatio(
  ids = available, ped = pedWithGenotype,
  additionalFemales = 1L
)
calculateSexRatio(
  ids = available, ped = pedWithGenotype,
  additionalMales = 1, additionalFemales = 1L
)
calculateSexRatio(
  ids = nonMales, ped = pedWithGenotype,
  additionalMales = 1, additionalFemales = 0L
)
calculateSexRatio(
  ids = character(0), ped = pedWithGenotype,
  additionalMales = 1, additionalFemales = 0L
)

Validate an ancestry compatibility rules table

Description

Checks the structure and domain of a center-configurable ancestry compatibility rules table (issue #168). Each row is one unordered pair of standardized ancestry levels plus a severity: block rules exclude the pairing during breeding-group formation, flag rules annotate it afterward. It mirrors checkKinshipOverrides: it stop()s on structural or domain errors and returns the coerced table when the input is acceptable. An empty table (zero rules) is valid.

Usage

checkAncestryRules(rules)

Arguments

Details

Ancestry levels must come from convertAncestry's standardized vocabulary: CHINESE, INDIAN, HYBRID, JAPANESE, OTHER, UNKNOWN. Levels are coerced to uppercase and severity to lowercase before validation, so a hand-edited file's casing never matters. A rule may pair a level with itself (e.g. HYBRID with HYBRID); duplicated unordered pairs are a data error the user must resolve. Because convertAncestry maps a blank ancestry to UNKNOWN but any unrecognized text – including a literal re-standardized "UNKNOWN" string – to OTHER, a table that names one of UNKNOWN/OTHER without the other draws a warning here: a center wanting conservative treatment of animals without usable ancestry information almost always wants both.

Value

The validated rules data.frame with ancestry1 and ancestry2 coerced to uppercase character and severity to lowercase character. Leading and trailing white space is trimmed from these three columns.

Examples

rules <- data.frame(
  ancestry1 = c("INDIAN", "INDIAN"),
  ancestry2 = c("CHINESE", "HYBRID"),
  severity = c("block", "flag"), stringsAsFactors = FALSE
)
checkAncestryRules(rules)

Check a changed-columns list for non-empty fields

Description

Check a changed-columns list for non-empty fields

Usage

checkChangedColsLst(changedCols)

Arguments

Value

Returns TRUE if any changed-columns field is non-empty, otherwise FALSE.

Examples

library(nprcgenekeepr)
library(lubridate)
pedOne <- data.frame(
  ego_id = c(
    "s1", "d1", "s2", "d2", "o1", "o2", "o3",
    "o4"
  ),
  `si re` = c(NA, NA, NA, NA, "s1", "s1", "s2", "s2"),
  dam_id = c(NA, NA, NA, NA, "d1", "d2", "d2", "d2"),
  sex = c("F", "M", "M", "F", "F", "F", "F", "M"),
  birth_date = mdy(
    paste0(
      sample(1:12, 8, replace = TRUE), "-",
      sample(1:28, 8, replace = TRUE), "-",
      sample(seq(0, 15, by = 3), 8, replace = TRUE) +
        2000
    )
  ),
  stringsAsFactors = FALSE, check.names = FALSE
)

errorLst <- qcStudbook(pedOne, reportErrors = TRUE, reportChanges = TRUE)
checkChangedColsLst(errorLst$changedCols)

Collect every cross-center identity-mapping problem, without stopping

Description

The "show every problem at once" companion to resolveCrossCenterIds (issue #149 Slice 1), sharing its five validation checks – id existence, mapping uniqueness, undeclared id collisions, a pedB animal that reuses an id the mapping gives a pedA animal, and conflicting recorded parents – via the same internal helpers (D2, docs/planning/issue149-cross-center-identity-mapping-workflow-plan.md section 3). resolveCrossCenterIds() stop()s on the first problem it finds; checkCrossCenterMapping() never stop()s on a domain problem – every one found becomes a row in the returned data.frame instead, so a curator can see and fix every issue at once rather than one at a time. A structural problem (a required column missing from any of the three inputs) still stop()s immediately, matching every other checkXxx() function in this package (checkKinshipOverrides, checkTwinRelations).

Usage

checkCrossCenterMapping(pedA, pedB, mapping)

Arguments

Details

Existence and uniqueness problems (tier A) are checked first; if either is present, only those are returned and the collision, reused-id and conflict checks (tier B) are skipped entirely, since a mapped id that does not resolve to a real pedigree row makes those checks meaningless. Tier B – and all three of its checks, across every mapped pair – runs only once tier A is clean.

Value

A data.frame of every domain problem found, with columns type ("existence", "uniqueness", "collision", "mappedIdClash", or "conflict"), ids (the offending id(s), as a single comma-separated string), and message (a human-readable description). Zero rows means none of these five kinds of problem was found. A "mappedIdClash" row names an id of a pedB animal with no mapping row that the mapping already uses for a pedA animal; a merge would hold two rows with that id. resolveCrossCenterIds can still stop on conflicting values in other columns shared by both pedigrees (e.g. sex), which this function does not check.

See Also

resolveCrossCenterIds

Examples

library(nprcgenekeepr)
pedA <- data.frame(
  id = c("P1", "P2", "T1"), sire = c(NA, NA, "P1"), dam = c(NA, NA, "P2"),
  stringsAsFactors = FALSE
)
pedB <- data.frame(
  id = c("X9", "O1"), sire = c(NA, "X9"), dam = c(NA, NA),
  stringsAsFactors = FALSE
)
mapping <- data.frame(idA = "T1", idB = "X9", stringsAsFactors = FALSE)
checkCrossCenterMapping(pedA, pedB, mapping) # zero rows: clean

Check an error list for non-empty fields

Description

Check an error list for non-empty fields

Usage

checkErrorLst(errorLst)

Arguments

Value

Returns FALSE if all fields are empty or the list is NULL otherwise TRUE. The changedCols field is not examined; use checkChangedColsLst for it.

Examples

errorLst <- qcStudbook(nprcgenekeepr::pedFemaleSireMaleDam,
  reportErrors = TRUE
)
checkErrorLst(errorLst)

Check genotype file

Description

Checks to ensure the content and structure are appropriate for a genotype file. These checks are simply based on expected columns and legal domains. The function stops (an error, not a warning) when the dataframe has fewer than three columns, when the first column name does not contain "id" (any case), when any column is named first or second (any case), or when an allele in columns 2 or 3 that reads as an integer is above 10000 (it would collide with the integer codes addGenotype assigns).

Usage

checkGenotypeFile(genotype)

Arguments

Value

The genotype dataframe, checked for the column count, the first column's name and the allele range described above; no column types are checked. The returned genotype file has the first column name forced to "id".

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::qcPed
ped <- ped[order(ped$id), ]
genotype <- data.frame(
  id = ped$id[50 + 1:20],
  first_name = paste0("first_name", 1:20),
  second_name = paste0("second_name", 1:20),
  stringsAsFactors = FALSE
)

## checkGenotypeFile disallows dataframe with < 3 columns
tryCatch(
  {
    checkGenotypeFile(genotype[, c("id", "first_name")])
  },
  warning = function(w) {
    cat("Warning produced")
  },
  error = function(e) {
    cat("Error produced")
  }
)

Validate a kinship overrides table

Description

Checks the structure and domain of an outside-information kinship override table. The table supplies pairwise kinship coefficients (id1, id2, kinship) that applyKinshipOverrides writes into a computed kinship matrix, replacing the pedigree-derived value for those pairs. It mirrors checkGenotypeFile: it stop()s on structural or domain errors and returns the (id-coerced) table when the input is acceptable.

Usage

checkKinshipOverrides(overrides)

Arguments

Details

kinship is the kinship coefficient f (the probability that an allele drawn at random from each of the two animals is identical by descent), not the coefficient of relatedness r (= 2f for non-inbred animals). Supplying r – e.g. 0.25 for half-sibs whose true f is 0.125 – silently corrupts the matrix, so an off-diagonal value above 0.5 (the maximum for a non-inbred pair) draws a warning here. It also stop()s on a missing (NA) or negative kinship, on a row whose id1 equals its id2, and on a duplicated unordered pair. The exact positive-semi-definiteness bound is enforced by applyKinshipOverrides once the matrix diagonal is known.

Value

The validated overrides data.frame with id1 and id2 coerced to character.

Examples

overrides <- data.frame(
  id1 = c("A1", "A3"), id2 = c("A2", "A4"),
  kinship = c(0.25, 0.125), stringsAsFactors = FALSE
)
checkKinshipOverrides(overrides)

Check a long-format multi-locus marker genotype file, multiallelic-tolerant

Description

Validates the structure of a long-format marker genotype table (one row per id x locus), the same schema checkMarkerGenotypeFile checks – but, unlike that function, does not require every locus to be biallelic. This is a new, sibling validator for the linkage-aware and haplotype-block metrics family (issue #153): real colony marker panels (e.g. microsatellite/STR panels) are routinely multiallelic, a data shape the KING-robust kinship estimator checked by checkMarkerGenotypeFile cannot represent, but which buildMarkerGenotypeMatrix pivots without error. checkMarkerGenotypeFile itself, and everything downstream of it (markerKinship), is untouched by this function.

Usage

checkLinkageMarkerGenotypeFile(genotype)

Arguments

Details

All of checkMarkerGenotypeFile's structural checks are retained – exactly four columns, id as the first column, no duplicate id x locus rows – except the per-locus more-than-two-distinct-alleles rejection, which is deliberately omitted.

Value

The genotype dataframe, checked to ensure the column count, first-column identity, and row uniqueness are all valid. The returned dataframe has its column names forced to c("id", "locus", "allele1", "allele2").

See Also

checkMarkerGenotypeFile, buildMarkerGenotypeMatrix

Examples

library(nprcgenekeepr)
markerGenotype <- data.frame(
  id = c("W", "X", "Y", "Z"),
  locus = c("L1", "L1", "L1", "L1"),
  allele1 = c("A", "A", "A", "A"),
  allele2 = c("B", "C", "A", "D"),
  stringsAsFactors = FALSE
)
checkLinkageMarkerGenotypeFile(markerGenotype)

Check a locus-metadata sidecar table and classify per-locus coverage

Description

Validates the structure of a locus-metadata sidecar table (locus, chrom, pos, and optionally cM) – the schema introduced by issue #152's own design decision and reused verbatim by issue #153 – and classifies each locus into one of three coverage tiers, following a PLINK-style three-state coverage model: "full" (both chrom and pos present; cM is optional even within "full"), "partial" (exactly one of chrom/pos present), or "none" (neither present). A value counts as present when it is not NA; an empty or all-space chrom is treated as missing and is returned as NA.

Usage

checkLocusMetadata(locusMetadata)

Arguments

Details

A locus-metadata table has one row per locus (not per individual x locus, unlike checkMarkerGenotypeFile's genotype table). Real curated marker panels typically supply little to no locus-order metadata – this function reports coverage explicitly per locus rather than requiring complete metadata before any downstream use.

Value

The locus-metadata dataframe, checked to ensure the column count, first-column identity, and row uniqueness are all valid, with a new coverage column appended ("full"/"partial"/ "none"). The returned dataframe has locus and chrom coerced to character, and its column names forced to locus, chrom, pos (and cM when there are four columns) whatever the input names were.

References

Purcell, S., Neale, B., Todd-Brown, K., Thomas, L., Ferreira, M. A. R., Bender, D., Maller, J., Sklar, P., de Bakker, P. I. W., Daly, M. J., & Sham, P. C. (2007). PLINK: a tool set for whole-genome association and population-based linkage analyses. American Journal of Human Genetics, 81(3), 559-575. doi:10.1086/519795

See Also

checkMarkerGenotypeFile

Examples

library(nprcgenekeepr)
locusMetadata <- data.frame(
  locus = c("L1", "L2", "L3"),
  chrom = c("1", "1", NA),
  pos = c(1000000, NA, NA),
  stringsAsFactors = FALSE
)
checkLocusMetadata(locusMetadata)

Check a long-format multi-locus marker genotype file

Description

Validates the structure and legal domain of a long-format marker genotype table (one row per id x locus), the input format for the marker-based (KING-robust) kinship estimator (markerKinship). This is a new, sibling schema to the single-locus first_name/second_name genotype format checked by checkGenotypeFile – that function, and everything downstream of it (addGenotype, geneDrop), is untouched by this one.

Usage

checkMarkerGenotypeFile(genotype)

Arguments

Details

The KING-robust kinship estimator (Manichaikul et al. 2010) is defined for biallelic markers only – every genotype is classified as homozygous-reference, heterozygous, or homozygous-alternate, with no representation for a third allele at a locus. A locus with more than two distinct alleles observed anywhere in the input is therefore rejected outright, rather than silently producing an uninterpretable kinship estimate.

Value

The genotype dataframe, checked to ensure the column count, first-column identity, per-locus allele count, and row uniqueness are all valid. The returned dataframe has its column names forced to c("id", "locus", "allele1", "allele2").

References

Manichaikul, A., Mychaleckyj, J. C., Rich, S. S., Daly, K., Sale, M., & Chen, W.-M. (2010). Robust relationship inference in genome-wide association studies. Bioinformatics, 26(22), 2867-2873. doi:10.1093/bioinformatics/btq559

See Also

buildMarkerGenotypeMatrix, markerKinship

Examples

library(nprcgenekeepr)
markerGenotype <- data.frame(
  id = c("A", "A", "B", "B"),
  locus = c("L1", "L2", "L1", "L2"),
  allele1 = c("A", "A", "A", "A"),
  allele2 = c("A", "B", "B", "B"),
  stringsAsFactors = FALSE
)
checkMarkerGenotypeFile(markerGenotype)

Check a wide-format MHC haplotype designation file

Description

Validates the structure of a wide per-animal MHC haplotype designation table: exactly three columns – id plus the animal's two named haplotype designations, one row per animal. This is the explicit input designation for MHC haplotype reporting (issue #148): a curator designates data as MHC by supplying it through this format, and no MHC semantics are ever inferred from locus or column names (the format has no locus names). A new, sibling input family: the long-format marker validators (checkMarkerGenotypeFile, checkLinkageMarkerGenotypeFile, checkSequenceGenotypeFile) and the single-locus checkGenotypeFile path are untouched by this one.

Usage

checkMhcHaplotypeFile(genotype)

Arguments

Details

Column names are not prescribed: the first column must be id-like (case-insensitive match on "id") and is forced to id; the second and third are forced to haplotype1 and haplotype2, so a colony file with, e.g., first_name/second_name headers (the bundled rhesusGenotypes shape) loads unchanged. NA/empty cells pass validation – a missing call is the statistics layer's concern, not a structural error. A trailing ? on a designation (an uncertain, provisional call) is likewise not validation's business; see the issue #148 design plan's D3 parse rule. Haplotype designations are otherwise opaque labels: never parsed, split, or matched against MHC region names.

Value

The genotype dataframe, checked to ensure the column count, first-column identity, and row uniqueness are all valid. The returned dataframe has its column names forced to c("id", "haplotype1", "haplotype2").

See Also

rhesusGenotypes, checkMarkerGenotypeFile

Examples

library(nprcgenekeepr)
checked <- checkMhcHaplotypeFile(rhesusGenotypes)
head(checked)

Check parent ages against a minimum age

Description

Ensure parents are sufficiently older than offspring

Usage

checkParentAge(
  sb,
  minSireAge = NULL,
  minDamAge = NULL,
  minParentAge = lifecycle::deprecated(),
  reportErrors = FALSE
)

Arguments

Value

A dataframe containing rows for each animal where one or more parent was younger than the minimum breeding age (minSireAge or minDamAge, or the species floor when they are NULL) at the animal's birth. It contains all of the columns in the original sb dataframe, with exit converted to character and the rows reordered, plus the following added columns:

1. sireBirth – sire's birth date

2. sireAge – age of sire in years on the date indicated by birth.

3. damBirth – dam's birth date

4. damAge – age of dam in years on the date indicated by birth.

Examples

library(nprcgenekeepr)
qcPed <- nprcgenekeepr::qcPed
checkParentAge(qcPed, minSireAge = 2L, minDamAge = 2L)
checkParentAge(qcPed, minSireAge = 3L, minDamAge = 3L)
checkParentAge(qcPed, minSireAge = 5L, minDamAge = 5L)
checkParentAge(qcPed, minSireAge = 6L, minDamAge = 6L)
head(checkParentAge(qcPed, minSireAge = 10L, minDamAge = 10L))

Check column names for required columns

Description

Check column names for required columns

Usage

checkRequiredCols(cols, reportErrors)

Arguments

Details

When reportErrors = TRUE, NA entries in cols are treated as ordinary non-matching column names when building the list of missing required columns, rather than causing an error. (Earlier versions could error with "missing value where TRUE/FALSE needed" on such out-of-contract input.)

Value

NULL is returned if all required columns are present. See description of reportErrors for what happens when required columns are missing.

Examples

library(nprcgenekeepr)
requiredCols <- getRequiredCols()
cols <- strsplit(
  paste0(
    "id,sire,siretype,dam,damtype,sex,numberofparentsknown,birth,",
    "arrivalatcenter,death,departure,status,ancestry,fromcenter?,",
    "origin"
  ),
  ","
)[[1L]]
checkRequiredCols(cols, reportErrors = TRUE) # NULL: all required present
# A missing required column is returned by name
checkRequiredCols(setdiff(cols, "birth"), reportErrors = TRUE)

Check a long-format sequence-derived marker genotype file

Description

Validates the structure of a long-format marker genotype table (one row per id x locus), the same schema checkMarkerGenotypeFile checks – but sized and hardened for sequence-derived panels (issue #152): a soft, overridable warning above a sparse/GBS-scale panel-size ceiling, and an explicit rejection of a literal "." allele value (VCF's missing-genotype placeholder), rather than silently counting it as a real allele. Optionally validates the accompanying locus-metadata sidecar's own structure by reusing checkLocusMetadata, rather than reinventing that check; the sidecar is not cross-checked against the loci of the genotype table.

Usage

checkSequenceGenotypeFile(genotype, locusMetadata = NULL, maxLoci = 50000L)

Arguments

Details

All of checkMarkerGenotypeFile's structural checks are retained – exactly four columns, id as the first column, no duplicate id x locus rows, and the same biallelic-only rejection the KING-robust kinship estimator (Manichaikul et al. 2010) requires. Two rules are new: a literal "." allele value is rejected before the biallelic count is even checked, so a curator sees the correct, actionable error rather than a misleading "more than two alleles" report (a genotype-preprocessing pipeline emitting VCF-style missingness that was never converted to NA is a real, anticipated failure mode – see Danecek et al. 2011 for the VCF missing-genotype convention this guards against); and a locus count above maxLoci produces a warning(), not a stop() – the "right" ceiling for this package's own vectorized implementations is not yet empirically known, so a hard stop would risk blocking legitimate data.

Value

The genotype dataframe, checked to ensure the column count, first-column identity, per-locus allele count, absence of a literal "." placeholder, and row uniqueness are all valid. The returned dataframe has its column names forced to c("id", "locus", "allele1", "allele2").

References

Manichaikul, A., Mychaleckyj, J. C., Rich, S. S., Daly, K., Sale, M., & Chen, W.-M. (2010). Robust relationship inference in genome-wide association studies. Bioinformatics, 26(22), 2867-2873. doi:10.1093/bioinformatics/btq559

Danecek, P., et al. (2011). The variant call format and VCFtools. Bioinformatics, 27(15), 2156-2158. doi:10.1093/bioinformatics/btr330

See Also

checkMarkerGenotypeFile, checkLinkageMarkerGenotypeFile, checkLocusMetadata, buildMarkerGenotypeMatrix

Examples

library(nprcgenekeepr)
markerGenotype <- data.frame(
  id = c("A", "A", "B", "B"),
  locus = c("L1", "L2", "L1", "L2"),
  allele1 = c("A", "A", "A", "A"),
  allele2 = c("A", "B", "B", "B"),
  stringsAsFactors = FALSE
)
checkSequenceGenotypeFile(markerGenotype)

Validate a colony snapshot-history table

Description

Checks the structure and domain of a longitudinal colony snapshot history (issue #167): one row per recorded snapshot, in the 27-column version-1 schema. It mirrors checkKinshipOverrides: it stop()s with a specific message on structural or domain errors and returns the coerced history when the input is acceptable.

Usage

checkSnapshotHistory(history)

Arguments

Details

The schema has three groups of nine columns:

Provenance / comparability

schemaVersion, snapshotDate, packageVersion, membershipRule, guIter, guThresh, nAnimals, nMales, nFemales. These let successive snapshots be compared like with like: snapshots generated under different membership rules, guIter settings, or package versions are comparable only with care, and trend displays flag such mixed-provenance series rather than hiding them.

Colony scalars

fe, fg, fgSE, neGD, neSexRatio, neVariance, nMaleFounders, nFemaleFounders, nFounders — verbatim from reportGV.

Colony aggregates

meanIndivMeanKin, medianIndivMeanKin, skewnessIndivMeanKin, kurtosisIndivMeanKin, meanGu, medianGu, meanGuSE, skewnessGu, kurtosisGu — the Summary Statistics definitions applied to the per-animal indivMeanKin and gu report columns.

Violations rejected: missing columns, non-numeric metric or count fields, an unrecognized schemaVersion, a duplicated (snapshotDate, membershipRule) pair, and malformed (non ISO-8601) dates. The membershipRule field is an open string — no enumeration is enforced, so new rule names are additive. Extra columns are ignored, matching the sibling validators.

Value

The validated history with snapshotDate coerced to Date, packageVersion and membershipRule coerced to character, and schemaVersion and the count columns coerced to integer.

Examples

history <- readSnapshotHistory(system.file("extdata", "examples",
  "example_snapshot_history.csv",
  package = "nprcgenekeepr"
))
history <- checkSnapshotHistory(history)

Validate a twin/zygosity relations table

Description

Checks the structure and domain of a twin/zygosity sidecar table. The table supplies pairwise twin declarations (id1, id2, code) that record which individuals in a pedigree are twins and with what twin zygosity certainty – a fact this package's per-individual pedigree data frame cannot represent directly. It mirrors checkKinshipOverrides: it stop()s on structural or domain errors and returns the (id-coerced) table when the input is acceptable.

Usage

checkTwinRelations(ped, twinRelations)

Arguments

Details

code adopts kinship2's own literal twin-code labels – "MZ twin", "DZ twin", "UZ twin" – rather than a bare "zygosity" identifier, which would collide with this package's unrelated marker-genetics heterozygosity vocabulary (see markerObservedHeterozygosity). kinship2's own fourth, non-twin "spouse" code is out of scope here.

Validation reproduces kinship2's own relation acceptance rules, confirmed empirically against the installed kinship2 namespace: both ids must exist in ped and differ (all codes); an "MZ twin"/"DZ twin" pair must already share both sire and dam in ped; an "MZ twin" pair must additionally have matching sex; "UZ twin" has no such precondition.

Value

The validated twinRelations data.frame with id1 and id2 coerced to character.

Examples

ped <- data.frame(
  id = c("F1", "F2", "S1", "S2"),
  sire = c(NA, NA, "F1", "F1"),
  dam = c(NA, NA, "F2", "F2"),
  sex = c("M", "F", "F", "F"),
  stringsAsFactors = FALSE
)
twinRelations <- data.frame(
  id1 = "S1", id2 = "S2", code = "MZ twin", stringsAsFactors = FALSE
)
checkTwinRelations(ped, twinRelations)

Combine two allele vectors by Mendelian sampling

Description

Combine two allele vectors by Mendelian sampling

Usage

chooseAlleles(a1, a2)

Arguments

Value

An integer vector with the result of sampling from a1 and a2 according to Mendelian inheritance.

Examples

chooseAlleles(0L:4L, 5L:9L)

Choose the earlier or later of two dates

Description

Part of Pedigree Curation

Usage

chooseDate(d1, d2, earlier = TRUE)

Arguments

Details

Given two dates, one is selected to be returned based on whether it occurred earlier or later than the other. NAs are ignored if possible.

Value

A single Date value, the chosen date, or NA where neither is provided. Vectors longer than one are not supported; use pmin or pmax, or mapply, for vectors.

Examples

library(nprcgenekeepr)
someDates <- lubridate::mdy(paste0(
  sample(1:12, 2, replace = TRUE), "-",
  sample(1:28, 2, replace = TRUE), "-",
  sample(seq(0, 15, by = 3), 2,
    replace = TRUE
  ) + 2000
))
someDates
chooseDate(someDates[1], someDates[2], earlier = TRUE)
chooseDate(someDates[1], someDates[2], earlier = FALSE)

Compute genomic Runs of Homozygosity (ROH) and F_ROH

Description

Computes per-individual genomic Runs of Homozygosity (ROH) segments and the genomic inbreeding coefficient F_ROH from a sequence-scale marker genotype matrix (issue #152 Slice 3, design decision D6) – a sequence-verified inbreeding estimate independent of (often incomplete) pedigree records, complementing rather than duplicating this package's existing pedigree-based kinship/founder metrics.

Usage

computeGenomicROH(genotypeMatrix, locusMetadata, minSnp = 50L, minBp = 1e+06)

Arguments

Details

Within each chromosome, loci are ordered by pos. A "run" is a maximal, gapless stretch of homozygous, non-missing genotyped loci – both a heterozygous call and a missing (NA) call end the current run. A run qualifies as an ROH segment only if it has at least minSnp loci AND spans at least minBp base pairs (the field-standard dual threshold, matching PLINK's --homozyg-snp/ --homozyg-kb, Purcell et al. 2007) – either condition alone is not sufficient. totalRohLength sums the qualifying segments' spans across all chromosomes; fRoh divides that sum by genomeLength, a single value shared across every individual: the sum, per chromosome, of (max(pos) - min(pos)) among the full-coverage loci in locusMetadata that are also columns of genotypeMatrix (Ceballos et al. 2018's L_{autosome} convention). The denominator is fixed across individuals within one call, which avoids conflating an individual's own missingness with inbreeding, but it changes with the matrix's locus set: full-coverage loci of locusMetadata that are not columns of genotypeMatrix are left out of that length, with one warning naming them (at most 10 are named, then "and N more"), so fRoh is comparable across a cohort only when the same loci are used. A locus without a position never enters the length, so its absence is not reported.

Only loci with full locusMetadata coverage (both chrom and pos present, per checkLocusMetadata's own three-tier classification) can be placed in the ordered walk; a locus lacking full coverage, or entirely absent from locusMetadata, is excluded from both the walk and the genomeLength denominator, with a warning naming it – it is never treated as a run-breaking gap. When every chromosome has at most one full-coverage locus, genomeLength is 0 and fRoh is an undefined 0/0 ratio: NA with a warning, not NaN silently, mirroring markerFst's own undefined-ratio precedent.

Value

A per-individual dataframe: id, nSegments (count of qualifying ROH segments), totalRohLength (their summed bp span), and fRoh (the genomic inbreeding coefficient, or NA if genomeLength is 0).

References

Ceballos, F. C., Joshi, P. K., Clark, D. W., Ramsay, M., & Wilson, J. F. (2018). Runs of homozygosity: windows into population history and trait architecture. Nature Reviews Genetics, 19(4), 220-234. doi:10.1038/nrg.2017.109

Purcell, S., et al. (2007). PLINK: a tool set for whole-genome association and population-based linkage analyses. American Journal of Human Genetics, 81(3), 559-575. doi:10.1086/519795

See Also

buildMarkerGenotypeMatrix, checkLocusMetadata, checkSequenceGenotypeFile

Examples

library(nprcgenekeepr)
locusMetadata <- data.frame(
  locus = c("L1", "L2", "L3", "L4"),
  chrom = c("1", "1", "1", "1"),
  pos = c(0, 400000, 900000, 1400000),
  stringsAsFactors = FALSE
)
genotypeMatrix <- matrix(
  c("A/A", "A/A", "A/B", "A/A"),
  nrow = 1L, dimnames = list("Animal1", locusMetadata$locus)
)
computeGenomicROH(genotypeMatrix, locusMetadata, minSnp = 2L, minBp = 300000)

Convert ancestry information to a standard code

Description

Part of Pedigree Curation

Usage

convertAncestry(ancestry)

Arguments

Value

A factor vector of standardized designators specifying if an animal is a Chinese rhesus, Indian rhesus, Chinese-Indian hybrid rhesus, or Japanese macaque. Levels: CHINESE, INDIAN, HYBRID, JAPANESE, OTHER, UNKNOWN.

Examples

original <- c("china", "india", "hybridized", NA, "human", "gorilla")
convertAncestry(original)

Convert character date columns to Date type

Description

Part of Pedigree Curation

Usage

convertDate(ped, timeOrigin = as.Date("1970-01-01"), reportErrors = FALSE)

Arguments

Value

A dataframe with an updated table with date columns converted from character data type to Date data type. A date must be in the form YYYY-MM-DD (month and day may have one digit), or YYYYMMDD when no date in the column has a separator. A year before 1000 is invalid. A value that does not conform is an error (see reportErrors), not set to NA. NA values and blank strings are left as NA. A date column must be character, factor, logical, integer or Date; any other class stops with an error. Records marked "added" are not checked and are returned after the other records. With reportErrors = TRUE see that argument instead.

Examples

library(lubridate)
set_seed(10)
someBirthDates <- paste0(
  sample(seq(0, 15, by = 3), 10,
    replace = TRUE
  ) + 2000, "-",
  sample(1:12, 10, replace = TRUE), "-",
  sample(1:28, 10, replace = TRUE)
)
someBadBirthDates <- paste0(
  sample(1:12, 10, replace = TRUE), "-",
  sample(1:28, 10, replace = TRUE), "-",
  sample(seq(0, 15, by = 3), 10,
    replace = TRUE
  ) + 2000
)
someDeathDates <- sample(someBirthDates, length(someBirthDates),
  replace = FALSE
)
someDepartureDates <- sample(someBirthDates, length(someBirthDates),
  replace = FALSE
)
ped1 <- data.frame(
  birth = someBadBirthDates, death = someDeathDates,
  departure = someDepartureDates
)
someDates <- ymd(someBirthDates)
ped2 <- data.frame(
  birth = someDates, death = someDeathDates,
  departure = someDepartureDates
)
ped3 <- data.frame(
  birth = someBirthDates, death = someDeathDates,
  departure = someDepartureDates
)
someNADeathDates <- someDeathDates
someNADeathDates[c(1, 3, 5)] <- ""
someNABirthDates <- someDates
someNABirthDates[c(2, 4, 6)] <- NA
ped4 <- data.frame(
  birth = someNABirthDates, death = someNADeathDates,
  departure = someDepartureDates
)

## convertDate identifies bad dates
result <- tryCatch(
  {
    convertDate(ped1)
  },
  warning = function(w) {
    print("Warning in date")
  },
  error = function(e) {
    print("Error in date")
  }
)

## convertDate with error flag returns error list and not an error
convertDate(ped1, reportErrors = TRUE)

## convertDate recognizes good dates
all(is.Date(convertDate(ped2)$birth))
all(is.Date(convertDate(ped3)$birth))

## convertDate handles NA and empty character string values correctly
convertDate(ped4)

Convert from-center information to a logical value

Description

Part of Pedigree Curation

Usage

convertFromCenter(fromCenter)

Arguments

Value

A logical vector specifying TRUE if an animal is from the center otherwise FALSE. An NA input stays NA. A value is read only when the whole text, ignoring case and any spaces around it, is y, yes, t or true (TRUE), or n, no, f or false (FALSE). Any other value, such as "unknown", "maybe", a number such as 1L or an empty string, stops with an error naming the offending rows.

Examples

original <- c(
  "y", "yes", "Y", "Yes", "YES", "n", "N", "No", "NO", "no",
  "t", "T", "True", "true", "TRUE", "f", "F", "false", "False",
  "FALSE"
)
convertFromCenter(original)

Convert pairwise kinship values to relationship categories

Description

Part of Relations

Usage

convertRelationships(kmat, ped, ids = NULL, updateProgress = NULL)

Arguments

Details

Ids given as numbers or as a factor, in the pedigree's id, sire and dam or in ids, are taken as their text.

Value

A dataframe with columns id1, id2, kinship, relation. It is a long-form table of pairwise kinships, with relationship categories included for each pair. IDs that are not in kmat are ignored. One ID gives that animal's own Self row, and no ID in kmat (or an empty ids) gives a table with no rows.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::smallPed
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen, sparse = FALSE)
ids <- c("A", "B", "D", "E", "F", "G", "I", "J", "L", "M", "O", "P")
relIds <- convertRelationships(kmat, ped, ids)
rel <- convertRelationships(kmat, ped, updateProgress = function() {})
head(rel)
ped <- nprcgenekeepr::qcPed
bkmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen,
  sparse = FALSE
)
relBIds <- convertRelationships(bkmat, ped, c("4LFS70", "DD1U77"))
relBIds

Convert a sex indicator to a standardized code

Description

Part of Pedigree Curation

Usage

convertSexCodes(sex, ignoreHerm = TRUE)

Arguments

Details

Standard sex codes are

• F – replacing "FEMALE" or "2"

• M – replacing "MALE" or "1"

• H – replacing "HERMAPHRODITE" or "4", if ignoreHerm == FALSE

• U – replacing "HERMAPHRODITE" or "4", if ignoreHerm == TRUE

• U – replacing "UNKNOWN" or "3"

• U – replacing a missing, blank or unrecognized value

Case and any spaces around a code are ignored, so " male " and "M " both become M.

Value

A single factor with levels F, M, H and U holding the standardized sex codes after transformation from non-standard codes. Level H is used only when ignoreHerm = FALSE.

Examples

library(nprcgenekeepr)
original <- c(
  "m", "male", "1", "MALE", "M", "F", "f", "female",
  "FemAle", "U", "Unknown", "H", "hermaphrodite",
  "U", "Unknown", "3", "4"
)
sexCodes <- convertSexCodes(original)
sexCodes

Convert status indicators to a standardized code

Description

Part of Pedigree Curation

Usage

convertStatusCodes(status)

Arguments

Details

Case is ignored, but spaces are not trimmed. The recognized codes are ALIVE, A, 1 for alive; DECEASED, DEAD, DIED, D, 2 for deceased; SHIPPED, SHIPED, SOLD, SALE, S, 3 for shipped; and UNKNOWN, U, 4 or NA for unknown.

Value

A factor vector of the standardized status codes with levels: ALIVE, DECEASED, SHIPPED, and UNKNOWN. A value that is not recognized becomes NA, not UNKNOWN.

Examples

library(nprcgenekeepr)
original <- c(
  "A", "alive", "Alive", "1", "S", "Sale", "sold", "shipped",
  "D", "d", "dead", "died", "deceased", "2",
  "shiped", "3", "U", "4", "unknown", NA,
  "Unknown", "U", "Unknown", "4"
)
## A value that is not recognized becomes NA
convertStatusCodes("hermaphrodite")
convertStatusCodes(original)

Correct the sex of animals listed as a sire or dam

Description

Part of Pedigree Curation

Usage

correctParentSex(id, sire, dam, sex, recordStatus, reportErrors = FALSE)

Arguments

Details

Only true female-sires ("F") and male-dams ("M") are corrected (to "M" and "F" respectively). Parents recorded as hermaphrodite ("H") or unknown ("U") sex are left unchanged, consistent with reportErrors = TRUE mode, which does not flag them.

When reportErrors = TRUE, only records whose recordStatus is exactly "added" are left out of the report. A missing (NA), blank or unrecognized status is treated as an original animal, and a NULL recordStatus means no added records are known, so every animal is checked.

Value

When reportErrors = FALSE, a factor (or character vector) of corrected sex codes with levels "M", "F", "H", and "U" for the ids provided. When reportErrors = TRUE, a named list of error vectors with elements sireAndDam, femaleSires, and maleDams (each NULL when no such errors are found).

Examples

library(nprcgenekeepr)
pedOne <- data.frame(
  id = c("s1", "d1", "s2", "d2", "o1", "o2", "o3", "o4"),
  sire = c(NA, "s0", "s4", NA, "s1", "s1", "s2", "s2"),
  dam = c(NA, "d0", "d4", NA, "d1", "d2", "d2", "d2"),
  sex = c("F", "F", "M", "F", "F", "F", "F", "M"),
  recordStatus = rep("original", 8),
  stringsAsFactors = FALSE
)
pedTwo <- data.frame(
  id = c("s1", "d1", "s2", "d2", "o1", "o2", "o3", "o4"),
  sire = c(NA, "s0", "s4", NA, "s1", "s1", "s2", "s2"),
  dam = c("d0", "d0", "d4", NA, "d1", "d2", "d2", "d2"),
  sex = c("M", "M", "M", "F", "F", "F", "F", "M"),
  recordStatus = rep("original", 8),
  stringsAsFactors = FALSE
)
pedOneCorrected <- pedOne
pedOneCorrected$sex <- correctParentSex(
  pedOne$id, pedOne$sire, pedOne$dam,
  pedOne$sex, pedOne$recordStatus
)
pedOne[pedOne$sex != pedOneCorrected$sex, ]
pedOneCorrected[pedOne$sex != pedOneCorrected$sex, ]

pedTwoCorrected <- pedTwo
pedTwoCorrected$sex <- correctParentSex(
  pedTwo$id, pedTwo$sire, pedTwo$dam,
  pedTwo$sex, pedTwo$recordStatus
)
pedTwo[pedTwo$sex != pedTwoCorrected$sex, ]
pedTwoCorrected[pedTwo$sex != pedTwoCorrected$sex, ]

Count first-order relatives

Description

Part of Relations

Usage

countFirstOrder(ped, ids = NULL)

Arguments

Details

Tallies the number of first-order relatives for each member of the provided pedigree. If 'ids' is provided, the analysis is restricted to only the specified subset.

Value

A dataframe with column id, parents, offspring, siblings, and total. A table of first-order relationship counts, broken down to indicate the number of parents, offspring, and siblings that are part of the subset under consideration. Siblings are animals with the same sire and the same dam, so half-siblings are not counted and an animal with an unknown sire or dam has 0 siblings.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
ids <- c("B", "D", "E", "F", "G")
countIds <- countFirstOrder(ped, ids)
countIds
count <- countFirstOrder(ped, NULL)
count

Count kinship-value occurrences across simulated pedigrees

Description

Count kinship-value occurrences across simulated pedigrees

Usage

countKinshipValues(kinshipValues, accummulatedKValueCounts = NULL)

Arguments

Value

A list of three lists named kIds (kinship IDs), kValues (kinship values), and kCounts (kinship counts).

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::smallPed
simParent_1 <- list(
  id = "A",
  sires = c("s1_1", "s1_2", "s1_3"),
  dams = c("d1_1", "d1_2", "d1_3", "d1_4")
)
simParent_2 <- list(
  id = "B",
  sires = c("s1_1", "s1_2", "s1_3"),
  dams = c("d1_1", "d1_2", "d1_3", "d1_4")
)
simParent_3 <- list(
  id = "E",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
simParent_4 <- list(
  id = "J",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
simParent_5 <- list(
  id = "K",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
simParent_6 <- list(
  id = "N",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
allSimParents <- list(
  simParent_1, simParent_2, simParent_3,
  simParent_4, simParent_5, simParent_6
)

extractKValue <- function(kValue, id1, id2, simulation) {
  kValue[
    kValue$id_1 == id1 & kValue$id_2 == id2,
    paste0("sim_", simulation)
  ]
}

n <- 10
simKinships <- createSimKinships(ped, allSimParents,
  pop = ped$id, n = n
)
kValues <- kinshipMatricesToKValues(simKinships)
extractKValue(kValues, id1 = "A", id2 = "F", simulation = 1:n)
counts <- countKinshipValues(kValues)

# A second, independent set of simulations is added to the first counts
n <- 10
simKinships <- createSimKinships(ped, allSimParents, pop = ped$id, n = n)
kValues <- kinshipMatricesToKValues(simKinships)
extractKValue(kValues, id1 = "A", id2 = "F", simulation = 1:n)
accummulatedCounts <- countKinshipValues(kValues, counts)

Count the number of loops in a pedigree tree

Description

Part of Pedigree Sampling From PedigreeSampling.R 2016-01-28

Usage

countLoops(loops, ptree)

Arguments

Details

Contains functions to build pedigrees from sub-samples of genotyped individuals.

The goal of sampling is to reduce the number of inbreeding loops in the resulting pedigree, and thus, reduce the amount of time required to perform calculations with SIMWALK2 or similar programs.

Uses the loops data structure and the list of all ancestors for each individual to calculate the number of loops for each individual.

Value

A list indexed with each ID in the pedigree tree (ptree) containing the number of loops for each individual.

Examples

library(nprcgenekeepr)
examplePedigree <- nprcgenekeepr::examplePedigree
exampleTree <- createPedTree(examplePedigree)
exampleLoops <- findLoops(exampleTree)
## You can count how many animals are in loops with the following code.
length(exampleLoops[exampleLoops == TRUE])
## You can count how many loops you have with the following code.
nLoops <- countLoops(exampleLoops, exampleTree)
sum(unlist(nLoops[nLoops > 0]))
## You can list the first 10 sets of ids, sires and dams in loops with
## the following line of code:
examplePedigree[exampleLoops == TRUE, c("id", "sire", "dam")][1:10, ]

Create a colony snapshot row from a genetic value report

Description

Turns one reportGV result into a one-row data.frame in the 27-column snapshot-history schema (issue #167, schema version 1), ready for appendColonySnapshot. Every metric field is a value the nprcgenekeeprGV object already carries, or a Summary Statistics aggregate (mean/median/calcSkewness/ calcKurtosis, NA removed) of its per-animal indivMeanKin/gu/guSE report columns, stored at full precision — no estimator is recomputed or duplicated.

Usage

createColonySnapshot(
  ped,
  geneticValue,
  membershipRule,
  guIter,
  guThresh,
  snapshotDate = Sys.Date()
)

Arguments

Details

guIter and guThresh are required because the reportGV return object does not carry them, and they are comparability provenance the snapshot must record truthfully: pass exactly the values the reportGV call used (its defaults are 1000L and 1L).

The claimed membershipRule is verified against ped and the report, and a contradiction stops:

"wholePedigree"

the report covers exactly the animals in ped.

"focalPopulation"

ped carries the logical population column (see setPopulation) and the report covers exactly ped$id[ped$population]. Pass the same population-designated pedigree the reportGV call analyzed.

"reconstructedLiving"

the snapshot was rebuilt for a past date from the pedigree's birth and exit dates (see backfillColonySnapshots). It is verified exactly like "focalPopulation", but is a separate rule so a rebuilt row never mixes with a recorded one: rules are never compared with each other.

Value

A one-row data.frame in the 27-column snapshot-history schema; it passes checkSnapshotHistory unchanged.

Examples

ped <- nprcgenekeepr::qcPed
gv <- reportGV(ped, guIter = 10L)
snapshot <- createColonySnapshot(ped, gv, "wholePedigree",
  guIter = 10L, guThresh = 1L
)
history <- appendColonySnapshot(NULL, snapshot)

Create example pedigree and ID-list CSV files

Description

Creates a folder named ExamplePedigrees under the R session temporary directory (as returned by tempdir()) if it does not already exist. It then proceeds to write each example data set into a CSV file named based on the name of the data set. The data sets include pedigrees and related lists, such as focalAnimals, qcBreeders, pedWithGenotype, and qcPed.

Usage

createExampleFiles()

Value

A character vector of the full path names of the files written.

Examples

library(nprcgenekeepr)
files <- createExampleFiles()

Create a pedigree tree (PedTree)

Description

The PedTree is a list containing sire and dam information for an individual.

Usage

createPedTree(ped)

Arguments

Details

Part of Pedigree Sampling From PedigreeSampling.R 2016-01-28

Contains functions to build pedigrees from sub-samples of genotyped individuals.

The goal of sampling is to reduce the number of inbreeding loops in the resulting pedigree, and thus, reduce the amount of time required to perform calculations with SIMWALK2 or similar programs.

This function uses only id, sire, and dam columns.

Value

A list of named lists forming a pedigree tree (PedTree or ptree). Each sublist represents an ID in the pedigree and contains the sire ID and the dam ID as named elements.

Examples

library(nprcgenekeepr)
exampleTree <- createPedTree(nprcgenekeepr::examplePedigree)
exampleLoops <- findLoops(exampleTree)

Build kinship matrices from simulated pedigrees

Description

createSimKinships uses makeSimPed with the ped object and the allSimParents object to create a set of kinship matrices to be used in forming the Monte Carlo estimates for the kinship values.

Usage

createSimKinships(
  ped,
  allSimParents,
  pop = NULL,
  n = 10L,
  verbose = FALSE,
  twinRelations = NULL
)

Arguments

Value

A list of n kinship matrices, each from one simulated pedigree with possible parents drawn for animals with unknown parents.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::smallPed
simParent_1 <- list(
  id = "A",
  sires = c("s1_1", "s1_2", "s1_3"),
  dams = c("d1_1", "d1_2", "d1_3", "d1_4")
)
simParent_2 <- list(
  id = "B",
  sires = c("s2_1", "s2_2", "s2_3"),
  dams = c("d2_1", "d2_2", "d2_3", "d2_4")
)
simParent_3 <- list(
  id = "E",
  sires = c("s3_1", "s3_2", "s3_3"),
  dams = c("d3_1", "d3_2", "d3_3", "d3_4")
)
allSimParents <- list(simParent_1, simParent_2, simParent_3)
pop <- LETTERS[1:7]
simKinships <- createSimKinships(ped, allSimParents, pop, n = 10)

Create an Excel workbook with worksheets

Description

Create an Excel workbook with worksheets

Usage

create_wkbk(file, df_list, sheetnames, replace = FALSE)

Arguments

Value

TRUE if the Excel file was successfully created. FALSE, with a warning, if the file already exists and replace is FALSE. Other problems are signaled as errors rather than returned as FALSE; examples are a number of sheetnames that differs from the length of df_list, a folder for file that does not exist and an invalid worksheet name.

Examples

library(nprcgenekeepr)

make_df_list <- function(size) {
  df_list <- list(size)
  if (size <= 0) {
    return(df_list)
  }
  for (i in seq_len(size)) {
    n <- sample(2:10, 2, replace = TRUE)
    df <- data.frame(matrix(data = rnorm(n[1] * n[2]), ncol = n[1]))
    df_list[[i]] <- df
  }
  names(df_list) <- paste0("A", seq_len(size))
  df_list
}
df_list <- make_df_list(3)
sheetnames <- names(df_list)
wkbkFile <- file.path(tempdir(), "example_excel_wkbk.xlsx")
create_wkbk(
  file = wkbkFile,
  df_list = df_list,
  sheetnames = sheetnames,
  replace = FALSE
)
if (file.exists(wkbkFile)) {
  file.remove(wkbkFile)
}

Compute kinship summary statistics across simulations

Description

cumulateSimKinships returns a named list of length 4 where the first element is the mean of the simulated kinships, the second element is the standard deviation of the simulated kinships, the third element is the minimum value of the kinships, and the fourth element is the maximum value of the kinships.

Usage

cumulateSimKinships(
  ped,
  allSimParents,
  pop = NULL,
  n = 10L,
  twinRelations = NULL
)

Arguments

Value

List object containing the meanKinship, sdKinship, minKinship, and maxKinship. sdKinship is the sample standard deviation across the n simulations; it is undefined for a single simulation, so when n < 2 it is returned as NA (with a warning), as base R sd() does for a length-one vector.

Examples

ped <- nprcgenekeepr::smallPed
simParent_1 <- list(
  id = "A",
  sires = c("s1_1", "s1_2", "s1_3"),
  dams = c("d1_1", "d1_2", "d1_3", "d1_4")
)
simParent_2 <- list(
  id = "B",
  sires = c("s2_1", "s2_2", "s2_3"),
  dams = c("d2_1", "d2_2", "d2_3", "d2_4")
)
simParent_3 <- list(
  id = "E",
  sires = c("s3_1", "s3_2", "s3_3"),
  dams = c("d3_1", "d3_2", "d3_3", "d3_4")
)
allSimParents <- list(simParent_1, simParent_2, simParent_3)
pop <- LETTERS[1:7]
cumulativeKinships <- cumulateSimKinships(ped, allSimParents, pop, n = 10)

Convert a data frame to a character vector

Description

Adapted from print.data.frame

Usage

dataframe2string(object, ..., digits = NULL, addRowNames = TRUE)

Arguments

Value

A character vector of length one holding the text representation of the data.frame provided to the function, with rows separated by newline characters.

Examples

library(nprcgenekeepr)
dataframe2string(nprcgenekeepr::pedOne)

Draw the Pedigree Browser's Diagram from a mating layout

Description

Returns the interactive diagram the Pedigree Browser's Diagram tab shows, as a visNetwork widget, for a layout made by makePedigreeMatingLayout. The Shiny application draws its Diagram with this function, so a script that calls it gets the same picture: the sex symbols at the layout's fixed positions, the legend (the five sex symbols, one row per affected condition or a single “Affected” row, “Deceased”, and the dashed repeat-appearance and twin lines), each multi-condition symbol split into its colored sections, the slash through each deceased animal's symbol, a canvas that grows with the number of conditions, the Export Diagram (PNG) button, a “Select by id” box that lists the animals, and the highlight on hover. The sections and the slash are painted by a drawing script inside the widget, so they appear wherever the widget is shown: in the RStudio viewer, in an R Markdown or Quarto document, or in a web page saved with htmlwidgets::saveWidget().

Usage

drawPedigreeDiagram(
  layout,
  edgeStyle = c("rectilinear", "direct"),
  onClick = NULL
)

Arguments

Details

Clicking an animal re-centers the Shiny application's Diagram on it; that needs a live Shiny session, so a script leaves onClick out.

Value

A visNetwork widget, 500 pixels tall, 45 more for each affected condition past the first (at most four are drawn).

See Also

makePedigreeMatingLayout

Examples

library(nprcgenekeepr)
layout <- makePedigreeMatingLayout(nprcgenekeepr::smallPed)
diagram <- drawPedigreeDiagram(layout)
## Print `diagram` in an interactive session to see it, or save it as a web
## page with htmlwidgets::saveWidget(diagram, "pedigree.html").

Example nprcgenekeepr configuration file (loadable)

Description

A loadable version of the example configuration file example_nprcgenekeepr_config. It contains a working version of a nprcgenekeepr configuration file created at the SNPRC. Users of LabKey's EHR can adapt it to their systems and put it in their home directory. Instructions are embedded as comments within the file.

Usage

data(exampleNprcgenekeeprConfig)

Format

An object of class character of length 89.

Examples

library(nprcgenekeepr)
data("exampleNprcgenekeeprConfig")
head(exampleNprcgenekeeprConfig)

Example pedigree object (from ExamplePedigree.csv)

Description

A pedigree object created by qcStudbook. Represents pedigree from ExamplePedigree.csv.

id

– character column of animal IDs

sire

– the male parent of the animal indicated by the id column. Unknown sires are indicated with NA

dam

– the female parent of the animal indicated by the id column. Unknown dams are indicated with NA

sex

– factor with levels: "F", "M", "H", "U". Sex specifier for an individual.

gen

– generation number (integers beginning with 0 for the founder generation) of the animal indicated by the id column.

birth

– Date vector of birth dates

exit

– Date vector of exit dates

age

– numerical vector of age in years

ancestry

– factor with levels: INDIAN, CHINESE, HYBRID, JAPANESE, OTHER, UNKNOWN indicating the geographic population of origin.

origin

– character vector or NA (optional) that indicates the name of the facility that the individual was imported from if other than local.

status

– character vector or NA. Flag indicating an individual's status as alive, dead, sold, etc. Transformed to factor {levels: ALIVE, DECEASED, SHIPPED, UNKNOWN}. Vector of standardized status codes with the possible values ALIVE, DECEASED, SHIPPED, or UNKNOWN

recordStatus

– character vector with value of "added" or "original".

fromCenter

– logical vector indicating whether the animal was born at the local center (colony-origin), derived from origin and recordStatus: TRUE when origin is blank and recordStatus is "original"; FALSE for animals imported from elsewhere (non-blank origin) or for synthetic placeholder second-parent rows (recordStatus == "added") whose true origin is not confirmed. Required by getPotentialParents to identify in-colony candidate parents.

Usage

data(examplePedigree)

Format

An object of class data.frame with 3694 rows and 13 columns.

Examples

library(nprcgenekeepr)
data("examplePedigree")
exampleTree <- createPedTree(examplePedigree)
exampleLoops <- findLoops(exampleTree)

Form breeding groups to match a target sex ratio

Description

The sex ratio is the number of non-males (females and animals of other or unknown sex) per male. A male is placed only if he is at least minAge years old; a male younger than that, or with no birth date, is left out of the groups.

Usage

fillGroupMembersWithSexRatio(
  candidates,
  groupMembers,
  grpNum,
  kin,
  ped,
  minAge,
  numGp,
  sexRatio
)

Arguments

Value

The groupMembers list, with one character vector of animal IDs per group (numGp groups), each filled so that its sex ratio is as close as possible to the ratio specified by sexRatio.

Examples

library(nprcgenekeepr)
examplePedigree <- nprcgenekeepr::examplePedigree
examplePedigree <- examplePedigree[1:300, ] # Comment out for full example
ped <- qcStudbook(examplePedigree,
  minSireAge = 2L, minDamAge = 2L, reportChanges = FALSE,
  reportErrors = FALSE
)

kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen, sparse = FALSE)
currentGroups <- list(1)
currentGroups[[1]] <- examplePedigree$id[1L:3L]
candidates <- examplePedigree$id[examplePedigree$status == "ALIVE"]
threshold <- 0.015625
kin <- getAnimalsWithHighKinship(kmat, ped, threshold, currentGroups,
  ignore = list(c("F", "F")), minAge = 1L
)
# Filtering out candidates related to current group members
conflicts <- unique(c(
  unlist(kin[unlist(currentGroups)]),
  unlist(currentGroups)
))
candidates <- setdiff(candidates, conflicts)

kin <- addAnimalsWithNoRelative(kin, candidates)

ignore <- NULL
minAge <- 1.0
numGp <- 1L
harem <- FALSE
sexRatio <- 0.0
withKin <- FALSE
groupMembers <- nprcgenekeepr::makeGroupMembers(numGp,
  currentGroups,
  candidates,
  ped,
  harem = harem,
  minAge = minAge
)
groupMembersStart <- groupMembers
grpNum <- nprcgenekeepr::makeGroupNum(numGp)

groupMembers <- fillGroupMembersWithSexRatio(
  candidates, groupMembers, grpNum, kin, ped, minAge, numGp,
  sexRatio = 1.0
)

Filter a kinship matrix to selected IDs

Description

Filter a kinship matrix to selected IDs

Usage

filterKinMatrix(ids, kmat)

Arguments

Value

A numeric matrix that is the reduced kinship matrix with named rows and columns (row and col names are 'ids'). It is a matrix however many IDs match: 1 x 1 for one ID, and with no rows or columns when none match.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::qcPed
ped$gen <- findGeneration(ped$id, ped$sire, ped$dam)
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen,
  sparse = FALSE
)
ids <- ped$id[c(189, 192, 194, 195)]
ncol(kmat)
nrow(kmat)
kmatFiltered <- filterKinMatrix(ids, kmat)
ncol(kmatFiltered)
nrow(kmatFiltered)

Filter kinship pairs by the animals' sexes

Description

Part of Group Formation

Usage

filterPairs(
  kin,
  ped,
  ignore = list(c(sexCodes[["female"]], sexCodes[["female"]]))
)

Arguments

Value

A dataframe representing a filtered long-format kinship table.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
ped$gen <- findGeneration(ped$id, ped$sire, ped$dam)
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen)
kin <- kinMatrix2LongForm(kmat, removeDups = FALSE)
threshold <- 0.1
kin <- filterThreshold(kin, threshold = threshold)
ped$sex <- c("M", "F", "M", "M", "F", "F", "M")
kinNull <- filterPairs(kin, ped, ignore = NULL)
kinMM <- filterPairs(kin, ped, ignore = list(c("M", "M")))
ped
kin[kin$id1 == "C", ]
kinMM[kinMM$id1 == "C", ]

Filter a genetic value report to selected animals

Description

Filter a genetic value report to selected animals

Usage

filterReport(ids, rpt)

Arguments

Value

A copy of report specific to the specified animals.

Examples

library(nprcgenekeepr)
rpt <- nprcgenekeepr::pedWithGenotypeReport$report
rpt1 <- filterReport(c("GHH9LB", "BD41WW"), rpt)

Filter out kinship pairs below a threshold

Description

Part of Group Formation Filters kinship values less than the specified threshold from a long-format table of kinship values.

Usage

filterThreshold(kin, threshold = 0.015625)

Arguments

Value

The filtered long-format kinship table (a data.frame) with all kinship relationships below the threshold value removed.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
ped$gen <- findGeneration(ped$id, ped$sire, ped$dam)
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen)
kin <- kinMatrix2LongForm(kmat, removeDups = FALSE)
kinFiltered_0.3 <- filterThreshold(kin, threshold = 0.3)
kinFiltered_0.1 <- filterThreshold(kin, threshold = 0.1)

Genetic-value report list prior to ranking

Description

A list object created from the list object rpt prepared by reportGV. It is created inside orderReport. This version is at the state just prior to calling rankSubjects inside orderReport.

Usage

data(finalRpt)

Format

An object of class list of length 3.

Details

It is a list of three data frames: highGu, lowMk and lowVal. Each has the 13 columns id, sex, age, birth, exit, population, first_name, second_name, indivMeanKin, zScores, gu, totalOffspring and livingOffspring.

Examples

library(nprcgenekeepr)
data("finalRpt")
finalRpt <- rankSubjects(finalRpt)

Determine the generation number for each ID

Description

This loops through the entire pedigree one generation at a time. It finds the zeroth generation during first loop. The first time through this loop no sire or dam is in parents. This means that the animals without a sire and without a dam are assigned to generation 0 and become the first parental generation. The second time through this loop finds all of the animals that do not have a sire or do not have a dam and at least one parent is in the vector of parents defined the first time through. The ids that were not assigned as parents in the previous loop are given the incremented generation number.

Usage

findGeneration(id, sire, dam)

Arguments

Details

Subsequent trips in the loop repeat what was done the second time through until no further animals can be added to the nextGen vector.

This does not work if the pedigree does not have all parent IDs as ego IDs.

Value

An integer vector indication the generation numbers for each id, starting at 0 for individuals lacking IDs for both parents. Any id that cannot be placed — e.g. when the pedigree contains a cycle or references a parent ID that is not itself present as an ego ID — is returned as NA and triggers a warning naming the affected ids.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped[, c("id", "sire", "dam")]
ped$gen <- findGeneration(ped$id, ped$sire, ped$dam)
ped

Find loops in a pedigree tree

Description

Part of Pedigree Sampling From PedigreeSampling.R 2016-01-28

Usage

findLoops(ptree)

Arguments

Details

Contains functions to build pedigrees from sub-samples of genotyped individuals.

The goal of sampling is to reduce the number of inbreeding loops in the resulting pedigree, and thus, reduce the amount of time required to perform calculations with SIMWALK2 or similar programs.

Value

A named list of logical values where each named element is named with an id from ptree. The value of the list element is set to TRUE if the id has a loop in the pedigree. Loops occur when an animal's sire and dam have a common ancestor.

Examples

data("examplePedigree")
exampleTree <- createPedTree(examplePedigree)
exampleLoops <- findLoops(exampleTree)

Count total offspring for each animal

Description

Part of Genetic Value Analysis

Usage

findOffspring(probands, ped)

Arguments

Value

A named integer vector containing the offspring counts for each animal in probands. The names are set to the IDs from probands, and an ID that is not a parent in ped gets 0.

Examples

library(nprcgenekeepr)
examplePedigree <- nprcgenekeepr::examplePedigree
breederPed <- qcStudbook(examplePedigree,
  minSireAge = 2,
  minDamAge = 2,
  reportChanges = FALSE,
  reportErrors = FALSE
)
focalAnimals <- breederPed$id[!(is.na(breederPed$sire) &
  is.na(breederPed$dam)) &
  is.na(breederPed$exit)]
ped <- setPopulation(ped = breederPed, ids = focalAnimals)
trimmedPed <- trimPedigree(focalAnimals, breederPed)
probands <- ped$id[ped$population]
totalOffspring <- findOffspring(probands, ped)

Determine the pedigree number for each ID

Description

One of Pedigree Curation functions

Usage

findPedigreeNumber(id, sire, dam)

Arguments

Value

Integer vector indicating the pedigree (family group) number for each id. Ids that are connected through parent-offspring links share the same number; numbering starts at 1. Numbering starts from ids with both parents unknown (NA), so an id that cannot be reached from such an id, for example one whose only parent is absent from id, or one in a cycle, is returned as NA.

Examples

library(nprcgenekeepr)
library(stringi)
ped <- nprcgenekeepr::lacy1989Ped
ped$gen <- NULL
ped$population <- NULL
ped2 <- ped
ped2$id <- stri_c(ped$id, "2")
ped2$sire <- stri_c(ped$sire, "2")
ped2$dam <- stri_c(ped$dam, "2")
ped3 <- ped
ped3$id <- stri_c(ped$id, "3")
ped3$sire <- stri_c(ped$sire, "3")
ped3$dam <- stri_c(ped$dam, "3")
ped <- rbind(ped, ped2)
ped <- rbind(ped, ped3)
ped$pedigree <- findPedigreeNumber(ped$id, ped$sire, ped$dam)
ped$pedigree

Standardize pedigree column names

Description

Standardizing converts the names to lower case, removes spaces, periods and underscores, and then renames by substring: egoid and ego become id, sireid becomes sire, damid becomes dam, birthdate becomes birth and deathdate becomes death. recordstatus, fromcenter and geographicorigin are restored to their camel case forms; a header already spelled recordStatus, fromCenter or geographicOrigin is not recorded as a change. The headers first_name and second_name keep their underscore. The matching is unanchored, so any name that contains one of these strings is changed (for example, category becomes catidry). A header that is NA is read as a blank one, so a nameless column is reported the way a column with a blank header is.

Usage

fixColumnNames(orgCols, errorLst)

Arguments

Value

A list object with newColNames and errorLst with a record of all changes made.

Examples

library(nprcgenekeepr)
fixColumnNames(c("Sire_ID", "EGO", "DAM", "Id", "birth_date"),
  errorLst = getEmptyErrorLst()
)

Focal animal IDs from examplePedigree

Description

A dataframe with one column (id) containing the animal Ids from the examplePedigree pedigree. They can be used to illustrate the identification of a population of interest as is shown in the example below. The id column is a factor, not a character vector like the id column of examplePedigree; use as.character(focalAnimals$id) when the two need the same type.

Usage

data(focalAnimals)

Format

An object of class data.frame with 327 rows and 1 columns.

Examples

library(nprcgenekeepr)
data("focalAnimals")
data("examplePedigree")
any(names(examplePedigree) == "population")
nrow(examplePedigree)
examplePedigree <- setPopulation(
  ped = examplePedigree,
  ids = focalAnimals$id
)
any(names(examplePedigree) == "population")
nrow(examplePedigree)
nrow(examplePedigree[examplePedigree$population, ])

Simulate gene dropping through a pedigree

Description

Part of Genetic Value Analysis

Usage

geneDrop(
  ids,
  sires,
  dams,
  gen,
  genotype = NULL,
  n = 1000L,
  updateProgress = NULL
)

Arguments

Details

The gene dropping method from Pedigree analysis by computer simulation by Jean W MacCluer, John L Vandeberg, and Oliver A Ryder (1986) https://doi.org/10.1002/zoo.1430050209 is used in the genetic value calculations.

Currently there is no means of handling knowing only one haplotype. Another column could be added to handle situations where only one allele is observed and it is not known to be homozygous or heterozygous. The new fourth column could have a frequency for homozygosity that could be used in the gene dropping algorithm.

The genotypes are using indirection (integer instead of character) to indicate the genes because the manipulation of character strings was found to take 20-35 times longer to perform.

Adding additional columns to genotype does not significantly affect the time require. Thus, it is convenient to add the corresponding haplotype names to the dataframe using first_name and second_name.

Animal IDs (ids) must not contain a period ("."). A period is disallowed because it causes problems across software environments (R column-name and formula parsing, file-name extensions, programming-language namespaces, and regular expressions); geneDrop additionally relies on the period internally to recover the id and parent of each allele row, so a period-bearing id would silently corrupt the result. IDs containing a period are therefore rejected with an error. The same rule is enforced at data input by qcStudbook and honored by all automatically generated IDs.

Animal IDs (ids) must also be unique. geneDrop indexes each animal's parents and accumulates its simulated alleles by id, so duplicate ids are rejected with an error. This invariant is established upstream by qcStudbook (via removeDuplicates) and by kinship, both of which require unique ids.

Value

A data.frame V1 ... Vn, id, parent A data.frame providing the maternal and paternal alleles for an animal for each iteration. The first n columns indicate the allele for each iteration. These are followed by two columns: id, the animal's ID, and parent, whether the allele came from the sire ("sire") or dam ("dam"). Each animal has two rows, and the animals are ordered by generation, oldest first.

Examples

## We usually define `n` to be >= 1000
library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
allelesNew <- geneDrop(ped$id, ped$sire, ped$dam, ped$gen,
  genotype = NULL, n = 50, updateProgress = NULL
)
genotype <- data.frame(
  id = ped$id,
  first_allele = c(
    NA, NA, "A001_B001", "A001_B002",
    NA, "A001_B002", "A001_B001"
  ),
  second_allele = c(
    NA, NA, "A010_B001", "A001_B001",
    NA, NA, NA
  ),
  stringsAsFactors = FALSE
)
pedWithGenotype <- addGenotype(ped, genotype)
pedGenotype <- getGVGenotype(pedWithGenotype)
allelesNewGen <- geneDrop(ped$id, ped$sire, ped$dam, ped$gen,
  genotype = pedGenotype,
  n = 5, updateProgress = NULL
)

Recursively collect an individual's ancestors

Description

Part of Pedigree Sampling From PedigreeSampling.R 2016-01-28

Usage

getAncestors(id, ptree)

Arguments

Details

Contains functions to build pedigrees from sub-samples of genotyped individuals.

The goal of sampling is to reduce the number of inbreeding loops in the resulting pedigree, and thus, reduce the amount of time required to perform calculations with SIMWALK2 or similar programs.

An ancestor reached through both parents is returned once for each route. The function stops with an error that names the ids involved when ptree contains a cycle (an animal that is its own ancestor), which is a data error.

A sire or dam that has no entry of its own in ptree is treated as an animal with unknown parents, as qcStudbook() treats it (addParents() adds the entry): it is returned as an ancestor and has no ancestors of its own. The function stops with an error that names the id when id itself is not in ptree.

Value

A character vector of ancestors for an individual ID.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::qcPed
ped <- qcStudbook(ped, minSireAge = 0, minDamAge = 0)
pedTree <- createPedTree(ped)
pedLoops <- findLoops(pedTree)
ids <- names(pedTree)
allAncestors <- list()

for (i in seq_along(ids)) {
  id <- ids[[i]]
  anc <- getAncestors(id, pedTree)
  allAncestors[[id]] <- anc
}
head(allAncestors)
countOfAncestors <- unlist(lapply(allAncestors, length))
idsWithMostAncestors <-
  names(allAncestors)[countOfAncestors == max(countOfAncestors)]
allAncestors[idsWithMostAncestors]

List each animal's high-kinship relatives

Description

List each animal's high-kinship relatives

Usage

getAnimalsWithHighKinship(kmat, ped, threshold, currentGroups, ignore, minAge)

Arguments

Value

A one-dimensional array of mode list (from tapply()), not a plain list. Its names are animal IDs, and each element is a character vector of animals sharing a kinship value greater than or equal to the threshold value. names() and [[ work as for a list.

Examples

qcPed <- nprcgenekeepr::qcPed
ped <- qcStudbook(qcPed,
  minSireAge = 2L, minDamAge = 2L, reportChanges = FALSE,
  reportErrors = FALSE
)
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen, sparse = FALSE)
currentGroups <- list(1L)
currentGroups[[1L]] <- examplePedigree$id[1L:3L]
candidates <- examplePedigree$id[examplePedigree$status == "ALIVE"]
threshold <- 0.015625
kin <- getAnimalsWithHighKinship(kmat, ped, threshold, currentGroups,
  ignore = list(c("F", "F")), minAge = 1.0
)
length(kin) # should be 259
kin[["0DAV0I"]] # should have 34 IDs

Get the auto-generated unknown-ID format

Description

Returns the sprintf template used to mint placeholder IDs for unknown parents (see addUIds) and to detect them. The format is the single source of truth shared by ID generation and ID detection.

Usage

getAutoIdFormat()

Details

The value is read from getOption("nprcgenekeepr.autoIdFormat"), defaulting to "U%04d" (a leading "U" plus a zero-padded integer) for backward compatibility. Set it with setAutoIdFormat.

Value

A single character string: the auto-ID sprintf format.

See Also

setAutoIdFormat, addUIds

Examples

getAutoIdFormat()

Get Box and Whisker Plot Description

Description

Returns a description of how box and whisker plots work, suitable for use in popovers and tooltips in the Shiny application.

Usage

getBoxWhiskerDescription()

Value

Character string containing the box and whisker plot description explaining whiskers, IQR (inter-quartile range), and outliers.

See Also

modSummaryStatsServer which uses this for popovers

Examples

desc <- getBoxWhiskerDescription()
cat(desc)

Build the changed-columns tab panel

Description

Build the changed-columns tab panel

Usage

getChangedColsTab(errorLst, pedigreeFileName)

Arguments

Value

A Shiny tabPanel titled "Changed Columns" that holds the HTML-formatted list of column changes made by qcStudbook.

Get the configuration file name for the system

Description

Get the configuration file name for the system

Usage

getConfigFileName(sysInfo)

Arguments

Value

A named character vector of length two: homeDir is the user's home directory and configFile is the expected configuration file path. Only sysInfo[["sysname"]] is used, to choose the file name (_nprcgenekeepr_config on Windows, otherwise .nprcgenekeepr_config).

Examples

library(nprcgenekeepr)
sysInfo <- Sys.info()
config <- getConfigFileName(sysInfo)

Calculate current age in years from a birth date

Description

Assumes current date for calculating age.

Usage

getCurrentAge(birth)

Arguments

Value

Age in years using the provided birthdate.

Examples

library(nprcgenekeepr)
age <- getCurrentAge(birth = as.Date("06/02/2000", format = "%m/%d/%Y"))

Find date errors and convert dates in a pedigree

Description

Finds date errors in columns defined in convertDate as dates and converts date strings to Date objects.

Usage

getDateErrorsAndConvertDatesInPed(sb, errorLst)

Arguments

Details

Every date column is checked on its own and each invalid date is listed by row; the invalid dates become NA in the converted pedigree, and exit dates are calculated and added, unless every original record has an invalid date, in which case the pedigree is returned unchanged.

Value

A list with the pedigree, sb, and the errorLst with invalid date rows (errorLst$invalidDateRows), a character vector of row numbers (character(0) when all dates are valid). When the dates are converted, sb also gains an exit column.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::pedInvalidDates
ped
errorLst <- getEmptyErrorLst()
colNamesAndErrors <- fixColumnNames(names(ped), errorLst)
names(ped) <- colNamesAndErrors$newColNames
pedAndErrors <- getDateErrorsAndConvertDatesInPed(ped, errorLst)
pedAndErrors$sb
pedAndErrors$errorLst

Prepend the date and time to a file name

Description

Prepend the date and time to a file name

Usage

getDatedFilename(filename)

Arguments

Value

A character string with filename prepended with the current date and time. The prefix is as.character() of the current time with spaces and colons replaced by underscores; it can include fractional seconds, for example 2026-10-01_15_39_25.959408_testName.

Examples

library(nprcgenekeepr)
getDatedFilename("testName")

Get demographic data

Description

This is a thin wrapper around labkey.selectRows(). It uses the site configuration from getSiteInfo (the configuration file, or the defaults plus a warning when there is no file) and sets the LabKey credentials with setLabKeyDefaults. All columns are returned, including hidden ones, when colSelect is NULL.

Usage

getDemographics(colSelect = NULL)

Arguments

Value

A data.frame containing LabKey demographic data with the columns specified in the single parameter provided.

Examples

## Not run: 
## Needs a connection to a LabKey server
library(nprcgenekeepr)
siteInfo <- getSiteInfo()
colSet <- siteInfo$lkPedColumns
source <- " generated by getDemographics: "
pedSourceDf <- tryCatch(getDemographics(colSelect = colSet),
  warning = function(wCond) {
    cat(paste0("Warning", source, wCond),
      name = "nprcgenekeepr"
    )
    return(NULL)
  },
  error = function(eCond) {
    cat(paste0("Error", source, eCond),
      name = "nprcgenekeepr"
    )
    return(NULL)
  }
)

## End(Not run)

Reduce a pedigree to a group and its descendants

Description

Filters a pedigree down to only the descendants of the provided group, building the pedigree forward in time starting from a group of probands. This is the downward (descendants-only) mirror of getProbandPedigree: it takes the transitive closure over offspring and returns the probands together with all of their descendants. It does not include collateral relatives (siblings, cousins, or mates).

Usage

getDescendantPedigree(probands, ped)

Arguments

Value

A reduced pedigree containing the probands and all of their descendants.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
## D's descendants are F and G
getDescendantPedigree(probands = "D", ped = ped)$id

Create an empty errorLst object

Description

Create an empty errorLst object

Usage

getEmptyErrorLst()

Value

An errorLst object (a list of class nprcgenekeeprErr) with placeholders for error types found in a pedigree file by qcStudbook. Its 11 fields are failedDatabaseConnection, missingColumns, invalidDateRows, suspiciousParents, femaleSires, maleDams, sireAndDam, duplicateIds, invalidIdChars, invalidPlaceholderRows and changedCols (a list of the column-name changes).

Examples

library(nprcgenekeepr)
getEmptyErrorLst()

Build the error-list tab panel

Description

Build the error-list tab panel

Usage

getErrorTab(errorLst, pedigreeFileName)

Arguments

Value

A Shiny tabPanel titled "Error List" that holds the HTML-formatted list of errors found by qcStudbook.

Get the direct relatives of selected animals from a pedigree file

Description

File-sourced sibling of getLkDirectRelatives: reads a pedigree file through the internal getPedigreeSource() "file" provider (via getPedigree), then delegates the pedigree walk to the source-agnostic getPedDirectRelatives. The result is the full connected pedigree component (ancestors, descendants, and collaterals such as siblings and mates) reachable from the focal animals. It is fully offline and deterministic.

Usage

getFileDirectRelatives(
  ids,
  fileName = NULL,
  sep = ",",
  unrelatedParents = FALSE
)

Arguments

Details

Unlike the LabKey source, which fails soft (returns NULL) when its fetch fails, the file source errors loudly: a NULL or missing fileName, a file that does not exist, or a file lacking the id, sire, and dam columns each raises an error.

Value

A data.frame with pedigree structure containing all direct relatives – the full connected pedigree component (ancestors, descendants, and collaterals) – for the Ids provided.

See Also

Other direct relatives: getLkDirectAncestors(), getLkDirectRelatives(), getPedDirectRelatives()

Examples

library(nprcgenekeepr)
## Build a tiny pedigree file, then pull the relatives of a focal animal.
ped <- data.frame(
  id = c("A", "B", "C"), sire = c(NA, NA, "A"), dam = c(NA, NA, "B"),
  stringsAsFactors = FALSE
)
pedFile <- tempfile(fileext = ".csv")
write.csv(ped, pedFile, row.names = FALSE)
getFileDirectRelatives(ids = "C", fileName = pedFile)
unlink(pedFile)

Get pedigree based on list of focal animals

Description

Reads the focal animal ids from the first column of a CSV or Excel file and pulls the pedigree of their relatives from LabKey.

Usage

getFocalAnimalPed(fileName, sep = ",")

Arguments

Value

A data.frame (not a file) with columns id, sex, birth, death, departure, dam and sire; the dates are character strings formatted as %Y-%m-%d. When the LabKey connection fails, an nprcgenekeeprErr list with failedDatabaseConnection set is returned instead.

Examples

library(nprcgenekeepr)
## A successful call needs a LabKey connection and a file of focal ids.
## This file does not exist, so the example shows the error handler.
source <- " generated by getFocalAnimalPed: "
tryCatch(getFocalAnimalPed(fileName = "breeding file.csv"),
  warning = function(wCond) {
    cat(paste0("Warning", source, wCond),
      name = "nprcgenekeepr"
    )
    return(NULL)
  },
  error = function(eCond) {
    cat(paste0("Error", source, eCond),
      name = "nprcgenekeepr"
    )
    return(NULL)
  }
)

Get a focal-animal pedigree from a pedigree file

Description

File-sourced sibling of getFocalAnimalPed: reads a list of focal animal Ids from fileName (the first column, exactly as getFocalAnimalPed does), then builds the focal animals' full connected pedigree component from a SEPARATE pedigree file via getFileDirectRelatives. This lets the focal-animal workflow run entirely offline – no LabKey / EHR connection is required.

Usage

getFocalAnimalPedFromFile(fileName, pedigreeFileName = NULL, sep = ",")

Arguments

Details

The underlying file source errors loudly on a bad pedigree file, but this function is the application boundary, so it is fail-soft: it does NOT throw. On failure it returns a classed nprcgenekeeprFileErr object whose message names the reason – a missing, not-found, or unreadable pedigree file, or one lacking the id, sire, and dam columns. (This mirrors how the app's other file inputs behave – the message surfaces as a "File Read Error" – and is distinct from the LabKey path, which returns an nprcgenekeeprErr.)

Value

On success, a data.frame with the focal animals' full connected pedigree component (ancestors, descendants, and collaterals), as returned by getFileDirectRelatives. On any failure this function does NOT throw: it returns a classed nprcgenekeeprFileErr object (a list with a message element) naming WHY the read failed – an unreadable focal-id list file; a missing, not-found, unreadable, or wrong-column pedigree file; or no focal IDs present in the pedigree. The application surfaces message as the "File Read Error" detail (distinct from the LabKey path, which returns an nprcgenekeeprErr).

Examples

library(nprcgenekeepr)
## A focal-id file and a pedigree file, then build the pedigree offline.
ped <- data.frame(
  id = c("A", "B", "C"), sire = c(NA, NA, "A"), dam = c(NA, NA, "B"),
  stringsAsFactors = FALSE
)
pedFile <- tempfile(fileext = ".csv")
write.csv(ped, pedFile, row.names = FALSE)
focalFile <- tempfile(fileext = ".csv")
write.csv(data.frame(id = "C"), focalFile, row.names = FALSE)
getFocalAnimalPedFromFile(focalFile, pedFile)
unlink(c(pedFile, focalFile))

Get the founder ids from a pedigree

Description

Part of Pedigree Curation

Usage

getFounders(ped)

Arguments

Details

A founder is an animal whose sire and dam are both unknown (NA). Animals with exactly one known parent (partial parentage) are not founders.

Value

A vector of the id values of the founders, in pedigree order. It has the same type as ped$id and is empty when there are no founders.

See Also

isFounder for the founder logical mask.

Examples

library(nprcgenekeepr)
ped <- data.frame(
  id = c("A", "B", "C", "D", "E", "F", "G"),
  sire = c(NA, NA, "A", "A", NA, "D", "D"),
  dam = c(NA, NA, "B", "B", NA, "E", "E"),
  stringsAsFactors = FALSE
)
getFounders(ped)

Extract genotype data for a genetic value report

Description

Extracts genotype data if available otherwise NULL is returned.

Usage

getGVGenotype(ped)

Arguments

Value

A data.frame with the columns id, first, and second extracted from a pedigree object (a data.frame) containing genotypic data. If the pedigree object does not contain genotypic data (columns id, first and second, with numeric first and second), NULL is returned.

Examples

## We usually define `n` to be >= 1000. The first part of this example is
## the same as the one for `geneDrop()`; `getGVGenotype()` is used on the
## last lines.
library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
allelesNew <- geneDrop(ped$id, ped$sire, ped$dam, ped$gen,
  genotype = NULL, n = 50, updateProgress = NULL
)
genotype <- data.frame(
  id = ped$id,
  first_allele = c(
    NA, NA, "A001_B001", "A001_B002",
    NA, "A001_B002", "A001_B001"
  ),
  second_allele = c(
    NA, NA, "A010_B001", "A001_B001",
    NA, NA, NA
  ),
  stringsAsFactors = FALSE
)
pedWithGenotype <- addGenotype(ped, genotype)
pedGenotype <- getGVGenotype(pedWithGenotype)
allelesNewGen <- geneDrop(ped$id, ped$sire, ped$dam, ped$gen,
  genotype = pedGenotype,
  n = 5, updateProgress = NULL
)

Get the population of interest for the Genetic Value analysis

Description

If user has limited the population of interest by defining pop, that information is incorporated via the ped$population column.

Usage

getGVPopulation(ped, pop)

Arguments

Value

A logical vector with one element per row of ped, in the order of ped: TRUE if the animal is in the population of interest. IDs in pop that are not in ped are ignored.

Examples

## Example from Analysis of Founder Representation in Pedigrees: Founder
## Equivalents and Founder Genome Equivalents.
## Zoo Biology 8:111-123, (1989) by Robert C. Lacy
library(nprcgenekeepr)
ped <- data.frame(
  id = c("A", "B", "C", "D", "E", "F", "G"),
  sire = c(NA, NA, "A", "A", NA, "D", "D"),
  dam = c(NA, NA, "B", "B", NA, "E", "E"),
  stringsAsFactors = FALSE
)
ped["gen"] <- findGeneration(ped$id, ped$sire, ped$dam)
ped$population <- getGVPopulation(ped, NULL)

Assemble breeding-group genetic diversity heat-map statistics

Description

Assemble breeding-group genetic diversity heat-map statistics

Usage

getGeneticDiversityStats(
  groups,
  ped,
  geneticValues,
  kmat,
  housing = "shelter_pens",
  currentDate = Sys.Date()
)

Arguments

Details

For each breeding group this builds the heat-map color indices by calling the per-group providers: Value from getProportionLow, Origin from getIndianOriginStatus, Production from getProductionStatus, and Inbreeding from getKinshipWithMaleStatus. The result is the group-by-metric data frame consumed by makeGeneticDiversityHeatmap: the first column holds the group label and each remaining column holds a color index (1 red, 2 yellow, 3 green).

Age is derived from each member's birth date using currentDate rather than read from a possibly-absent age column, so the age filters and the production birth window share one reference date. Genetic-value labels of "Undetermined" are dropped before the Value proportion is taken. A group with no assessed value, and a group whose Inbreeding metric is undefined (no breeding-age females), are both scored red so that missing data is surfaced rather than shown as healthy green. When the pedigree has no ancestry column the Origin metric cannot be computed and its column is omitted.

Production is the number of births in the two calendar years ending the year before currentDate that lived at least 30 days, divided by the number of breeding-age females in the group: females at least 3 years old. A female with no birth date has no age. She counts as a breeding-age female only when the pedigree (ped) lists at least one animal as her offspring, looked up in the whole pedigree and not only in her group, so a mother whose offspring are in another group still counts. A female with no birth date and no offspring is left out, and so is an animal with a blank sex. A group with no breeding-age females has no Production value: its entry is NA, and the heat map draws that cell gray.

The Inbreeding column counts breeding-age females by the same rule: a female with no birth date counts when the pedigree lists an offspring for her, and is left out otherwise. A male with no birth date is never counted as a potential mate.

Value

A data frame with one row per group: the first column group holds the group label and each remaining column (Value, Origin when available, Production, Inbreeding) holds an integer color index in c(1, 2, 3). Production is NA for a group with no breeding-age females.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::qcPed
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen, sparse = FALSE)
## The genetic value report of qcPed, stored with the package
geneticValues <- nprcgenekeepr::qcPedGvReport$report
## Three groups of living animals that have a genetic value
living <- geneticValues$id[geneticValues$id %in% ped$id[is.na(ped$exit)]]
groups <- list(
  "Group 1" = living[1L:15L],
  "Group 2" = living[16L:30L],
  "Group 3" = living[31L:45L]
)
getGeneticDiversityStats(groups, ped, geneticValues, kmat)

Get genotypes from file

Description

Get genotypes from file

Usage

getGenotypes(fileName, sep = ",")

Arguments

Value

The file's contents as an unchecked dataframe (column names are not changed). In a delimited text file an empty string and "NA" are read as NA. Pass the result to checkGenotypeFile to make it compatible with the other functions in this package.

Examples

library(nprcgenekeepr)
pedCsv <- getGenotypes(fileName = system.file("testdata", "qcPed.csv",
  package = "nprcgenekeepr"
))

Get ids of animals with only one parent

Description

Get ids of animals with only one parent

Usage

getIdsWithOneParent(uPed)

Arguments

Value

Character vector of the IDs of animals with exactly one known parent.

Examples

examplePedigree <- nprcgenekeepr::examplePedigree
breederPed <- qcStudbook(examplePedigree,
  minSireAge = 2, minDamAge = 2,
  reportChanges = FALSE,
  reportErrors = FALSE
)
probands <- breederPed$id[!(is.na(breederPed$sire) &
  is.na(breederPed$dam)) &
  is.na(breederPed$exit)]
ped <- getProbandPedigree(probands, breederPed)
nrow(ped)
p <- removeUninformativeFounders(ped)
nrow(p)
p <- addBackSecondParents(p, ped)
nrow(p)
getIdsWithOneParent(p)

Get the superset of report-inclusion columns

Description

Part of Genetic Value Functions

Usage

getIncludeColumns()

Details

Replaces INCLUDE.COLUMNS data statement.

Value

A character vector of the ten columns kept in genetic-value reports (id, sex, age, birth, exit, population, condition, origin, first_name and second_name). It is not the set of columns a pedigree file may contain; that is returned by getPossibleCols.

Examples

getIncludeColumns()

Get the direct ancestors of selected animals

Description

Gets direct ancestors from labkey study schema and demographics table.

Usage

getLkDirectAncestors(ids)

Arguments

Value

data.frame with pedigree structure having the records of the Ids provided (the focal animals themselves) and all of their direct ancestors. NULL is returned when the site configuration cannot be read or the LabKey data cannot be fetched.

See Also

Other direct relatives: getFileDirectRelatives(), getLkDirectRelatives(), getPedDirectRelatives()

Examples

## Not run: 
# Requires LabKey connection
library(nprcgenekeepr)
## Have to a vector of focal animals
focalAnimals <- c("1X2701", "1X0101")
suppressWarnings(getLkDirectAncestors(ids = focalAnimals))

## End(Not run)

Get the direct relatives of selected animals from the LabKey EHR

Description

Builds the pedigree of relatives for the provided focal animals from the LabKey study schema demographics table, obtained through the internal getPedigreeSource() adapter. The pedigree walk is delegated to getPedDirectRelatives(), so the result is the full connected pedigree component (ancestors, descendants, and collaterals such as siblings and mates) reachable from the focal animals.

Usage

getLkDirectRelatives(ids, unrelatedParents = FALSE)

Arguments

Value

A data.frame with pedigree structure containing all direct relatives – the full connected pedigree component (ancestors, descendants, and collaterals) – for the Ids provided. NULL is returned when the LabKey data cannot be fetched.

See Also

Other direct relatives: getFileDirectRelatives(), getLkDirectAncestors(), getPedDirectRelatives()

Examples

## Not run: 
# Requires LabKey connection
library(nprcgenekeepr)
## Have to a vector of focal animals
focalAnimals <- c("1X2701", "1X0101")
suppressWarnings(getLkDirectRelatives(ids = focalAnimals))

## End(Not run)

Get offspring to corresponding animal IDs provided

Description

Get offspring to corresponding animal IDs provided

Usage

getOffspring(pedSourceDf, ids)

Arguments

Value

A character vector containing all of the offspring IDs for all of the IDs provided in the second argument ids. All offspring are combined and duplicates are removed.

Examples

library(nprcgenekeepr)
pedOne <- nprcgenekeepr::pedOne
names(pedOne) <- c("id", "sire", "dam", "sex", "birth")
getOffspring(pedOne, c("s1", "d2"))

Get parents to corresponding animal IDs provided

Description

Get parents to corresponding animal IDs provided

Usage

getParents(pedSourceDf, ids)

Arguments

Value

A character vector with the IDs of the parents of the provided ID list.

Examples

library(nprcgenekeepr)
pedOne <- nprcgenekeepr::pedOne
names(pedOne) <- c("id", "sire", "dam", "sex", "birth")
getParents(pedOne, c("o1", "d4"))

Get the direct relatives of selected animals from a pedigree

Description

Gets the full connected pedigree component reachable from the selected animals in the supplied pedigree (ped). The result includes ancestors, descendants, and collaterals such as siblings and mates. A NULL ped returns NULL.

Usage

getPedDirectRelatives(ids, ped, unrelatedParents = FALSE)

Arguments

Value

A data.frame of pedigree records for the selected animals and the full connected pedigree component (ancestors, descendants, siblings and mates) in ped, or NULL when ped is NULL.

See Also

Other direct relatives: getFileDirectRelatives(), getLkDirectAncestors(), getLkDirectRelatives()

Examples

library(nprcgenekeepr)
## A pedigree to search and a focal animal whose direct relatives we want
ped <- nprcgenekeepr::lacy1989Ped
getPedDirectRelatives(ids = "E", ped = ped)

Get the maximum age of any animal in the pedigree

Description

Returns the maximum age among all animals in the pedigree that have a non-NA age. Because ages are computed for deceased animals (age at exit) as well, the maximum can reflect a deceased animal.

Usage

getPedMaxAge(ped)

Arguments

Value

Numeric value representing the maximum age of animals in the pedigree, or NA_real_ if no animal has a non-missing age (no age column or all ages missing).

Examples

library(nprcgenekeepr)
examplePedigree <- nprcgenekeepr::examplePedigree
ped <- qcStudbook(examplePedigree,
  minSireAge = 2, minDamAge = 2,
  reportChanges = FALSE,
  reportErrors = FALSE
)
getPedMaxAge(ped)

Get pedigree from file

Description

Get pedigree from file

Usage

getPedigree(fileName, sep = ",")

Arguments

Value

A data.frame of the pedigree as read from the file, with no quality control applied (see qcStudbook). Every column read from an Excel file is returned as character.

Examples

library(nprcgenekeepr)
ped <- getPedigree(fileName = system.file("testdata", "qcPed.csv",
  package = "nprcgenekeepr"
))

Get possible column names for a studbook

Description

Pedigree curation function

Usage

getPossibleCols()

Value

A character vector of the possible columns that can be in a studbook. The possible columns are as follows:

Examples

library(nprcgenekeepr)
getPossibleCols()

Get potential parents for animals with unknown parents

Description

Usage

getPotentialParents(
  ped,
  minSireAge = NULL,
  minDamAge = NULL,
  minParentAge = lifecycle::deprecated(),
  maxGestationalPeriod = NULL,
  gestationTable = NULL
)

Arguments

Value

a list of list with each internal list being made up of an animal id (id), a vector of possible sires (sires) and a vector of possible dams (dams). The id must be defined while the vectors sires and dams can be empty. A fourth element, damBasis, is a single string saying where dams came from: "provenBreeder" when the candidates are females who gave birth near the time of the focal birth, "eligibleFemale" when there were none and dams lists every female old enough and present at the birth instead, and NA when dams is empty. In both tiers, a female who delivered another offspring within maxGestationalPeriod days of the focal birth is never listed. Candidates are listed only for the parent that is missing: when an animal's dam is recorded its dams is empty, and when its sire is recorded its sires is empty. NULL (not a list) is returned when no animal has an unknown parent with a candidate and when ped has no fromCenter column.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::rhesusPedigree
## getPotentialParents needs a logical fromCenter column flagging
## colony-born animals; add one if your pedigree lacks it.
ped$fromCenter <- TRUE
potentialParents <- getPotentialParents(
  ped = ped, minSireAge = 2, minDamAge = 2, maxGestationalPeriod = 210L
)
## Each element pairs a focal id with candidate sires and dams.
potentialParents[[1L]]

List potential sires

Description

List potential sires

Usage

getPotentialSires(ids, ped, minAge = 1L)

Arguments

Value

A character vector of potential sire Ids

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::pedWithGenotype
ids <- nprcgenekeepr::qcBreeders
getPotentialSires(ids, ped, minAge = 1L)

Reduce a pedigree to probands and their ancestors

Description

Filters a pedigree down to the provided group (the probands) together with all of their ancestors, removing unnecessary individuals from the studbook. This version builds the pedigree back in time starting from a group of probands. This will include all ancestors of the probands, even ones that might be uninformative.

Usage

getProbandPedigree(probands, ped)

Arguments

Value

A reduced pedigree.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::pedWithGenotype
ids <- nprcgenekeepr::qcBreeders
sires <- getPotentialSires(ids, ped, minAge = 1)
head(getProbandPedigree(probands = sires, ped = ped))

Get the age distribution for the pedigree

Description

Returns the pedigree with all animals, adding a status column describing each animal as ALIVE or DECEASED and a computed age column (age at exit for deceased animals). All animals are returned, not only living ones. An animal is DECEASED when it has an exit date or when its birth date is NA; otherwise it is ALIVE. When ped is NULL (the default), the packaged qcPed example data are used.

Usage

getPyramidAgeDist(ped = NULL)

Arguments

Details

The columns of ped are read by position, not by name: the first six columns must be the id, sire, dam, sex, birth and exit values in that order, and are renamed accordingly. Any further columns are dropped. If birth is not in the fifth column and of class Date, POSIXct or character, the error message reports that the birth column is of the wrong class.

The lubridate package is used here because of the way the modern Gregorian calendar is constructed, there is no straightforward arithmetic method that produces a person’s age, stated according to common usage — common usage meaning that a person’s age should always be an integer that increases exactly on a birthday.

Value

A pedigree with the six columns of ped (id, sire, dam, sex, birth, exit) and a status column added, which describes the animal as ALIVE or DECEASED and a age column added, which has the animal's age in years or NA if it cannot be calculated. The exit column values have been remapped to valid dates or NA.

Examples

library(nprcgenekeepr)
ped <- getPyramidAgeDist()

Create an age-sex pyramid plot of a pedigree

Description

The pedigree provided must have the following columns: sex and age. This needs to be augmented to allow pedigrees structures that are provided by the nprcgenekeepr package.

Usage

getPyramidPlot(
  ped = NULL,
  binWidth = 2L,
  ageUnit = "years",
  colorScheme = "default",
  showCounts = TRUE,
  ageLabelCex = 1
)

Arguments

Details

Only living animals are plotted: when ped has an exit column, animals with a non-NA exit are dropped, and only animals with sex "M" or "F" are counted. The age axis is, however, sized from the oldest animal in ped, including deceased ones. When ped is NULL (the default), the packaged qcPed example data are used. An unrecognized colorScheme silently falls back to "default".

Value

The return value of par("mar") when the function was called.

Examples

library(nprcgenekeepr)
data(qcPed)
getPyramidPlot(qcPed)
getPyramidPlot(qcPed, binWidth = 5, colorScheme = "viridis")

Get required column names for a studbook

Description

Pedigree curation function

Usage

getRequiredCols()

Value

A character vector of the required columns that can be in a studbook. The required columns are as follows:

• id – character vector with unique identifier for an individual

• sire – character vector with unique identifier for an individual's father (NA if unknown).

• dam – character vector with unique identifier for an individual's mother (NA if unknown).

• sex – factor (levels: "M", "F", "U") Sex specifier for an individual

• birth – Date or NA with the individual's birth date

Examples

library(nprcgenekeepr)
getRequiredCols()

Get site information

Description

Get site information

Usage

getSiteInfo(expectConfigFile = TRUE)

Arguments

Value

A named list of 20 elements of site specific information used by the application.

The first seven elements (center, baseUrl, schemaName, folderPath, queryName, lkPedColumns and mapPedColumns) are read from the configuration file when one exists. A configuration file that lacks one of these keys causes an error ("Could not find ..."). When no configuration file exists, the defaults for the ONPRC are returned instead: center "ONPRC", baseUrl "https://primeuat.ohsu.edu", schemaName "study", folderPath "/ONPRC/EHR" and queryName "demographics". A warning is signaled for the missing file only when expectConfigFile is TRUE.

The format of the configuration file is described in the notes at the top of the example file, example_nprcgenekeepr_config, in the package's extdata/examples folder.

The returned list contains the following elements.

1. center – center name, such as "ONPRC" or "SNPRC"

2. baseUrl – base URL of the LabKey server

3. schemaName – LabKey schema name

4. folderPath – LabKey folder path

5. queryName – LabKey query name, "demographics" by default

6. lkPedColumns – LabKey column names for the pedigree

7. mapPedColumns – the package column names that lkPedColumns are renamed to

8. sysname, release, version, nodename, machine, login, user and effective_user – character strings from Sys.info()

9. homeDir and configFile – the home directory and the expected configuration file path, from getConfigFileName

10. requiredCols – the required studbook columns, from getRequiredCols

11. possibleCols – the possible studbook columns, from getPossibleCols

12. includeColumns – the superset of report-inclusion columns, from getIncludeColumns

Examples

library(nprcgenekeepr)
## default sends warning if configuration file is missing
suppressWarnings(getSiteInfo())
getSiteInfo(expectConfigFile = FALSE)

Look up the maximum gestation period (days) for one or more species

Description

Maps each supplied species name to a conservative upper bound on the number of days from conception to birth, using the speciesGestation lookup table (or a supplied gestationTable). Matching is case- and whitespace-insensitive. Any species that is missing, NA, an empty string, or not present in the table falls back to default (210 days, the conservative rhesus bound). Used by getPotentialParents to key its gestation window on the first-class species pedigree column.

Usage

getSpeciesGestation(species, gestationTable = NULL, default = 210L)

Arguments

Value

an integer vector of gestation-period day bounds, the same length and order as species.

Examples

getSpeciesGestation("RHESUS")
getSpeciesGestation(c("RHESUS", "UNICORN", NA))

Look up the minimum breeding age (years) for one or more species and sexes

Description

Maps each supplied (species, sex) pair to the minimum age in years at which an animal of that species and sex can produce offspring, using the speciesGestation lookup table (or a supplied breedingTable). Matching is case- and whitespace-insensitive on both species and sex. Any species that is missing, NA, an empty string, or not present in the table – and any sex that is not "M" or "F" – falls back to default (2 years, the legacy package-wide minimum parent age). Used by the Genetic Value Analysis unknown-parent mean-kinship correction to form a focal animal's contemporaneous breeding-age peer cohort. The bundled table is populated for the common colony NHP species; a user's overrides, merged onto the bundled table by loadSpeciesOverrides, are supplied through breedingTable and default.

Usage

getSpeciesMinBreedingAge(species, sex, breedingTable = NULL, default = 2)

Arguments

Value

a numeric vector of minimum breeding ages in years, the same length as the longer of species and sex.

Examples

getSpeciesMinBreedingAge("RHESUS", "M")
getSpeciesMinBreedingAge("RHESUS", "F")
getSpeciesMinBreedingAge(c("RHESUS", "UNICORN"), c("M", "F"))

Get tokens from a character vector of lines

Description

Reads the lines of an nprcgenekeepr configuration file. The term before each equals sign names a setting and the terms after it, up to the next name, are its value; terms are separated by blanks, commas or line breaks, a term in double quotes is kept whole (a quote not closed on its line ends at the end of that line), and a # that begins a word starts a comment that runs to the end of the line. Round brackets outside quotes are ignored. A setting with nothing after its equals sign has an empty value.

Usage

getTokenList(lines)

Arguments

Value

A list with two elements: param, a character vector of parameter names, and tokenVec, a list of the token vectors parsed for each parameter (an empty character vector for a setting with no value).

Examples

lines <- c(
  "center = \"SNPRC\"",
  " baseUrl = \"https://boomer.txbiomed.local:8080/labkey\"",
  " schemaName = \"study\"", " folderPath = \"/SNPRC\"",
  " queryName = \"demographics\"",
  "lkPedColumns = (\"Id\", \"gender\", \"birth\", \"death\",",
  "              \"lastDayAtCenter\", \"dam\", \"sire\")",
  "mapPedColumns = (\"id\", \"sex\", \"birth\", \"death\", ",
  "  \"exit\", \"dam\", \"sire\")"
)
lkVec <- c(
  "Id", "gender", "birth", "death",
  "lastDayAtCenter", "dam", "sire"
)
mapVec <- c("id", "sex", "birth", "death", "exit", "dam", "sire")
tokenList <- getTokenList(lines)
params <- tokenList$param
tokenVectors <- tokenList$tokenVec

Get the version number of nprcgenekeepr

Description

Get the version number of nprcgenekeepr

Usage

getVersion(date = TRUE)

Arguments

Value

Current Version

Examples

library(nprcgenekeepr)
getVersion()

Join a character vector into an and/or list

Description

Join a character vector into an and/or list

Usage

get_and_or_list(c_vector, conjunction = "and")

Arguments

Value

A character vector of length one containing a single correctly punctuated character string that lists each element in the first argument vector with commas between if there are more than two elements with the last two elements joined by the selected conjunction. A zero-length input returns an empty string and a single element is returned unchanged.

Examples

get_and_or_list(c("Bob", "John")) # "Bob and John"
get_and_or_list(c("Bob", "John"), "or") # "Bob or John"
get_and_or_list(c("Bob", "John", "Sam", "Bill"), "or")
# "Bob, John, Sam, or Bill"

Format the elapsed time since a start time

Description

Taken from github.com/rmsharp/rmsutilityr

Usage

get_elapsed_time_str(start_time)

Arguments

Value

A character vector describing the passage of time in hours, minutes, and seconds.

Examples

start_time <- proc.time()
## do something
elapsed_time <- get_elapsed_time_str(start_time)

Add animals to a breeding group or form new groups

Description

Part of Group Formation

Usage

groupAddAssign(
  candidates,
  kmat,
  ped,
  currentGroups = list(character(0L)),
  threshold = 0.015625,
  ignore = list(c("F", "F")),
  minAge = 1,
  iter = 1000L,
  numGp = 1L,
  harem = FALSE,
  sexRatio = 0,
  withKin = FALSE,
  maxCandidates = 5L,
  exhaustive = FALSE,
  maxExhaustiveCandidates = 20L,
  exhaustiveTimeLimit = 10,
  ancestryRules = NULL,
  updateProgress = NULL
)

Arguments

Details

groupAddAssign finds the largest group that can be formed by adding unrelated animals from a set of candidate IDs to an existing group, to a new group it has formed from a set of candidate IDs or if more than 1 group is desired, it finds the set of groups with the largest minimum group size (the score is the size of the smallest group).

The function implements a maximal independent set (MIS) algorithm to find groups of unrelated animals. A set of animals may have many different MISs of varying sizes, and finding the largest would require traversing all possible combinations of animals. Since this could be very time consuming, this algorithm produces a random sample of the possible MISs, and selects from these. The size of the random sample is determined by the specified number of iterations.

Value

A list with list items group, score, candidates and optionally groupKin. The list item group contains a list of the best group(s) produced during the simulation (an alias for candidates[[1]]$group, kept for backward compatibility). It has numGp groups plus a final element holding the IDs of the unused candidates, or a bare NA if none remain. The same holds for each candidates[[i]]$group. The list item score provides the score associated with the group(s) (an alias for candidates[[1]]$score); it ignores that final element. The list item candidates is a list of up to maxCandidates distinct candidate solutions (default 5; issue #125, configurable per issue #146 Slice 1), each a list with its own group, score and, when withKin = TRUE, groupKin, ordered best-scoring first. Candidates are deduplicated by partition content, not by score – two trials with the same score but different membership both count as distinct candidates; two trials with identical membership count once. The list item groupKin contains the subset of the kinship matrix that is specific for each group formed in the best candidate (an alias for candidates[[1]]$groupKin). When exhaustive = TRUE was requested (issue #146 Slice 2), three additional top-level items are present – absent entirely, not merely NULL, when exhaustive = FALSE (the default): exhaustive (logical, whether the search completed before its wall-clock deadline), examined (integer, the total number of distinct maximal independent sets found), and retentionRule (character, describing the top-maxCandidates cutoff actually applied to candidates).

References

Vinson, A. and Raboin, M.J. (2015) "A Practical Approach for Designing Breeding Groups to Maximize Genetic Diversity in a Large Colony of Captive Rhesus Macaques (Macaca mulatta)" Journal of the American Association for Laboratory Animal Science, 2015 Nov, Vol.54(6), pp.700-707.

Examples

library(nprcgenekeepr)
examplePedigree <- nprcgenekeepr::examplePedigree
breederPed <- qcStudbook(examplePedigree,
  minSireAge = 2, minDamAge = 2,
  reportChanges = FALSE,
  reportErrors = FALSE
)
focalAnimals <- breederPed$id[!(is.na(breederPed$sire) &
  is.na(breederPed$dam)) &
  is.na(breederPed$exit)]
ped <- setPopulation(ped = breederPed, ids = focalAnimals)
trimmedPed <- trimPedigree(focalAnimals, breederPed)
probands <- ped$id[ped$population]
ped <- trimPedigree(probands, ped,
  removeUninformative = FALSE,
  addBackParents = FALSE
)
geneticValue <- reportGV(ped,
  guIter = 50, # should be >= 1000
  guThresh = 3,
  byID = TRUE,
  updateProgress = NULL
)
trimmedGeneticValue <- reportGV(trimmedPed,
  guIter = 50, # should be >= 1000
  guThresh = 3,
  byID = TRUE,
  updateProgress = NULL
)
candidates <- trimmedPed$id[trimmedPed$birth < as.Date("2013-01-01") &
  !is.na(trimmedPed$birth) &
  is.na(trimmedPed$exit)]
haremGrp <- groupAddAssign(
  kmat = trimmedGeneticValue[["kinship"]],
  ped = trimmedPed,
  candidates = candidates,
  iter = 10, # should be >= 1000
  numGp = 6,
  harem = TRUE
)
haremGrp$group
sexRatioGrp <- groupAddAssign(
  kmat = trimmedGeneticValue[["kinship"]],
  ped = trimmedPed,
  candidates = candidates,
  iter = 10L, # should be >= 1000L
  numGp = 6L,
  sexRatio = 9.0
)
sexRatioGrp$group

Recommend gene-drop iterations for a pedigree

Description

Part of Genetic Value Analysis

Usage

gvaConvergence(
  ped,
  pop = NULL,
  nMax = 3000L,
  guThresh = 1L,
  byID = TRUE,
  grid = NULL,
  k = 20L,
  oMin = 0.9,
  rhoMin = 0.95,
  seed = NULL,
  updateProgress = NULL,
  breedingTable = NULL,
  gestationTable = NULL,
  breedingAgeDefault = NULL,
  gestationDefault = NULL,
  kinshipOverrides = NULL,
  twinRelations = NULL
)

Arguments

Details

Genome uniqueness (calcGU) is the only ranked Genetic Value Analysis output that carries Monte Carlo (gene-drop) sampling noise, so the number of iterations a colony actually needs is pedigree-dependent: there is no single universal "right" count. gvaConvergence answers the literal request – "define reproducible and automate finding the needed number of iterations" – on the ratified definition that the decision-relevant quantity is the selection order (which animals are chosen, and in what order), not the precision of the gu number itself.

Because the n gene-drop iteration columns are independent and identically distributed replicates, the whole convergence picture is recoverable from a single completed gene drop the user already pays for: gvaConvergence runs one gene drop at nMax, computes the per-iteration rare-allele matrix once (calcA), and for each candidate iteration count N in grid splits the columns into two disjoint halves of N columns each. The two halves are genuinely independent N-iteration estimates; each is ranked through the same ordering pipeline the report uses, and the two orderings are compared. A run is judged reproducible at N when both

• the top-k selected animals overlap by at least oMin (the same animals are chosen), and

• the Kendall rank agreement of the commonly-ranked animals is at least rhoMin (they come out in the same order).

The recommended iteration count is the smallest N in grid at which both criteria hold. The de-inflated gu = 0 "Undetermined" set (both parents unknown, no recorded origin) is a policy constant with rank NA; it is excluded from the order the criteria are computed on and reported separately as nUndetermined.

Because the half-split compares two N-column runs to each other (never to their pooled mean), it is a conservative, self-validating estimate of reproducibility at N. This changes nothing about seeding: a fixed seed already makes gu bit-identical run to run; that is reproducibility of the process, whereas this function reports the sampling reproducibility of the estimate.

The population of interest (see pop) must hold at least 2 animals, as for reportGV. With fewer, gvaConvergence stops before doing any calculation, with a message giving the number of animals.

Value

An object of class nprcgenekeeprGVConv: a list with

• convergence – a data.frame with one row per assessed iteration count: iterations, topOverlap (top-k selected-set overlap, from 0 to 1), and rankAgreement (Kendall rank agreement of the commonly-ranked animals, from -1 to 1). Either metric can be NA when it cannot be computed.

• recommendedIter – the smallest assessed iteration count meeting both criteria, or NA_integer_ if none did within grid.

• converged – TRUE if any assessed count met both criteria.

• criteria – the k, oMin, and rhoMin used.

• nRankable – the number of probands carrying a (non-NA) rank that the order metrics are computed on.

• nUndetermined – the count of the excluded Undetermined set.

• nMax – the gene-drop budget actually simulated.

See Also

reportGV, calcGU, calcGUSE

Examples

library(nprcgenekeepr)
## A quick, small illustration (use a larger nMax in practice). With
## nMax = 200 only the grid counts 25, 50 and 100 can be assessed.
conv <- gvaConvergence(nprcgenekeepr::qcPed, nMax = 200L, seed = 1L)
conv$convergence
conv$recommendedIter

Check whether an animal has both parents

Description

Check whether an animal has both parents

Usage

hasBothParents(id, ped)

Arguments

Value

TRUE if ID has both sire and dam identified in ped, FALSE if one or both are unknown, and logical(0) if id is not in ped.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::pedOne
names(ped) <- c("id", "sire", "dam", "sex", "birth")
hasBothParents("o2", ped)
ped$sire[ped$id == "o2"] <- NA
hasBothParents("o2", ped)

Check for genotype data in dataframe

Description

Checks to ensure the content and structure are appropriate for genotype data are in the dataframe and ready for the geneDrop function by already being mapped to numbers (integer codes are expected, but any numeric value passes) and placed in columns named first and second. Only the id column is matched loosely (any column whose lower-cased name contains "id"). The allele columns must be named exactly first and second and be numeric; no check is made of the values' range, so negative, missing or very large numbers still give TRUE.

Usage

hasGenotype(genotype)

Arguments

Value

A logical value representing whether or not the data.frame passed in contains genotypic data that can be used. Columns named First or Second (other cases) give FALSE.

Examples

library(nprcgenekeepr)
rhesusPedigree <- nprcgenekeepr::rhesusPedigree
rhesusGenotypes <- nprcgenekeepr::rhesusGenotypes
pedWithGenotypes <- addGenotype(
  ped = rhesusPedigree,
  genotype = rhesusGenotypes
)
hasGenotype(pedWithGenotypes)

Convert internal column names to display or header names

Description

Converts the column names of a Pedigree or Genetic value Report to something more descriptive.

Usage

headerDisplayNames(headers)

Arguments

Value

A character vector the same length as headers with the display name for each header. The lookup is case sensitive, and a header with no display name gives NA.

Examples

library(nprcgenekeepr)
headerDisplayNames(headers = c("id", "sire", "dam", "sex", "birth", "age"))

Identify the founders in a pedigree

Description

Part of Pedigree Curation

Usage

isFounder(ped)

Arguments

Details

A founder is an animal whose sire and dam are both unknown (NA). Animals with exactly one known parent (partial parentage) are not founders.

Value

A logical vector with one element per row of ped that is TRUE for each animal whose sire and dam are both NA. The result never contains NA.

See Also

getFounders for the founder id values.

Examples

library(nprcgenekeepr)
ped <- data.frame(
  id = c("A", "B", "C", "D", "E", "F", "G"),
  sire = c(NA, NA, "A", "A", NA, "D", "D"),
  dam = c(NA, NA, "B", "B", NA, "E", "E"),
  stringsAsFactors = FALSE
)
isFounder(ped)

Test whether a string is a valid date

Description

Taken from github.com/rmsharp/rmsutilityr

Usage

is_valid_date_str(
  date_str,
  format = "%d-%m-%Y %H:%M:%S",
  optional = FALSE
)

Arguments

Value

A logical vector with one element per element of date_str (zero-length input gives a zero-length result) indicating whether or not each string is a valid date. Elements are NA instead of FALSE when optional is TRUE. Numeric input is never treated as a date and always gives FALSE.

Examples

is_valid_date_str(c(
  "13-21-1995", "20-13-98", "5-28-1014",
  "1-21-15", "2-13-2098", "25-28-2014"
), format = "%m-%d-%y")

Reformat a kinship matrix into long form

Description

Part of Group Formation

Usage

kinMatrix2LongForm(kinMatrix, removeDups = FALSE)

Arguments

Value

A dataframe with columns id1, id2, and kinship. This is the kinship data reformatted from a matrix, to a long-format table.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
ped$gen <- findGeneration(ped$id, ped$sire, ped$dam)
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen)
reformattedKmat <- kinMatrix2LongForm(kmat, removeDups = FALSE)
nrow(reformattedKmat)
reformattedNoDupsKmat <- kinMatrix2LongForm(kmat, removeDups = TRUE)
nrow(reformattedNoDupsKmat)

Generate a kinship matrix

Description

The function previously had an internal call to the kindepth function in order to provide the parameter pdepth (the generation number). This version requires the generation number to be calculated elsewhere and passed into the function.

Usage

kinship(
  id,
  father.id,
  mother.id,
  pdepth,
  sparse = FALSE,
  twinRelations = NULL,
  chrtype = "autosome",
  sex = NULL
)

Arguments

Details

The rows (cols) of founders are just 0.5 * identity matrix, no further processing is needed for them. Parents must be processed before their children, and then a child's kinship is just the average of the kinship values for his or her parents.

The code for the kinship function was written by Terry Therneau at the Mayo clinic and taken from his website. This function is part of a package written in S (and later ported to R) for calculating kinship and other statistics.

Value

A kinship square matrix

Author(s)

Terry M. Therneau, Mayo Clinic (mayo.edu), original version

All of the code on the original S-Plus kinship function (originally hosted on Terry Therneau's Mayo Clinic software page, offline since at least 2019) was stated to be released under the GNU General Public License (version 2 or later).

The R version became the kinship2 package available on CRAN:

as modified by M Raboin, 2014-09-08 14:44:26

References

https://cran.r-project.org/package=kinship2

The chrtype = "x" branch is ported from kinship2's own X-chromosome kinship algorithm, described and worked (Table S2) in its supplementary material:

Sinnwell JP, Therneau TM, Schaid DJ (2014). "The kinship2 R Package for Pedigree Data." Human Heredity, 78(2), 91-93.

$Id: kinship.s,v 1.5 2003/01/04 19:07:53 therneau Exp $

Create the kinship matrix, using the algorithm of K Lange, Mathematical and Statistical Methods for Genetic Analysis, Springer, 1997, p 71-72.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
ped$gen <- findGeneration(ped$id, ped$sire, ped$dam)
kmat <- kinship(ped$id, ped$sire, ped$dam, ped$gen)
ped
kmat

Build a kValue table from a list of kinship matrices

Description

A kValue matrix has one row for each pair of individuals in the kinship matrix and one column for each kinship matrix. Thus, in a kinship matrix with 20 individuals the kinship matrix will have 20 rows by 20 columns but only the upper or lower triangle has unique information as the diagonal values are the self-kinship coefficients, (1 + F) / 2 (0.5 for a non-inbred animal), and the upper triangle has the same values as the lower triangle. The kValue table will have 210 rows. The calculation for the number or row in the kValue table is 20 + (20 * 19) / 2 rows with the 20 values from the kinship coefficient matrix diagonal and (20 * 19) / 2 elements from one of either of the two triangles.

Usage

kinshipMatricesToKValues(kinshipMatrices)

Arguments

Details

The kValue matrix for 1 kinship matrix for 20 individuals will have 210 rows and 3 columns. The first two columns are dedicated to the ID pairs and the third column contains the pair's kinship coefficient.

Thus, the number of rows in the kValues matrix will be n + n(n-1) / 2 and the number of columns will be 2 plus one additional column for each kinship matrix (2 + m, where m is the number of kinship matrices).

Value

A data.table with columns id_1, id_2, and sim_1 through sim_m, one column for each kinship matrix in kinshipMatrices. The first two columns contain the IDs of the individuals in the kinship matrices provided to the function and the sim_ columns contain the corresponding kinship coefficients. Unlike the kinship matrix, each possible pairing of IDs appears once.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::smallPed
simParent_1 <- list(
  id = "A",
  sires = c("s1_1", "s1_2", "s1_3"),
  dams = c("d1_1", "d1_2", "d1_3", "d1_4")
)
simParent_2 <- list(
  id = "B",
  sires = c("s1_1", "s1_2", "s1_3"),
  dams = c("d1_1", "d1_2", "d1_3", "d1_4")
)
simParent_3 <- list(
  id = "E",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
simParent_4 <- list(
  id = "J",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
simParent_5 <- list(
  id = "K",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
simParent_6 <- list(
  id = "N",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
allSimParents <- list(
  simParent_1, simParent_2, simParent_3,
  simParent_4, simParent_5, simParent_6
)

extractKValue <- function(kValue, id1, id2, simulation) {
  kValue[kValue$id_1 == id1 & kValue$id_2 == id2, paste0(
    "sim_",
    simulation
  )]
}

n <- 10
simKinships <- createSimKinships(ped, allSimParents, pop = ped$id, n = n)
kValue <- kinshipMatricesToKValues(simKinships)
extractKValue(kValue, id1 = "A", id2 = "F", simulation = 1:n)

Extract a kValue table from a kinship matrix

Description

A kValue matrix has one row for each pair of individuals in the kinship matrix and one column for each kinship matrix. Thus, in a kinship matrix with 20 individuals the kinship matrix will have 20 rows by 20 columns but only the upper or lower triangle has unique information as the diagonal values are each animal's self-kinship, (1 + F) / 2 (0.5 when not inbred), and the upper triangle has the same values as the lower triangle. The kValue table will have 210 rows. The calculation for the number or row in the kValue table is 20 + (20 * 19) / 2 rows with the 20 values from the kinship coefficient matrix diagonal and (20 * 19) / 2 elements from one of either of the two triangles.

Usage

kinshipMatrixToKValues(kinshipMatrix)

Arguments

Details

The kValue matrix for 1 kinship matrix for 20 individuals will have 210 rows and 3 columns. The first two columns are dedicated to the ID pairs and the third column contains the pair's kinship coefficient.

Thus, the number of rows in the kValues matrix will be n + n(n-1) / 2 and the number of columns will be 3.

Value

A data.table with columns id_1, id_2, and kinship where the first two columns contain the IDs of the individuals in the kinship matrix provided to the function and the kinship column contains the corresponding kinship coefficient. Unlike the kinship matrix, each possible pairing of IDs appears once.

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::smallPed
simParent_1 <- list(
  id = "A",
  sires = c("s1_1", "s1_2", "s1_3"),
  dams = c("d1_1", "d1_2", "d1_3", "d1_4")
)
simParent_2 <- list(
  id = "B",
  sires = c("s1_1", "s1_2", "s1_3"),
  dams = c("d1_1", "d1_2", "d1_3", "d1_4")
)
simParent_3 <- list(
  id = "E",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
simParent_4 <- list(
  id = "J",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
simParent_5 <- list(
  id = "K",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
simParent_6 <- list(
  id = "N",
  sires = c("A", "C", "s1_1"),
  dams = c("d3_1", "B")
)
allSimParents <- list(
  simParent_1, simParent_2, simParent_3,
  simParent_4, simParent_5, simParent_6
)

simPed <- makeSimPed(ped, allSimParents)
simKinship <- kinship(
  simPed$id, simPed$sire,
  simPed$dam, simPed$gen
)
kValues <- kinshipMatrixToKValues(simKinship)

Small hypothetical pedigree (Lacy 1989)

Description

Small hypothetical pedigree (Lacy 1989)

Usage

data(lacy1989Ped)

Format

An object of class data.frame with 7 rows and 5 columns.

Source

lacy1989Ped is a dataframe containing the small hypothetical pedigree of three founders and four descendants used by Robert C. Lacy in "Analysis of Founder Representation in Pedigrees: Founder Equivalents and Founder Genome Equivalents" Zoo Biology 8:111-123 (1989).

The founders (A, B, E) have unknown parentages and are assumed to have independent ancestries.

id

character column of animal IDs

sire

the male parent of the animal indicated by the id column. Unknown sires are indicated with NA

dam

the female parent of the animal indicated by the id column. Unknown dams are indicated with NA

gen

generation number (integers beginning with 0 for the founder generation) of the animal indicated by the id column.

population

logical vector with all values set TRUE

Gene-drop alleles for lacy1989Ped (5000 iterations)

Description

A dataframe produced by geneDrop on lacy1989Ped with 5000 iterations.

Usage

data(lacy1989PedAlleles)

Format

A dataframe with 14 rows and 5002 columns. There are 5000 columns (V1 to V5000), one for each iteration in geneDrop containing alleles randomly selected at each generation of the pedigree using Mendelian rules.

Column 5001 is the id column with two rows for each member of the pedigree (2 * 7).

Column 5002 is the parent column with values of sire and dam alternating.

Source

lacy1989Ped is a dataframe containing the small example pedigree used by Robert C. Lacy in "Analysis of Founder Representation in Pedigrees: Founder Equivalents and Founder Genome Equivalents" Zoo Biology 8:111-123 (1989).

Load the site configuration for the modular Shiny application

Description

Reads the user's site-configuration file (~/.nprcgenekeepr_config, or ~/_nprcgenekeepr_config on Windows) using the tolerant getSiteInfo parser, which handles the documented configuration format (comment lines, blank lines, and multi-line / quoted / comma-separated values; see inst/extdata/examples/example_nprcgenekeepr_config). The call is wrapped in tryCatch so that a missing or malformed configuration file can never crash the application on boot: in that case a warning is logged and NULL is returned.

Usage

loadSiteConfig()

Details

This replaces a former read.table(sep = "=") call in the application server that assumed a strict two-column table, could not parse the documented format, and crashed runGeneKeepR at startup.

Value

A named list of site information (as returned by getSiteInfo) when a configuration file is present and parseable; otherwise NULL.

See Also

getSiteInfo, getConfigFileName, appServer

Examples

library(nprcgenekeepr)
## Reads ~/.nprcgenekeepr_config (or ~/_nprcgenekeepr_config on
## Windows) if it exists; returns NULL when no config file is
## present, so this is safe to run on any machine.
config <- loadSiteConfig()
config

Load user-configurable species reproductive-parameter overrides

Description

Reads the optional species-override settings from the user's site configuration file (~/.nprcgenekeepr_config, or ~/_nprcgenekeepr_config on Windows) and assembles the override tables and fallbacks consumed by the Genetic Value Analysis. The configuration may carry up to three optional keys, each looked up softly (the getConfigApiKey pattern – absent keys are not an error and never touch the fixed-schema getSiteInfo parser):

• speciesOverridesPath – path to a CSV with the four speciesGestation columns (species, gestation, minMaleBreedingAge, minFemaleBreedingAge; header required, matched by name). A colony lists only the rows (species) it wants to change; the CSV is merged onto the bundled table, so every unlisted species keeps its bundled value (not replaced).

• minBreedingAgeDefault – numeric fallback (years) for a species absent from the table (bundled built-in 2.0).

• gestationDefault – integer fallback (days) for a species absent from the table (bundled built-in 210).

Usage

loadSpeciesOverrides()

Details

Like loadSiteConfig, this never crashes the application on boot: a missing configuration file, a missing override key, or a missing/malformed CSV all fall back to the bundled values (a warning is raised for an unreadable CSV).

Value

A named list with elements breedingTable, gestationTable (each the merged speciesGestation-shaped data.frame, or NULL when no CSV is configured), breedingAgeDefault (numeric or NULL), and gestationDefault (integer or NULL). A NULL element means "use the bundled value / built-in default".

See Also

loadSiteConfig, getSpeciesMinBreedingAge, getSpeciesGestation, reportGV

Examples

library(nprcgenekeepr)
## Reads optional species overrides from the user's site config
## file; with no config file every element is NULL, meaning "use
## the bundled speciesGestation values / built-in defaults".
overrides <- loadSpeciesOverrides()
str(overrides)

Log module events

Description

Centralized logging function for Shiny module events. Provides consistent logging format across all modules with configurable log levels.

Usage

logModuleEvent(module, message, level = "INFO", ...)

Arguments

Details

"WARN" and "ERROR" entries are always emitted with message(). "INFO" entries are written to standard output with cat() only when options(nprcgenekeepr.verbose = TRUE) is set. "DEBUG" entries are written the same way only when options(nprcgenekeepr.debug = TRUE) is set. Otherwise those two levels produce no output. An unrecognized level is treated as "INFO".

Value

Invisible NULL. Called for side effect of logging.

See Also

safeExecute for error-safe execution with logging

Examples

logModuleEvent("modInput", "File uploaded successfully")
logModuleEvent("modPedigree", "Processing %d animals", level = "DEBUG", 100)
logModuleEvent("modGeneticValue", "Calculation failed", level = "ERROR")

Make a CEPH-style pedigree for each id

Description

Part of Relations

Usage

makeCEPH(id, sire, dam)

Arguments

Details

Creates a CEPH-style pedigree for each id, consisting of three generations: the id, the parents, and the grandparents. Inserts NA for unknown pedigree members. Ids given as numbers or as a factor are taken as their text.

Value

List of lists: fields: id, subfields: parents, pgp, mgp. Pedigree information converted into a CEPH-style list. The top level list elements are the IDs from id. Below each ID is a list of three elements: parents (sire, dam), paternal grandparents (pgp: sire, dam), and maternal grandparents (mgp: sire, dam).

Examples

library(nprcgenekeepr)
ped <- nprcgenekeepr::lacy1989Ped
pedCEPH <- makeCEPH(ped$id, ped$sire, ped$dam)
head(ped)
head(pedCEPH$F)

Write copy of nprcgenekeepr::examplePedigree into a file

Description

Uses examplePedigree data structure to create an example data file. Files of type "csv" and "txt" are silently overwritten if they already exist. A file of type "excel" is never overwritten; if the file already exists, an error is signaled.

Usage

makeExamplePedigreeFile(
  file = file.path(tempdir(), paste0("examplePedigree.", c(csv = "csv", txt = "txt",
    excel = "xlsx")[[fileType]])),
  fileType = "csv"
)

Arguments

Value

Full path name of file saved.

Examples

library(nprcgenekeepr)
pedigreeFile <- makeExamplePedigreeFile()

Create Founder Statistics HTML Table

Description

Generates an HTML table displaying founder statistics including counts of known founders, female founders, male founders, founder equivalents (FE), and founder genome equivalents (FG). When founderStats is NULL a paragraph saying that no founder statistics are available is returned instead of a table.

Usage

makeFounderStatsTable(founderStats)

Arguments

Value

Character string containing HTML table markup.

See Also

makeGeneticSummaryTable for genetic value summary

calcFE for founder equivalents calculation

calcFG for founder genome equivalents

Examples

stats <- list(
  total = 50,
  nMaleFounders = 20,
  nFemaleFounders = 30,
  fe = 25.5,
  fg = 22.3
)
html <- makeFounderStatsTable(stats)

Make a genetic diversity heat map

Description

Renders a red/yellow/green stoplight heat map of breeding-group genetic diversity metrics. Each row is a breeding group and each column is a metric; every cell is colored by its color index, where 1 is red (the problem condition), 2 is yellow (watch), and 3 is green (healthy). A metric that is undefined for a group (an NA index, such as Production for a group with no breeding-age females) is drawn gray, never as a verdict.

Usage

makeGeneticDiversityHeatmap(stats)

Arguments

Details

This function is agnostic to the number of metric columns: it draws one tile per group-by-metric cell for whatever metric columns it is handed, preserving their input order across the top of the plot. The metric names are written level, centered over their column and in bold, and the group names down the left are the same size (22 pt, 2.5 times the 8.8 pt default), so both stay whole and readable at the size the app draws the plot.

Value

A ggplot object: a geom_tile heat map with metric headers across the top and group labels down the left, filled red/yellow/green (gray for NA) from the color indices.