FAProbResults-class {FamAgg} | R Documentation

## Probability test

### Description

The `FAProbResults` object contains the results from the probability test. The probability test is only a convience method that calls the `gap` package's method `pfc.sim` to compute probabilities of familial clustering of phenotypes [Yu and Zelterman (2002)]. One drawback of that method is that it is limited to families with at most 22 individuals. Thus, pedigrees need to be split with specialized software such as Jenti [Falchi and Fuchsberger ea. (2008)], which within large families define cliques that can then be used as input to this algorithm.

### Usage

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

    ## S4 method for signature 'FAProbResults'
    cliqueAndTrait(object, na.rm=FALSE)

    ## S4 method for signature 'FAProbResults'
    cliques(object, na.rm=FALSE)

    ## S4 replacement method for signature 'FAProbResults'
    cliques(object) <- value

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

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

    ## S4 method for signature 'FAProbResults'
    runSimulation(object, nsim=50000)

    ## S4 method for signature 'FAProbResults'
    shareKinship(object, id=NULL)

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

    ## S4 method for signature 'FAProbResults'
    traitByClique(object)

### Arguments

(in alphabetic order)

`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`, `shareKinship`: the id (character or numerif) of the clique (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.
`na.rm` | Whether `NA` elements should be returned or not.
`nsim` | Number of simulations.
`object` | The `FAProbResults` object.
`prune` | For `buildPed`: whether the full pedigree should be returned (`prune=FALSE`) or the pedigree should be reduced to the individuals in the corresponding clique (`prune=TRUE`). Note: the `plotPed` method does also support this parameter.
`value` | For `cliques<-`: 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 `FAProbResults` object is the same as calling the `probabilityTest` on a `FAData` object. In the first case the simulation is performed using the clique and trait information data stored internally in the object, while in the latter case the clique and trait information have to be submitted to the function call.

A call to the setter methods `trait<-` or `cliques<-` 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 or clique data.

### Value

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

### Objects from the Class

`FAProbResults` objects are created by the `probabilityTest` method of `FAData` objects.

### Extends

Class `FAData` directly.

### Slots

nsim

  Number of simulations.

sim

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

.cliques

  A factor with the assignment of individuals to cliques. This slot should not be accessed directly, but the `cliques` and `cliques<-` methods should be used instead that ensure that the data is matched to the information in the pedigree.

### Methods and Functions

cliqueAndTrait

  Get a `data.frame` with the clique ID and the value from the trait for each individual. If `na.rm=TRUE` all rows (individuals) with either a missing clique ID or trait value are removed.

buildPed

  Builds the pedigree for the submitted id (which represents the id of the group, i.e. the clique (e.g. column `"group_id"` of `result(object)`). By default the method builds the full pedigree for all individuals in the clique but the argument `prune` allows to reduce it to the individuals of the clique. Building a pedigree by submitting the family id is not supported. The pedigree is returned as a `data.frame`.

cliques

  Returns a `factor` vector representing the clique/group assignment of the individuals. By default, the ordering is the same as pedigree, setting argument `na.rm=TRUE` removes all `NA` values, thus the ordering and length might differ (e.g. if some individuals are not part of any clique).

cliques<-

  Setter for the cliques vector. Can be a named numeric vector, character vector or factor with the names matching the ids of the individuals in the pedigree. The method internally matches and re-orders the cliques vector to match the ordering of the ids in the pedigree. In addition, the function resets eventually stored simulation results in the `sim` slot.

`plotPed` Plots a pedigree for one of the cliques in the simulation results. The ids of all individuals of the selected clique are highlighted in red. See `plotPed` for more details on the plotting and details below for additional settings.

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 group (i.e. cliques specified by the `clique` parameter). `affected`: the number of affected individuals in all group (i.e. cliques specified by the `clique` parameter). `group_id`: the id of the group (clique). `family`: the id of the family in which the clique was defined. `group_phenotyped`: the number of phenotyped individuals in the current group. `group_affected`: the number of affected individuals in the current group. `pvalue`: the p-value from the Monte Carlo simulation. `padj`: the p-value adjusted for multiple hypothesis testing using the method specified with argument `method`.

runSimulation

  Performs the simulation analysis based on the pedigree, trait and clique information stored in the object. Returns a `FAProbResults` object with the results of the simulation.

shareKinship

  Returns a character vector with the ids of all individuals that share kinship with any of the individuals in the clique identified by the argument `id`.

trait<-

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

traitByClique

  Summarize the trait information by clique. Returns a `matrix` with the size of the clique (i.e. individuals in the clique with available trait information) and count of individuals in the clique with a trait value other than zero (column `affected_size`). The clique ids are used as rownames of the `matrix`.

### Note

Subsetting (using the `[` operator) is not supported.

### Author(s)

Johannes Rainer, Daniel Taliun

### References

Yu C & Zelterman D (2002) Statistical inference for familial disease clusters. Biometrics, pp 481-491

Falchi M & Fuchsberger C (2008) Jenti: an efficient tool for mining complex inbred genealogies. Bioinformatics, pp 724-726

### See Also

`FAData`, `buildPed`, `plotPed`, `trait`, `probabilityTest`, `kinshipGroupTest`, `kinshipSumTest`, `genealogicalIndexTest`, `familialIncidenceRateTest`, `fsirTest`

### Examples

    ## Build the data based on the internal test data set.
    pedFile <- system.file("txt/Large.ped", package="FamAgg")
    cliqFile <- system.file("txt/Large-cliques.txt", package="FamAgg")
    ped <- read.table(pedFile, sep=";")
    cliqDf <- read.table(cliqFile, sep="\t")
    cliqs <- cliqDf[, 1]
    names(cliqs) <- cliqDf[, 2]

    ## generate the FAData
    fad <- FAData(ped[, 1:5])

    ## define the trait
    affs <- ped[, 6]
    affs[affs==2] <- 1
    names(affs) <- ped[, 2]

    ## Performing the test
    far <- probabilityTest(fad, trait=affs,
                           cliques=cliqs, nsim=1000)

    ## display the results:
    res <- result(far)
    head(res)

    ## plot the pedigree for the first group
    ## we are using the kinshiup2 plotting function, since the pedigree is
    ## quite busy
    plotPed(far, id=res[1, "group_id"])

    ## the full pedigree for this affected individual is:
    nrow(buildPed(far, id=res[1, "group_id"]))

    ## restrict to the individuals in the tested clique:
    nrow(buildPed(far, id=res[1, "group_id"], prune=TRUE))
    plotPed(far, id=res[1, "group_id"], prune=TRUE)

[Package FamAgg version 1.6.1 Index]