cmbBioCond: Combine a Set of `bioCond` Objects into a Single `bioCond`

Description

Given a list of bioCond objects, cmbBioCond combines them into a single bioCond, by treating each bioCond as an individual ChIP-seq sample. This function is primarily used to handle ChIP-seq samples associated with a hierarchical structure (see "Details" for an example).

Usage

cmbBioCond(
  conds,
  occupy.num = 1,
  name = "NA",
  weight = NULL,
  strMatrix = NULL,
  meta.info = NULL
)

Value

A bioCond object, created by combining all the supplied bioCond objects.

Arguments

conds: A list of bioCond objects to be combined.
occupy.num: For each interval, the minimum number of bioConds occupying it required for the interval to be considered as occupied by the newly constructed bioCond.
name: Name of the constructed biological condition, used only for demonstrating a bioCond object.
weight: A matrix or data frame specifying the relative precisions of signal intensities of the constructed bioCond. Must have the same number of columns as the number of bioConds in conds. A vector is interpreted as a matrix having a single row. Note that rows of weight are recycled if necessary. By default, the same weight is assigned to each measurement in the constructed bioCond.
strMatrix: An optional list of symmetric matrices specifying directly the structure matrix of each genomic interval in the constructed bioCond. Elements of it are recycled if necessary. This argument, if set, overrides the weight argument. See bioCond and setWeight for a detailed description of structure matrix.
meta.info: Optional extra information about the bioCond to be created. If set, the supplied argument is stored in the meta.info field of returned bioCond, and shall never be used by other tools in MAnorm2.

Details

Technically, cmbBioCond treats each bioCond object in conds as a ChIP-seq sample, taking the sample.mean and occupancy fields stored in each bioCond to represent its signal intensities and occupancy indicators, respectively. Then, by grouping these "samples", a new bioCond object is constructed following the exact routine as described in bioCond. See bioCond also for a description of the structure of a bioCond object.

Notably, ChIP-seq samples contained in these bioCond objects to be combined are supposed to have been normalized to the same level, so that these bioConds are comparable to each other. For this purpose, you may choose to normalize the ChIP-seq samples involved all together via normalize, or to normalize the bioCond objects to be combined via normBioCond.

cmbBioCond is primarily used to deal with ChIP-seq samples sorted into a hierarchical structure. For example, suppose ChIP-seq samples are available for multiple male and female individuals, where each individual is associated with several replicates. To call differential ChIP-seq signals between males and females, two bioCond objects representing these two conditions need to be created. One way to do that is to select one ChIP-seq sample as representative for each individual, and group male and female samples, respectively. Alternatively, to leverage all available ChIP-seq samples, a bioCond object could be constructed for each individual, consisting of the samples of him (her). Then, the bioConds of male and female can be separately created by grouping the corresponding individuals. See also "Examples" below.

Examples

Run this code

data(H3K27Ac, package = "MAnorm2")
attr(H3K27Ac, "metaInfo")

## Construct two bioConds comprised of the male and female individuals,
## respectively.
# \donttest{
# First, normalize ChIP-seq samples separately for each individual (i.e.,
# cell line).
norm <- normalize(H3K27Ac, 4, 9)
norm <- normalize(norm, 5:6, 10:11)
norm <- normalize(norm, 7:8, 12:13)

# Then, construct separately a bioCond for each individual, and perform MA
# normalization on the resulting bioConds. Genomic intervals in sex
# chromosomes are not allowed to be common peak regions, since the
# individuals are of different genders.
conds <- list(GM12890 = bioCond(norm[4], norm[9], name = "GM12890"),
              GM12891 = bioCond(norm[5:6], norm[10:11], name = "GM12891"),
              GM12892 = bioCond(norm[7:8], norm[12:13], name = "GM12892"))
autosome <- !(H3K27Ac$chrom %in% c("chrX", "chrY"))
conds <- normBioCond(conds, common.peak.regions = autosome)

# Finally, group individuals into bioConds based on their genders.
female <- cmbBioCond(conds[c(1, 3)], name = "female")
male <- cmbBioCond(conds[2], name = "male")
summary(female)
summary(male)
# }