FAKinSumResults: Kinship sum test

In jotsetung/FamAgg: Pedigree Analysis and Familial Aggregation

Kinship sum test

Description

The FAKinSumResults object contains the results from a kinship cluster test which evaluates familial aggregation based on the sum of kinship values between affected cases. This test highlights individuals that exhibit a higher than chance relationship to other affected individuals, therefore highlighting individuals within families aggregating the phenotype. To achieve this, for each affected individual the sum of kinship values to all other affected cases is computed. In a Monte Carlo simulation this is repeated with the same number of cases and the resulting background distribution is used to compute p-values for the kinship sums obtained from the observed cases.

Usage

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

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

## S4 method for signature 'FAKinSumResults'
result(object, method="BH", cutoff=0.05, rmKinship=0)

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

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

Arguments

(in alphabetic order)

addLegend	For plotRes: if a legend should be added to the plot.
cutoff	For result: P-value cutoff for clustering of kinship-related affected individuals based on their padj value. Individuals with p-value lower than this cutoff will be included in the grouping. Each group will have at least one individual that satisfies this threshold, as this is the one that started that group. Others are included due to kinship to this particular individual. This is especially useful for large pedigrees with inaccurate or missing family assignment.
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 plotPed and plotRes: the id of the indiviual (i.e. affected individual in the result data.frame) for which the pedigree or the simulation result should be plotted. Note: id can be a numeric or a character. Numeric ids will be internally converted to character.
method	The multiple hypothesis testing method. All methods supported by p.adjust are allowed.
nsim	Number of simulations.
object	The FAKinSumResults object.
only.phenotyped	For plotPed: Wheter only phenotyped individuals, i.e. individuals with a non-NA value in column affected (the trait information). If TRUE, the function removes all non-phenotyped individuals, keeping only those that are required for the pedigree to be complete.
rmKinship	For result: When assigning kinship groups, skip pairs of cases with kinship <= rmKinship.
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 FAKinSumResults object is the same as calling the kinshipSumTest 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 expected frequency (column "freq") in the result data.frame is NA if the corresponding sum of kinship coefficients reported in column "kinship_sum" was never sampled in the simulation. Still, a p-value can be reported.

The plotPed function does not support to draw pedigrees for individuals for which no simulation test has been performed. To draw a pedigree for any individual (with or without trait information, being affected or not in the trait) refer to the plotPed method for FAData objects.

Value

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

Objects from the Class

FAKinSumResults objects are created by the kinshipSumTest method on a FAData object.

Extends

Class FAData directly.

Slots

nsim

Number of simulations.

sim

The result of the simulation. This slot should not be accessed directly, use the result method to extract result information.

Methods and Functions

plotPed

Plots a pedigree for one of the affected individuals in the simulation results. The id of the selected affected individual (specified with argument id) is highlighted in red. See plotPed for more details.

plotRes

Plots the distribution of kinship sums between random sets of samples individuals from the Monte Carlo simulation along with the actually observed kinship sum for the affected individual specified with parameter id. For id only affected individuals for which the analysis has been performed are allowed. The ids of these individuals are listed in column "affected_id" of the data.frame returned by result.

result

Returns the result from the simulation as a data.frame with columns: "trait_name": the name of the trait. "total_phenotyped": total number of phenotyped individuals in the trait. "total_affected": total number of affected individuals in the trait. "affected_id": the id of the affected individual for whom the test has been performed. "family": the family id of the affected. "ksgrp": Numeric identifier that specifies a group of affected individuals related by kinship. Group assignment starts with the top ranking individual (by padj), NA is assigned to those that did not pass the threshold cutoff supplied to result. If parameter rmKinship is passed, assignment is restricted to kinship values >rmKinship between the top ranking individual that founded this group and the rest. Kinship-related individuals that have a lower kinship value will be left unassigned, therefore they may end up in a separate group. "kinship_sum": the sum of kinship values. "freq": the expected frequency of the kinship sum from the simulation. "pvalue": the p-value for the significance of the kinship sum. "padj": the p-value adjusted for multiple hypothesis testing (with the method specified with argument method).

The returned data.frame is sorted by column "pvalue", its row names correspond to column "affected_id".

runSimulation

Performs the simulation analysis based on the pedigree and trait information stored in the object. Returns a FAKinSumResults object with the results of the simulation.

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, Christian Weichenberger

See Also

FAData, kinship, trait, probabilityTest, kinshipGroupTest, kinshipSumTest, genealogicalIndexTest, familialIncidenceRateTest, fsirTest, plotPed

Examples

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

## Subset to some families and generate a pedigree data.frame.
mbsub <- minnbreast[minnbreast$famid == 4 | minnbreast$famid == 5 |
                  minnbreast$famid == 6 | minnbreast$famid == 7, ]
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 test:
far <- kinshipSumTest(fad, trait=tcancer, traitName="cancer",
                      nsim=1000)
head(result(far))

## Plot the pedigree for one of affected individuals. The id of the affected
## individual is highlighted in red.
plotPed(far, id=result(far)$affected_id[1])

## Replace the trait, this will delete all simulation results
## on the existing FAKinSumResults object
tpreg <- mbsub$everpreg
names(tpreg) <- mbsub$id
trait(far) <- tpreg

## The analysis can be performed using the runSimulation method.
far <- runSimulation(far, nsim=1000)
head(result(far))

## Plot the pedigree of one of the affected; note that "affected" now
## indicates whether the individual was ever pregnant.
plotPed(far, id="9")

## Plot also the result from the simulation run.
plotRes(far, id="9")

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