genotPPE: Simple paternity exclusion for genotype allele data

Description

Conduct a paternity exclusion analysis on a genotype dataset.

Usage

genotPPE(adata)

Arguments

adata

data frame: the preprocessed allele data set returned by either inputData or preprocessData.

Value

A list whose components are described below. The components that are probably of primary interest to the user are adultTables$FLCount and adultTables$VLTotal. These are likely to be large tables, so note that the functions potentialFatherCounts and potentialFatherIDs are available to usefully summarise their content.The list returned by genotPPE contains two elements, progenyTables and adultTables, each of which are themselves lists.Element adultTables contains the following components:

FLCount: Father Loci Count - a matrix, showing for each progeny-candidate combination, the number of loci at which the candidate matches (i.e., could have fathered) the progeny
VLTotal: Valid Loci Total - a matrix, showing for each progeny-candidate combination, the total number of loci at which a valid comparison between progeny and candidate could be made. (Missing allele sets, whether in the original data, or due to progeny-mother mismatches found by preprocessData, can result in fewer loci at which progeny-candidate (father) comparisons are possible.)
fatherSummaryTable: A matrix, combining the results of FLCount and VLTotal (see above) for each progeny-candidate combination in one table. This is purely for ease of viewing purposes, but note also the functions potentialFatherCounts and potentialFatherIDs which may provide more useful summary output.
CPNotM.alleleArray: A 3D array containing the alleles present in both candidate (father) and progeny, but not in the progeny's mother (for each progeny/candidate/locus combination)
CMP.alleleArray: A 3D array containing the alleles present in candidate, progeny and progeny's mother (for each progeny/candidate/locus combination)
simpleFatherArray: A 3D array indicating whether each candidate is compatible with each progeny, for each locus

progenyTables contains the following components:

progenyStatusTable: A data frame, indicating the status of the progeny / mother allele set comparison (for each progeny, at each locus).
MP.alleleTable: A data frame containing the alleles that are found in both mother's and progeny's allele sets (for each progeny, at each locus)
PNotM.alleleTable: A data frame, containing the alleles in the progeny's allele set, that are not present in the mother's allele set(for each progeny, at each locus)

The status codes in progenyTables$progenyStatusTable are:

"MAO": Mother Alleles Only - the progeny contains only alleles found also in the mother
"NMA": Non-Mother Alleles - the progeny contains alleles that are not found in the mother
"P.missing": No comparison was possible at this locus because the progeny's allele set was missing
"P.missing": No comparison was possible at this locus because the mother's allele set was missing
"PM.missing": No comparison was possible at this locus because both progeny's and mother's allele sets were missing

Note that some of the "P.missing" or "PM.missing" codes may have arisen due to progeny / mother mismatches found (and corresponding progeny allele sets removed) by preprocessData.

Details

genotPPE conducts a basic paternity exclusion analysis on a genotype dataset.

For the purposes of the PolyPatEx package, the term ‘genotype’ refers to forms of marker data where the allele copy numbers (or multiplicities) are known - hence for a polyploid species of ploidy p, there should be exactly p alleles detected at each locus, some of which may be repeats of the same allele state. In PolyPatEx, no allowance is made for undetected alleles in genotype data - allele sets having fewer than p alleles present should have been reset to contain no alleles by preprocessData.

For the above and other reasons, genotPPE should NOT be applied to a dataset that has not been preprocessed by preprocessData (either by calling directly preprocessData on the data frame directly, or by using inputData to load the data from file).

The genotype-based paternity analysis is based on simple comparison of genotype allele sets between mother, progeny, and candidate father. The mother-progeny relationship is assumed to be known. For genotype data, should a progeny contain only alleles also present in its mother, then a potential father is any candidate that can provide a gamete compatible with the progeny's genotype, given the mother's genotype.

Examples

Run this code

## Using the example dataset 'FR_Genotype':
data(FR_Genotype)

## Since we did not load this dataset using inputData(), we must
## first process it with preprocessData() before doing anything
## else:
gData <- preprocessData(FR_Genotype,
                        numLoci=7,
                        ploidy=4,
                        dataType="genotype",
                        dioecious=TRUE,
                        mothersOnly=TRUE)

head(gData)  ## Checked and Cleaned version of FR_Genotype

gPPE <- genotPPE(gData)  ## Perform the exclusion analyses

## gPPE is a large (and rather ugly!) data structure - see
## functions potentialFatherCounts() and potentialFatherIDs() for
## more useful output from the gPPE object.