FAKinGroupResults-class {FamAgg} | R Documentation

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

[Package FamAgg version 1.22.0 Index]