Pedigree Reconstruction
sequoia.Rd
Perform pedigree reconstruction based on SNP data, including parentage assignment and sibship clustering.
Usage
sequoia(
GenoM = NULL,
LifeHistData = NULL,
SeqList = NULL,
Module = "ped",
Err = 1e-04,
Tfilter = -2,
Tassign = 0.5,
MaxSibshipSize = 100,
DummyPrefix = c("F", "M"),
Complex = "full",
Herm = "no",
UseAge = "yes",
args.AP = list(Flatten = NULL, Smooth = TRUE),
mtSame = NULL,
CalcLLR = TRUE,
quiet = FALSE,
Plot = NULL,
StrictGenoCheck = TRUE,
ErrFlavour = "version2.0",
MaxSibIter = 42,
MaxMismatch = NA,
FindMaybeRel = FALSE
)
Arguments
- GenoM
numeric matrix with genotype data: One row per individual, and one column per SNP, coded as 0, 1, 2 or -9 (missing). See also
GenoConvert
.- LifeHistData
data.frame with up to 6 columns:
- ID
max. 30 characters long
- Sex
1 = female, 2 = male, 3 = unknown, 4 = hermaphrodite, other numbers or NA = unknown
- BirthYear
birth or hatching year, integer, with missing values as NA or any negative number.
- BY.min
minimum birth year, only used if BirthYear is missing
- BY.max
maximum birth year, only used if BirthYear is missing
- Year.last
Last year in which individual could have had offspring. Can e.g. in mammals be the year before death for females, and year after death for males.
"Birth year" may be in any arbitrary discrete time unit relevant to the species (day, month, decade), as long as parents are never born in the same time unit as their offspring, and only integers are used. Individuals do not need to be in the same order as in `GenoM', nor do all genotyped individuals need to be included.
- SeqList
list with output from a previous run, to be re-used in the current run. Used are elements `PedigreePar', `LifeHist', `AgePriors', `Specs', and `ErrM', and these override the corresponding input parameters. Not all of these elements need to be present, and all other elements are ignored. If
SeqList$Specs
is provided, all input parameters with the same name as its items are ignored, exceptModule
/MaxSibIter
.- Module
one of
- pre
Only input check, return
SeqList$Specs
- dup
Also check for duplicate genotypes
- par
Also perform parentage assignment (genotyped parents to genotyped offspring)
- ped
(Also) perform full pedigree reconstruction, including sibship clustering and grandparent assignment. By far the most time consuming, and may take several hours for large datasets.
NOTE: Until `MaxSibIter` is fully deprecated: if `MaxSibIter` differs from the default (
42
), and `Module` equals the default ('ped'
), MaxSibIter overrides `Module`.- Err
estimated genotyping error rate, as a single number, length 3 vector or 3x3 matrix; see details below. The error rate is presumed constant across SNPs, and missingness is presumed random with respect to actual genotype. Using
Err
>5% is not recommended.- Tfilter
threshold log10-likelihood ratio (LLR) between a proposed relationship versus unrelated, to select candidate relatives. Typically a negative value, related to the fact that unconditional likelihoods are calculated during the filtering steps. More negative values may decrease non-assignment, but will increase computational time.
- Tassign
minimum LLR required for acceptance of proposed relationship, relative to next most likely relationship. Higher values result in more conservative assignments. Must be zero or positive.
- MaxSibshipSize
maximum number of offspring for a single individual (a generous safety margin is advised).
- DummyPrefix
character vector of length 2 with prefixes for dummy dams (mothers) and sires (fathers); maximum 20 characters each. Length 3 vector in case of hermaphrodites (or default prefix 'H').
- Complex
Breeding system complexity. Either "full" (default), "simp" (simplified, no explicit consideration of inbred relationships), "mono" (monogamous).
- Herm
Hermaphrodites, either "no", "A" (distinguish between dam and sire role, default if at least 1 individual with sex=4), or "B" (no distinction between dam and sire role). Both of the latter deal with selfing.
- UseAge
either "yes" (default), "no" (only use age differences for filtering), or "extra" (additional rounds with extra reliance on ageprior, may boost assignments but increased risk of erroneous assignments). Used during full reconstruction only.
- args.AP
list with arguments to be passed on to
MakeAgePrior
, e.g. `Discrete` (non-overlapping generations), `MinAgeParent`, `MaxAgeParent`.- mtSame
NEW matrix indicating whether individuals (might) have the same mitochondrial haplotype (1), and may thus be matrilineal relatives, or not (0). Row names and column names should match IDs in `GenoM`. Not all individuals need to be included and order is not important. Please report any issues. For details see the mtDNA vignette.
- CalcLLR
TRUE/FALSE; calculate log-likelihood ratios for all assigned parents (genotyped + dummy; parent vs. otherwise related). Time-consuming in large datasets. Can be done separately with
CalcOHLLR
.- quiet
suppress messages: TRUE/FALSE/"verbose".
- Plot
display plots from
SnpStats, MakeAgePrior
, andSummarySeq
. Defaults (NULL) to TRUE when quiet=FALSE or "verbose", and FALSE when quiet=TRUE. If you get error 'figure margins too large', enlarge the plotting area (drag with mouse). Error 'invalid graphics state' can be dealt with by clearing the plotting area with dev.off().- StrictGenoCheck
Automatically exclude any individuals genotyped for <5 the unavoidable default up to version 2.4.1. Otherwise only excluded are (very nearly) monomorphic SNPs, SNPs scored for fewer than 2 individuals, and individuals scored for fewer than 2 SNPs.
- ErrFlavour
DEPRECATED, (use length 3 vector for
Err
instead) function that takesErr
(single number) as input, and returns a 3x3 matrix of observed (columns) conditional on actual (rows) genotypes, or choose from inbuilt options 'version2.0', 'version1.3', or 'version1.1', referring to the sequoia version in which they were the default. Ignored ifErr
is a matrix. SeeErrToM
.- MaxSibIter
DEPRECATED, use
Module
number of iterations of sibship clustering, including assignment of grandparents to sibships and avuncular relationships between sibships. Clustering continues until convergence or until MaxSibIter is reached. Set to 0 for parentage assignment only.- MaxMismatch
DEPRECATED AND IGNORED. Now calculated automatically using
CalcMaxMismatch
.- FindMaybeRel
DEPRECATED AND IGNORED, advised to run
GetMaybeRel
separately.
Value
A list with some or all of the following components, depending on
Module
. All input except GenoM
is included in the output.
- AgePriors
Matrix with age-difference based probability ratios for each relationship, used for full pedigree reconstruction; see
MakeAgePrior
for details. When running only parentage assignment (Module="par"
) the returned AgePriors has been updated to incorporate the information of the assigned parents, and is ready for use during full pedigree reconstruction.- args.AP
(input) arguments used to specify age prior matrix. If a custom ageprior was provided via
SeqList$AgePrior
, this matrix is returned instead- DummyIDs
Dataframe with pedigree for dummy individuals, as well as their sex, estimated birth year (point estimate, upper and lower bound of 95% confidence interval; see also
CalcBYprobs
), number of offspring, and offspring IDs. From version 2.1 onwards, this includes dummy offspring.- DupGenotype
Dataframe, duplicated genotypes (with different IDs, duplicate IDs are not allowed). The specified number of maximum mismatches is used here too. Note that this dataframe may include pairs of closely related individuals, and monozygotic twins.
- DupLifeHistID
Dataframe, row numbers of duplicated IDs in life history dataframe. For convenience only, but may signal a problem. The first entry is used.
- ErrM
(input) Error matrix; probability of observed genotype (columns) conditional on actual genotype (rows)
- ExcludedInd
Individuals in GenoM which were excluded because of a too low genotyping success rate (<50%).
- ExcludedSNPs
Column numbers of SNPs in GenoM which were excluded because of a too low genotyping success rate (<10%).
- LifeHist
(input) Dataframe with sex and birth year data. All missing birth years are coded as '-999', all missing sex as '3'.
- LifeHistPar
LifeHist with additional columns 'Sexx' (inferred Sex when assigned as part of parent-pair), 'BY.est' (mode of birth year probability distribution), 'BY.lo' (lower limit of 95% highest density region), 'BY.hi' (higher limit), inferred after parentage assignment. 'BY.est' is NA when the probability distribution is flat between 'BY.lo' and 'BY.hi'.
- LifeHistSib
as LifeHistPar, but estimated after full pedigree reconstruction
- NoLH
Vector, IDs in genotype data for which no life history data is provided.
- Pedigree
Dataframe with assigned genotyped and dummy parents from Sibship step; entries for dummy individuals are added at the bottom.
- PedigreePar
Dataframe with assigned parents from Parentage step.
- Specs
Named vector with parameter values.
- TotLikParents
Numeric vector, Total likelihood of the genotype data at initiation and after each iteration during Parentage.
- TotLikSib
Numeric vector, Total likelihood of the genotype data at initiation and after each iteration during Sibship clustering.
- AgePriorExtra
As AgePriors, but including columns for grandparents and avuncular pairs. NOT updated after parentage assignment, but returned as used during the run.
- DummyClones
Hermaphrodites only: female-male dummy ID pairs that refer to the same non-genotyped individual
List elements PedigreePar and Pedigree both have the following columns:
- id
Individual ID
- dam
Assigned mother, or NA
- sire
Assigned father, or NA
- LLRdam
Log10-Likelihood Ratio (LLR) of this female being the mother, versus the next most likely relationship between the focal individual and this female. See Details below for relationships considered, and see
CalcPairLL
for underlying likelihood values and further details)- LLRsire
idem, for male parent
- LLRpair
LLR for the parental pair, versus the next most likely configuration between the three individuals (with one or neither parent assigned)
- OHdam
Number of loci at which the offspring and mother are opposite homozygotes
- OHsire
idem, for father
- MEpair
Number of Mendelian errors between the offspring and the parent pair, includes OH as well as e.g. parents being opposing homozygotes, but the offspring not being a heterozygote. The offspring being OH with both parents is counted as 2 errors.
Details
For each pair of candidate relatives, the likelihoods are calculated of them being parent-offspring (PO), full siblings (FS), half siblings (HS), grandparent-grandoffspring (GG), full avuncular (niece/nephew - aunt/uncle; FA), half avuncular/great-grandparental/cousins (HA), or unrelated (U). Assignments are made if the likelihood ratio (LLR) between the focal relationship and the most likely alternative exceed the threshold Tassign.
Dummy parents of sibships are denoted by F0001, F0002, ... (mothers) and M0001, M0002, ... (fathers), are appended to the bottom of the pedigree, and may have been assigned real or dummy parents themselves (i.e. sibship-grandparents). A dummy parent is not assigned to singletons.
Full explanation of the various options and interpretation of the output is provided in the vignettes and on the package website, https://jiscah.github.io/index.html .
Genotyping error rate
The genotyping error rate Err
can be specified three different ways:
A single number, which is combined with
ErrFlavour
to create a 3x3 matrix with the probabilities of observed genotype (columns) conditional on actual genotype (rows). By default (ErrFlavour
= 'version2.0'),Err
is interpreted as the locus level error rate (as opposed to allele level), e.g. the probability to observe a true heterozygote Aa as aa (het -> hom) = the probability to observe it as AA \(=E/2\). SeeErrToM
for details and examples.a 3x3 matrix, with the probabilities of observed genotype (columns) conditional on actual genotype (rows)
a length 3 vector, with the probabilities to observe a actual homozygote as the other homozygote, to observe a homozygote as heterozygote, and to observe an actual heterozygote as homozygote (NEW from version 2.6). This only assumes that the two alleles are equivalent with respect to genotyping errors, i.e. $P(AA|aa) = P(aa|AA)$ and $P(aa|Aa)=P(AA|Aa)$.
(Too) Few Assignments?
Possibly Err
is much lower than the actual genotyping error rate.
Alternatively, a true parent will not be assigned when it is:
unclear who is the parent and who the offspring, due to unknown birth year for one or both individuals
unclear whether the parent is the father or mother
unclear if it is a parent or e.g. full sibling or grandparent, due to insufficient genetic data
And true half-siblings will not be clustered when it is:
unclear if they are maternal or paternal half-siblings
unclear if they are half-siblings, full avuncular, or grand-parental
unclear what type of relatives they are due to insufficient genetic data
All pairs of non-assigned but likely/definitely relatives can be found with
GetMaybeRel
. For further information see the vignette.
Disclaimer
While every effort has been made to ensure that sequoia provides what it claims to do, there is absolutely no guarantee that the results provided are correct. Use of sequoia is entirely at your own risk.
References
Huisman, J. (2017) Pedigree reconstruction from SNP data: Parentage assignment, sibship clustering, and beyond. Molecular Ecology Resources 17:1009--1024.
See also
GenoConvert
to read in various data formats,CheckGeno
,SnpStats
to calculate missingness and allele frequencies,SimGeno
to simulate SNP data from a pedigree,EstEr
to estimate genotyping error rate,MakeAgePrior
to estimate effect of age on relationships,GetMaybeRel
to find pairs of potential relatives,SummarySeq
andPlotAgePrior
to visualise results,GetRelM
to turn a pedigree into pairwise relationships,CalcOHLLR
to calculate Mendelian errors and LLR for any pedigree,CalcPairLL
for likelihoods of various relationships between specific pairs,CalcBYprobs
to estimate birth years,PedCompare
andComparePairs
to compare to two pedigrees,EstConf
to estimate assignment errors,writeSeq
to save results,vignette("sequoia")
for detailed manual & FAQ.
Author
Jisca Huisman, jisca.huisman@gmail.com
Examples
# === EXAMPLE 1: simulated data ===
head(SimGeno_example[,1:10])
#> V2 V3 V4 V5 V6 V7 V8 V9 V10 V11
#> a00013 0 0 0 1 0 0 0 1 0 2
#> a00008 1 1 1 1 2 1 1 1 1 0
#> a00011 0 2 1 2 2 1 0 2 0 0
#> a00023 0 0 1 1 1 0 0 0 2 0
#> a00006 1 1 1 0 0 0 0 0 1 1
#> a00004 0 1 1 1 2 1 1 0 0 1
head(LH_HSg5)
#> Error in eval(expr, envir, enclos): object 'LH_HSg5' not found
# parentage assignment:
SeqOUT <- sequoia(GenoM = SimGeno_example, Err = 0.005,
LifeHistData = LH_HSg5, Module="par", Plot=TRUE)
#> Error in eval(expr, envir, enclos): object 'LH_HSg5' not found
names(SeqOUT)
#> Error in eval(expr, envir, enclos): object 'SeqOUT' not found
SeqOUT$PedigreePar[34:42, ]
#> Error in eval(expr, envir, enclos): object 'SeqOUT' not found
# compare to true (or old) pedigree:
PC <- PedCompare(Ped_HSg5, SeqOUT$PedigreePar)
#> Error in eval(expr, envir, enclos): object 'Ped_HSg5' not found
PC$Counts["GG",,]
#> Error in eval(expr, envir, enclos): object 'PC' not found
# \donttest{
# parentage assignment + full pedigree reconstruction:
# (note: this can be rather time consuming)
SeqOUT2 <- sequoia(GenoM = SimGeno_example, Err = 0.005,
LifeHistData = LH_HSg5, Module="ped", quiet="verbose")
#> Error in eval(expr, envir, enclos): object 'LH_HSg5' not found
SeqOUT2$Pedigree[34:42, ]
#> Error in eval(expr, envir, enclos): object 'SeqOUT2' not found
PC2 <- PedCompare(Ped_HSg5, SeqOUT2$Pedigree)
#> Error in eval(expr, envir, enclos): object 'Ped_HSg5' not found
PC2$Counts["GT",,]
#> Error in eval(expr, envir, enclos): object 'PC2' not found
PC2$Counts[,,"dam"]
#> Error in eval(expr, envir, enclos): object 'PC2' not found
# different kind of pedigree comparison:
ComparePairs(Ped1=Ped_HSg5, Ped2=SeqOUT$PedigreePar, patmat=TRUE)
#> Error in eval(expr, envir, enclos): object 'Ped_HSg5' not found
# results overview:
SummarySeq(SeqOUT2)
#> Error in eval(expr, envir, enclos): object 'SeqOUT2' not found
# important to run with approx. correct genotyping error rate:
SeqOUT2.b <- sequoia(GenoM = SimGeno_example, # Err = 1e-4 by default
LifeHistData = LH_HSg5, Module="ped", Plot=FALSE)
#> Error in eval(expr, envir, enclos): object 'LH_HSg5' not found
PC2.b <- PedCompare(Ped_HSg5, SeqOUT2.b$Pedigree)
#> Error in eval(expr, envir, enclos): object 'Ped_HSg5' not found
PC2.b$Counts["GT",,]
#> Error in eval(expr, envir, enclos): object 'PC2.b' not found
# }
if (FALSE) {
# === EXAMPLE 2: real data ===
# ideally, select 400-700 SNPs: high MAF & low LD
# save in 0/1/2/NA format (PLINK's --recodeA)
GenoM <- GenoConvert(InFile = "inputfile_for_sequoia.raw",
InFormat = "raw") # can also do Colony format
SNPSTATS <- SnpStats(GenoM)
# perhaps after some data-cleaning:
write.table(GenoM, file="MyGenoData.txt", row.names=T, col.names=F)
# later:
GenoM <- as.matrix(read.table("MyGenoData.txt", row.names=1, header=F))
LHdata <- read.table("LifeHistoryData.txt", header=T) # ID-Sex-birthyear
SeqOUT <- sequoia(GenoM, LHdata, Err=0.005)
SummarySeq(SeqOUT)
SeqOUT$notes <- "Trial run on cleaned data" # add notes for future reference
saveRDS(SeqOUT, file="sequoia_output_42.RDS") # save to R-specific file
writeSeq(SeqOUT, folder="sequoia_output") # save to several plain text files
# runtime:
SeqOUT$Specs$TimeEnd - SeqOUT$Specs$TimeStart
}