NormRFit-class {normr} | R Documentation

## Container for a fit done with normR

### Description

This S4 class wraps a `normR` fit containing counts, fit configuration and results of the fit. Herein, functions for printing, summarization and accessing are provided. The functions `enrichR`, `diffR` and `regimeR` generate a container of this class to save results of a normR binomial mixture fitting. Please refer to their documentation for conventional usage of the normR package.

### Usage

    ## S4 method for signature 'NormRFit,character'
    exportR(x, filename, fdr = 0.01, color = NA,
      type = c(NA, "bed", "bedGraph", "bigWig"))

    ## S4 method for signature 'NormRFit,missing'
    plot(x, y, ...)

    ## S4 method for signature 'NormRFit'
    getCounts(x)

    ## S4 method for signature 'NormRFit'
    getRanges(x, fdr = NA, k = NULL)

    ## S4 method for signature 'NormRFit'
    getPosteriors(x)

    ## S4 method for signature 'NormRFit'
    getEnrichment(x, B = NA, F = NA, standardized = TRUE,
      procs = 1L)

    ## S4 method for signature 'NormRFit'
    getPvalues(x, filtered = FALSE)

    ## S4 method for signature 'NormRFit'
    getQvalues(x)

    ## S4 method for signature 'NormRFit'
    getClasses(x, fdr = NA)

    ## S4 method for signature 'NormRFit'
    length(x)

    ## S4 method for signature 'NormRFit'
    print(x, digits = max(3L, getOption("digits") - 3L), ...)

    ## S4 method for signature 'NormRFit'
    show(object)

    ## S4 method for signature 'NormRFit'
    summary(object, print = TRUE, digits = 3, ...)

### Arguments

`x` | A `NormRFit` object.
`filename` | A `character` specifying the file to write to.
`fdr` | `NA` or a `numeric` between `0` and `1` specifying a FDR-level. Only regions with a q-value smaller than `fdr` will be returned. If set to `NA`, all regions analyzed will be returned (`getRanges`), classes are assigned by Maximum A Posteriori (`exportR`).
`color` | Specified color(s) when printing a bed file. If `x@type == "enrichR"`, `color` should of length 1 and color shading will be done on this color. If `x@type == "diffR"`, `color` should be of length 2 giving, firstly, the color for `control` and, secondly, the color for `treatment`. If `x@type == "regimeR"`, `color` should be of length `x@k-1`, specifying a color for each enrichment component. Per default an appropriate color palette is used.
`type` | A `character` specifying the filetype for exporting results. If `NA`, format is guessed from `filename`'s extension.
`y` | not used.
`...` | optional arguments to be passed directly to the inherited function without alteration and with the original names preserved.
`k` | `NULL` or a `integer` specifying a model component for which regions have to be returned. If set to `NULL`, regions are not filtered on component assignments. If `fdr` is set and `k == x@B`, the function stops.
`B` | An `integer` specifying the index of a mixture component. The enrichment is calculated relative to this component used as a background component. If `<NA>` (default), the background is determined by normR.
`F` | An `integer` specifying the index of a mixture component. The enrichment is calculated for this component over background `B`. If `<NA>` (default), the component with theta closest to B is used (`enrichR`, `regimeR`). For `diffR`, `F` is not effective.
`standardized` | A `logical` indicating if the enrichment should be standardized betwen 0 and 1. A non-standardized enrichment is particular useful when comparing intensities for ChIP-seq against the same antigen in different conditions (default = TRUE).
`procs` | An `integer` specifying the number of threads to use.
`filtered` | A `logical` specifying if T-filtered or all (default) P-values should be returned.
`digits` | Number of digits to show in number formatting.
`object` | A `NormRCountConfig` object.
`print` | `logical()` indicating if summary should be print to screen

### Details

When working with instances of this S4 class, it is recommended to only use functions to access contents of this object. Internally, the class holds a map structure of unique elements to reduce memory requirements. #'

### Value

getCounts: A `list` of length 2 with `integer` for control and treatment each.

getRanges: A `GenomicRanges` object.

getPosteriors: A `matrix` of posteriors for `x@k` mixture components

getEnrichment: A `numeric` of length `length(x@n)` giving the normR computed enrichment.

getPvalues: A `numeric` of length `length(x@n)` giving the normR computed Pvalues.

getQvalues: A `numeric` of length `length(x@filteredT)` giving the FDR-corrected q-values using Storey's method.

getClasses: A `integer` specifying assignments of regions to the mixture model. If `x@type == "enrichR"`, it contains `1` for enriched regions and `NA` for non-enriched regions. If `x@type == "diffR"`, it contains `1` for control-enriched regions, `2` for treatment-enriched regions and `NA` for non-enriched regions. If `x@type == "regimeR"`, it contains `>= 1` for regime-enriched regions and `NA` for non-enriched regions.

### Methods (by generic)

- `exportR`: Export results of a normR fit to common file formats.

- `plot`: Plot a NormRFit.

- `getCounts`: Get count data for control and treatment.

- `getRanges`: Get the genomic coordinates of regions analyzed with information about component assignment.

- `getPosteriors`: Get computed posteriors for each mixture component.

