NormRFit-class: Container for a fit done with normR
In imbbLab/normr: Normalization and difference calling in ChIP-seq data

Description Usage Arguments Details Value Methods (by generic) Slots Author(s) See Also Examples

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.

## 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, ...)

`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

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. #'

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.

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.

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.

Johannes Helmuth helmuth@molgen.mpg.de

normr for function creating this container

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)