weights {podkat} | R Documentation

## Extract Contribution Weights of Variants

### Description

Method for extracting the contributions that each variant makes to the test statistic of an association test

### Usage

    ## S4 method for signature 'AssocTestResult'
    weights(object, Z, model)
    ## S4 method for signature 'AssocTestResultRanges'
    weights(object, Z, model, limit=20, sex=NULL)

### Arguments

`object` | an object of class `AssocTestResult` or `AssocTestResultRanges`
`Z` | an object of class `GenotypeMatrix`, an object of class `TabixFile`, or a character string with the file name of a VCF file
`model` | an object of class `NullModel`
`limit` | maximum number of regions to be processed; set to `Inf` or non-numeric value like `NA` or `NULL` to disable limitation. Do this with caution, in particular, when reading from a VCF file, as reading of excessively large regions from VCF files may take very long or even kill the R session because of excessive memory comsumption!
`sex` | if `NULL`, all samples are treated the same without any modifications; if `sex` is a factor with levels `F` (female) and `M` (male) that is as long as the number of samples in `model`, this argument is interpreted as the sex of the samples. In this case, the genotypes corresponding to male samples are doubled before further processing. This is designed for mixed-sex analyses of the X chromosome outside of the pseudoautosomal regions.

### Details

Upon successful completion of an association test, the `weights` method allows for finding out the individual contributions each of the variants made to the test statistic. This computation is only possible for kernels “linear.podkat” and “linear.SKAT” (see `computeKernel`).

If called for an `AssocTestResult` object as first argument `object`, a `GenotypeMatrix` object `Z`, and a `NullModel` object `model`, `weights` returns a `GRanges` object that contains all variants of `variantInfo(Z)` along with two numerical metadata columns named “weight.raw” and “weight.contribution”. The column “weight.raw” corresponds to raw contributions. These are signed, i.e. a positive value indicates a positive association, while a negative value indicates a negative association. The larger the absolute value, the larger the contribution. The column “weight.contribution” corresponds to relative contributions. These values are non-negative and they sum up to 1. For mathematical details, see Subsection 9.4 of the package vignette.

If `weights` is called for an `AssocTestResultRanges` object `object`, a second argument `Z` that is an object of class `GenotypeMatrix`, an object of class `TabixFile`, or a character string with the name of a VCF file, and a `NullModel` object `model`, the contribution weights described above are computed for each region in `object`. In this case, the method returns a `GRangesList` with as many components as `object` has regions, where each list component is a `GRanges` object containing the contribution weights as described above.

It is essential for `weights` to work correctly that `object` is actually the result of an association test between `Z` and `model`. If called for objects that actually do not belong to each other, the results are void. The method is implemented such that all possible checks are made that possibly detect inconsistencies between the input objects. However, the final responsibility is left to user to make sure that all data are consistent. Special caution is necessary if `weights` is run for an `AssocTestResultRanges` object that has been obtained by merging multiple `AssocTestResultRanges` using the `c` method. The `c` method performs several checks to ensure consistency of association test parameters among the merged results, but the `sex` parameter is an exception: if it appears to be inconsistent among the results to merge, it is omitted from the merged object (see also `AssocTestResultRanges`).

The `weights` method needs to re-evaluate some computations of the association test. In case it is called for `Z` being a `TabixFile` object or file name of a VCF file, `weights` even needs to re-read the genotype data from the file. Therefore, the method has a safety limit not to process too many regions (see `limit` argument described above).

### Value

an object of class `GRanges` or `GRangesList` (see details above)

### Author(s)

Ulrich Bodenhofer bodenhofer@bioinf.jku.at

### References

http://www.bioinf.jku.at/software/podkat

### See Also

`assocTest`, `AssocTestResult`, `AssocTestResultRanges`, `nullModel`, `NullModel`, `computeKernel`, `GenotypeMatrix`, `p.adjust`, `filterResult`

### Examples

    ## load genome description
    data(hgA)

    ## partition genome into overlapping windows
    windows <- partitionRegions(hgA)

    ## load genotype data from VCF file
    vcfFile <- system.file("examples/example1.vcf.gz", package="podkat")
    Z <- readGenotypeMatrix(vcfFile)

    ## read phenotype data from CSV file (continuous trait + covariates)
    phenoFile <- system.file("examples/example1lin.csv", package="podkat")
    pheno <- read.table(phenoFile, header=TRUE, sep=",")

    ## train null model with all covariates in data frame 'pheno'
    model <- nullModel(y ~ ., pheno)

    ## perform association test
    res <- assocTest(Z, model, windows)

    ## perform multiple testing correction and filter for
    ## significant regions
    res <- filterResult(p.adjust(res), filterBy="p.value.adj")

    ## compute contributions
    contrib <- weights(res, Z, model)
    contrib

    ## extract most indicative variants
    filterResult(contrib)

    ## plot contributions
    plot(contrib[[1]], "weight.raw")
    plot(contrib[[1]], "weight.contribution", type="b", alongGenome=TRUE)

[Package podkat version 1.14.0 Index]