FAKinSumResults-class {FamAgg} | R Documentation

## 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")

    ## 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.
`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.
`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. `"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")

[Package FamAgg version 1.20.0 Index]