phenotPPE: Simple paternity exclusion for phenotype allele data

Description

Conduct a paternity exclusion analysis on a phenotype dataset.

Usage

phenotPPE(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 phenotPPE contains two elements, progenyTables and adultTables, each of which are themselves lists.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

phenotPPE conducts a basic paternity exclusion analysis on a ‘phenotype’ dataset.

For the purposes of the PolyPatEx package, the term ‘phenotype’ refers to forms of marker data where the allele dosages (or multiplicities) are not known - hence for a polyploid species of ploidy p, a valid allele set may contain between one and p alleles, which should all be distinct. Any cases of allele sets having duplicated alleles will have previously been caught by preprocessData (automatically called by inputData) and will have produced an error message, requiring the user to remove any duplicated alleles (within allele sets) in the original data file.

For the above and other reasons, phenotPPE should NOT be applied to a dataset that has not been preprocessed by preprocessData (either by calling preprocessData on the allele data frame directly, or by loading the allele data into R using inputData).

Examples

Run this code

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

## Since we did not load this dataset using inputData(), we must
## first process it with preprocessData() before doing anything
## else:
pData <- preprocessData(GF_Phenotype,
                        numLoci=7,
                        ploidy=6,
                        dataType="phenotype",
                        dioecious=FALSE,
                        selfCompatible=FALSE)

pPPE <- phenotPPE(pData)

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