FAKinGroupResults: Kinship group test

In jotsetung/FamAgg: Pedigree Analysis and Familial Aggregation

Kinship group test

Description

The FAKinGroupResults object contains the results from the kinship test. This test performs a familial aggregation analysis on a subset of individuals within a family. Two actual tests are conducted, a ratio test that evaluates whether the number of affected individuals within the group is higher than expected by chance, and a kinship test that compares the largest kinship value between affected in the group to the one between randomly sampled individuals.

For more details see kinshipGroupTest.

Usage

## S4 method for signature 'FAKinGroupResults'
affectedKinshipGroups(object)

## S4 method for signature 'FAKinGroupResults'
buildPed(object, id=NULL, max.generations.up=3,
                                     max.generations.down=16, prune=FALSE)



## S4 method for signature 'FAKinGroupResults'
plotPed(object, id=NULL, family=NULL,
                                    filename=NULL, device="plot", ...)

## S4 method for signature 'FAKinGroupResults'
plotRes(object, id=NULL, family=NULL,
                                    addLegend=TRUE, type="density", ...)

## S4 method for signature 'FAKinGroupResults'
result(object, method="BH")

## S4 method for signature 'FAKinGroupResults'
runSimulation(object, nsim=50000, strata=NULL)

## S4 method for signature 'FAKinGroupResults'
shareKinship(object, id=NULL, rmKinship=0)

## S4 replacement method for signature 'FAKinGroupResults'
trait(object) <- value

Arguments

(in alphabetic order)

addLegend	For plotRes: if a legend should be added to the plot.
device	For plotPed: see plotPed for more details.
family	For plotPed: not supported.
filename	For plotPed: the file name to which the pedigree plot should be exported. See plotPed for more details.
id	For buildPed, plotPed, plotRes and shareKinship: the id of the kinship group (i.e. one of the ids in column "group_id" of the result table result(object)). Note: id can be a numeric or a character. Numeric ids will be internally converted to character.
max.generations.down	For buildPed: the maximal number of generations to look for children.
max.generations.up	For buildPed: the maximal number of generations to look for ancestors.
method	The multiple hypothesis testing method. All methods supported by p.adjust are allowed.
nsim	Number of simulations.
object	The FAKinGroupResults object.
prune	For buildPed: whether the full pedigree should be returned (prune=FALSE) or the pedigree should be reduced to a smaller pedigree containing only individuals in the kinship group (prune=TRUE); see details for more information. Note: the plotPed method does also support this parameter.
rmKinship	For shareKinship: Restrict reporting pairs to those that have kinship values >rmKinship. See shareKinship below for more details.
strata	For runSimulation: a numeric, character of factor characterizing each individual in the pedigree. The length of this vector and the ordering has to match the pedigree. This vector allows to perform stratified random sampling. See details on the PedigreeAnalysis help page or examples for more information.
type	For plotRes: either "density" (the default) or "hist" specifying whether the distribution of expected values from the simulation should be visualized as a density plot or histogram.
value	For trait<-: can be a named numeric, character or factor vector. The names (at least some of them) have to match the ids in the pedigree of the object.
...	For plotPed: additional arguments to be submitted to the internal buildPed call and to plotPed.

Details

Calling the runSimulation method on a FAKinGroupResults object is the same as calling the kinshipGroupTest on a FAData object. In the first case the simulation is performed using the trait information data stored internally in the object, while in the latter case the trait information have to be submitted to the function call.

A call to the setter methods trait<- resets any simulation results present in the sim slot, thus, the object can be re-used to perform a simulation analysis using the new trait data.

The buildPed method returns by default the full pedigree (all ancestors and all children) up to the maximal number of generations. By setting prune=TRUE the method restricts the pedigree to all individuals with a kinship >= the minimal kinship between the individual (with the id equal to the group id) and any other affected individual in its pedigree.

The plotPed method allows to plot the pedigree for a kinship group. This pedigree consists of the full pedigree (all ancestors and children) of all individuals in the kinship group. Similar to the buildPed method the pedigree can be restricted to the kinship group (and eventual missing parents etc) by setting prune=TRUE.

Value

Refer to the method and function description above for detailed information on the returned result object.

Objects from the Class

FAKinGroupResults objects are created by the kinshipGroupTest method for FAData objects.

Extends

Class FAData directly.

Slots

nsim

Number of simulations.

sim

The list containing the result of the simulation. Element "pvalueKinship" contains the p-values from the kinship test, "pvalueRatio" the p-values from the ratio test, "expDensity" and "expHist" density and hist objects representing the background distribution from the Monte Carlo simulation. This slot should not be directly accessed, use the result method to extract result information.

affectedKinshipGroups

A list of lists, each element representing one kinship group, $aff the ids of all affected persons in that group sharing kinship with the indivudual (being the id of the group), $phe ids of all phenotyped individuals in the pedigree with kinship to the individual up to a kinship being smaller or equal to the smallest kinship of the indivudal with any other affected in that group. $kinfreq: a table with the frequency (counts) of kinship values (smaller 0.5). $meankin: the mean kinship in that group.