- `getEnrichment`: Get normalized enrichment.

- `getPvalues`: Get normR-computed P-values.

- `getQvalues`: Get FDR-corrected q-values.

- `getClasses`: Get component assignments for each region analyzed.

- `length`: Returns the number of regions analyzed.

- `print`: Prints a small summary on a NormRFit.

- `show`: Shows a small summary on a NormRFit.

- `summary`: Prints a concise summary of a NormRFit.

### Slots

`type`

  A `character` representing the type of fit. One of `c("enrichR","diffR", "regimeR")`.

`n`

  An `integer` specifying the number of regions.

`ranges`

  A `GenomicRanges` specifying the genomic coordinates of the regions.

`k`

  An `integer` giving the number of binomial mixture components.

`B`

  An `integer` specifying the index of the background component.

`map`

  A vector of `integer` holding a map to map back `counts`, `lnposteriors`, `lnenrichment`, `lnpvals`, `lnqvals` and `classes`. See low level function `normr:::map2uniquePairs` for how the map is generated.

`counts`

  A `list` of length two containing a vector of `integer` holding unique counts for control and treatment each. Use `getCounts` to retrieve original count matrix.

`amount`

  A vector of `integer` specifying the number of occurences of each unique control / treatment count pair.

`names`

  A `character` of length two specifying the names for control and treatment.

`thetastar`

  A `numeric` giving the calculated naive background estimation, i.e. `sum(getCounts(obj)[2,])/sum(getCounts(obj))`

`theta`

  A `numeric` of length `k` giving the normR fitted parametrization of `k` binomial mixture components.

`mixtures`

  A `numeric` of length `k` giving the normR fitted mixture proportions of `k` binomial mixture components. Should add up to one.

`lnL`

  A vector of `numeric` holding the log-likelihood-trace of a normR model fit.

`eps`

  A `numeric` used as threshold for normR fit EM convergence.

`lnposteriors`

  A `matrix` with `length(amount)` rows and `k` columns. It contains the ln posterior probabilities for each unique control / treatment count pair. Use `getPosteriors` to get the posterior matrix for the original data.

`lnenrichment`

  A `numeric` of length `length(amount)` holding calculared normalized enrichment for each unique control / treatment count pair. The enrichment is calculated with respect to the fitted component `B`. Use `getEnrichment` to retrieve enrichment for the original data.

`lnpvals`

  A `numeric` of length `length(amount)` holding ln P-values for each unique control / treatment count pair. Given `theta` of `B` the signifcane of enrichment is assigned. Use `getPvalues` to retrieve Pvalues for original data.

`thresholdT`

  An `integer` giving the threshold used to filter P-values for FDR correction. The T-Filter threshold is a calculated population size for which the null hypothesis (`theta` of `B`) can be rejected. `eps` specifies the significance level.

`filteredT`

  A vector of `integer` giving indices of P-values passing `thresholdT`. Only these P-values will be considered for FDR correction.

`lnqvals`

  A `numeric` of length `length(filteredT)` holding ln q-values (FDR correction). P-values are corrected for multiple testing using Storey's method.

`classes`

  A `integer` of length `length(amount)` specifying the class assignments for each unique control / treatment count pair. These class assignments are based on the normR model fit. For `type == "enrichR"`, this vector contains either `NA` (not enriched) or `1` (enriched). For `type == "diffR"`, this vector contains `NA` (unchanged), `1` (differential in ChIP-seq 1) and `2` (differential in ChIP-seq 2). For `type == "regimeR"`, this vector contains `NA` (not enriched) and an arbitary number of enrichment class `>= 1`.

### Author(s)

Johannes Helmuth helmuth@molgen.mpg.de

### See Also

normr for function creating this container

### Examples

    require(GenomicRanges)

    #Create a toy instance of type 'enrichR'
    fit <- new("NormRFit",
               type="enrichR", n=10L,
               ranges=GRanges("chr1", IRanges(seq(1,100,10), width=10)),
               k=2L, B=1L, map=rep(1:5,2), counts=list(1:5, 1:5),
               amount=rep(2L,5), names=c("chip", "input"), thetastar=.35,
               theta=c(.15,.55), mixtures=c(.9,.1), lnL=seq(-50,-1,10), eps=.001,
               lnposteriors=log(matrix(runif(10), ncol=2)),
               lnenrichment=log(runif(5,0,.2)), lnpvals=log(runif(5)),
               filteredT=2:5, thresholdT=1L, lnqvals=log(runif(5,0,.2)),
               classes=sample(1:2,5,TRUE))

    #print some statistics on fits
    fit
    summary(fit)

    ## Not run:
    #write significant regions to bed
    #exportR(fit, filename = "enrich.bed", fdr = 0.1)
    #write normalized enrichment to bigWig
    #exportR(fit, filename = "enrich.bw")
    ## End(**Not run**)

    ###AccessorMethods
    #get original counts
    getCounts(fit)
    #get genomic coordinates for significant ranges as a GenomicRanges instance
    getRanges(fit, fdr = .1)
    getPosteriors(fit)
    getEnrichment(fit)
    getPvalues(fit)
    getQvalues(fit)
    getClasses(fit)

[Package normr version 1.16.0 Index]