nprcgenekeepr (version 2.0.0)

getFocalAnimalPedFromFile: 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 = ",")

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).

Arguments

fileName

character path to a file (CSV, delimited text, or Excel) whose first column is the list of focal animal Ids.

pedigreeFileName

character path to the pedigree file (CSV, delimited text, or Excel) read via getPedigree; it must provide at least id, sire, and dam columns.

sep

column separator passed to the file readers for delimited text files (default ","); ignored for Excel files.

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.)

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))