Methods and Functions

affectedKinshipGroups

Get groups of affected individuals in the pedigree along with all phenotyped individuals with kinship larger or equal to the smallest kinship between affected individuals in the group. Returns a list of lists with elements aff, phe, kinfreq and meankin for each list item: aff: character vector with the ids of all affected in the group, phe: character vector with the ids of all phenotyped in the group, kinfreq: a table with the frequency (counts) of kinship values (self-self kinships removed; the names of the table correnspond to the kinship values ordered increasingly), and meankin: the mean kinship value in the group. The names of the list correspond to the id of the affected individual for which the affected kinship group was determined.

buildPed

Builds the pedigree for the submitted id (which represents the id of the group, i.e. one of names(affectedKinshipGroups(object)), respectively ids in column "group_id" of result(object)). Building a pedigree by submitting the family id is not supported. See details below for more information. The resulting pedigree is returned as a data.frame.

plotPed

Plots a pedigree for one of the affected kinship groups in the simulation results. The ids of all individuals of the affected kinship group are highlighted in the plot in red. See plotPed for more details on the plotting and details below for additional settings.

plotRes

Plots the distribution of counts of randomly sampled affected counts within the kinship group along with the actually observed kinship sum.

result

Returns the result from the simulation as a data.frame with columns: "trait_name": the name of the trait. "total_phenotyped": the total number of phenotyped individuals in the trait. "total_affected": the total number of affected individuals in the trait. "phenotyped": the number of phenotyped individuals in all analyzed kinship groups. "affected": the number of affected individuals in all analyzed kinship groups. "group_id": the id for the kinship group (represents the id of one of the affected individuals in the group). "family": the family id of the affected/group. "group_phenotyped": the number of phenotyped individuals in the current kinship group. "group_affected": the number of affected individuals in the current kinship group. "ratio_pvalue": the p-value from the ratio test. "ratio_padj": the p-value from the ratio test adjusted for multiple hypothesis testing using the method specified with argument method. "mean_kinship": the mean kinship value between all individuals in the current kinship group. "kinship_pvalue": the p-value from the kinship test. "kinship_padj": the p-value from the kinship test adjusted for multiple hypothesis testing using the method specified with argument method.

The data.frame is sorted by column "ratio_pvalue", its rownames correspond to the "group_id".

runSimulation

Performs the simulation analysis based on the pedigree and trait information stored in the object. Optionally allows to perform stratified sampling. Returns a FAKinGroupResults with the results of the simulation.

shareKinship

Returns a character vector with ids of all individuals that share kinship with any of the individuals in the kinship group identified by the argument id. If rmKinship is specified, only individuals with a kinship >rmKinship to the group defined by id will be reported. This esentially restricts only the inclusion of individuals outside of the group. Everyone inside the group will be reported independently of the threshold defined by rmKinship. This feature has mainly been implemented for reasons of API compatibility with the remaining versions of shareKinship.

trait<-

Set the trait information. This method will reset all simulation results saved in the sim slot.

Note

Subsetting (using the [ operator) is not supported.

Author(s)

Johannes Rainer, Daniel Taliun

See Also

FAData, kinship, trait, probabilityTest, kinshipSumTest, genealogicalIndexTest, familialIncidenceRateTest, fsirTest, buildPed, plotPed, switchPlotfun

Examples

##########################
##
##  Perform the simulation analysis
##
## Load the test data.
data(minnbreast)

## Subset to some families and generate the pedigree data.frame
mbsub <- minnbreast[minnbreast$famid == 165 | minnbreast$famid == 432, ]
PedDf <- mbsub[, c("famid", "id", "fatherid", "motherid", "sex")]
colnames(PedDf) <- c("family", "id", "father", "mother", "sex")

## Generate the FAData.
fad <- FAData(pedigree=PedDf)

## Specify the trait.
tcancer <- mbsub$cancer
names(tcancer) <- mbsub$id

## Perform the kinship group test.
far <- kinshipGroupTest(fad, trait=tcancer, traitName="cancer", nsim=1000)
res <- result(far)
head(res)

## Plot the pedigree for the most significant kinship group
plotPed(far, id=res[1, "group_id"])

## The full pedigree for this affected individual and its kinship group is
## large:
nrow(buildPed(far, id=res[1, "group_id"]))

## We can however restrict it to a reduced pedigree containing only the
## kinship group and all individuals with a kinship >= the smallest kinship
## between the individual and any other affected individual in the pedigree:
nrow(buildPed(far, id=res[1, "group_id"], prune=TRUE))

## By specifying prune=TRUE we can restrict the pedigree plot to these
## individuals
plotPed(far, id=res[1, "group_id"], prune=TRUE)

## Get the ids of all individuals sharing kinship with any of the inddividuals
## in that kinship group:
shareKinship(far, id=res[1, "group_id"])

## Plot the simulation analysis result for the ratio test.
plotRes(far, id=res[1, "group_id"], type="hist")

jotsetung/FamAgg documentation built on March 15, 2023, 3:48 a.m.