peakEnrichment4Features: Enrichment for Features
In Chicago: CHiCAGO: Capture Hi-C Analysis of Genomic Organization

Description Usage Arguments Value Note Author(s) Examples

View source: R/peakEnrichment4Features.R

This function computes how many other-ends from a chicagoData object, that engage in significant interactions, overlap with a set of genomic features. In order to determine how those numbers compare to what would be expected if interaction significance had no effect on the overlaps, this function samples different sets of interactions from the non-significant pool and assesses how they overlap with genomic features (it computes the mean and confidence intervals). Results are returned in a table and plotted in a barplot. The difference between the results for the set of significant interactions and the random samples can be used as a measure of the enrichment for genomic features. Samples have the same size as the number of significant interactions called. Moreover, they follow the same distribution of distances between bait and other-end. This is achieved by binning this distribution and drawing interactions per bin, according to the numbers observed in the significant set.

peakEnrichment4Features(x1, folder=NULL,  list_frag, no_bins=NULL, sample_number, 
                        position_otherEnd= NULL,colname_dist=NULL,
                        score=5, colname_score="score",min_dist=0, max_dist=NULL,
                        sep="\t", filterB2B=TRUE, b2bcol="isBait2bait", 
                        unique=TRUE,plot_name=NULL, trans=FALSE, plotPeakDensity=FALSE)

`x1`	a `chicagoData` object or a data table (`data.table`) containining other end IDs.
`folder`	the name of the folder where the files containing the features of interest are stored.
`list_frag`	a list where each element is the name of a file containing a feature of interest (e. g. H3K4me1, CTCF, DHS etc.). These files must have a bed format, with no header. Each element of the list must be named.
`no_bins`	Number of bins to divide the range of `colname_dist` (after `colname_dist` has been trimmed according to `min_dist` and `max_dist`). This will be important to determine how many interactions should be sampled according to distance from bait. For more details see `Note` below.
`sample_number`	Number of samples to be used in the permutation test. Large numbers of samples (around 100) are recommended. Nevertheless, smaller numbers (around 10) speed up the processing time and have shown to give sensible results when compared to large numbers.
`position_otherEnd`	the name of the file containing the coordinates of the restriction fragments and the corresponding IDs. The coordinates should be "chromosome", "start" and "end", and the ID should be numeric. `position_otherEnd` only needs to be specified if x is not a `chicagoData` object.
`colname_dist`	the name of the column which contains the distances between bait and other end. `colname_dist` only needs to be specified if x is not a `chicagoData` object.
`score`	the threshold above which interactions start being called as significant.
`colname_score`	the name of the column which contains the score values which establish the level of significance of each interaction.
`min_dist`	the minimum distance from bait required in the query. If this parameter is set to `NULL` and `trans` is set to `TRUE`, cis interactions are disregarded from the analysis. This parameter is also useful when the user only wants to look at cis distal interactions (very far from bait).
`max_dist`	the maximum distance from bait required in the query. This parameter is particularly useful when the user only wants to look at cis proximal interactions (interactions surrounding the bait).
`sep`	the field separator character. Values are separated by this character on each line of the file containing the coordinates of the restriction fragments (called by `position_otherEnd`).
`filterB2B`	a logical value indicating whether bait-to-bait interactions should be removed from the analysis.
`b2bcol`	the name of the column identifying bait-to-bait interactions in the `x1`.
`unique`	a logical value indicating whether to removing duplicated other-ends from significant interactions and samples.
`plot_name`	the name of the file where to save the resulting plot. This parameter is only required if the user wants to save the plot. Otherwise, the plot will be displayed on the screen, but not saved.
`trans`	a logical value indicating whether the enrichment is to be computed for trans interactions. If this parameter is set to `TRUE` and `min_dist` is set to `NULL`, cis interactions are disregarded from the analysis.
`plotPeakDensity`	a logical value indicating whether to plot the density of interactions with distance. Setting this parameter to `TRUE` only applies to cis interactions.

a data frame containing columns for the number of overlaps for each feature in our significant interactions, the average number of overlaps for each feature in our samples, the corresponding standard deviations.

The number of interactions sampled per distance follows the same distribution as the one in the significant set. This is achieved by counting the number of significant interactions per distance bin. In this way, when samples are computed, the number of interactions drawn will depend on each distance bin. Each sample will have the same number of interactions per bin as in the significant set. To improve this computation, we recommend a bin size of around 10-20kb, but this number could be larger when looking at distal interactions only (up to 200kb). This is established using the parameter no_bins. For instance, using min_dist=0 and max_dist=1e6, no_bins should be set to 100 so to obtain 10kb bins.

Mikhail Spivakov, Jonathan Cairns, Paula Freire Pritchett

data(cdUnitTest)

##modifications to cdUnitTest, ensuring it uses correct design directory
designDir <- file.path(system.file("extdata", package="Chicago"), "unitTestDesign")
cdUnitTest <- modifySettings(cd=cdUnitTest, designDir=designDir)

##get the unit test ChIP tracks
dataPath <- system.file("extdata", package="Chicago")
ChIPdir <- file.path(dataPath, "unitTestChIP")
dir(ChIPdir)

##get a list of the unit test ChIP tracks
featuresFile <- file.path(ChIPdir, "featuresmESC.txt")
featuresTable <- read.delim(featuresFile, header=FALSE, as.is=TRUE)
featuresList <- as.list(featuresTable$V2)
names(featuresList) <- featuresTable$V1

##test for overlap
peakEnrichment4Features(cdUnitTest, folder=ChIPdir, list_frag = featuresList, no_bins = 500, sample_number = 100)

Loading required package: data.table

Welcome to CHiCAGO - version 1.18.0
If you are new to CHiCAGO, please consider reading the vignette through the command: vignette("Chicago").
NOTE: Default values of tlb.minProxOEPerBin and tlb.minProxB2BPerBin changed as of Version 1.1.5. No action is required unless you specified non-default values, or wish to re-run the pipeline on old chicagoData objects. See news(package="Chicago")
Warning: settings are not checked for consistency with the original ones.
Locating <baitmapfile>.baitmap in /usr/lib/R/site-library/Chicago/extdata/unitTestDesign...
Found unitTest.baitmap
Locating <rmapfile>.rmap in /usr/lib/R/site-library/Chicago/extdata/unitTestDesign...
Found unitTest.rmap
Locating <nperbinfile>.npb in /usr/lib/R/site-library/Chicago/extdata/unitTestDesign...
Found unitTest.npb
Locating <nbaitsperbinfile>.nbpb in /usr/lib/R/site-library/Chicago/extdata/unitTestDesign...
Found unitTest.nbpb
Locating <proxOEfile>.poe in /usr/lib/R/site-library/Chicago/extdata/unitTestDesign...
Found unitTest.poe
Checking the design files...
Reading the settings from NPB file header...
Checking the integrity of the NPB file...
Reading NPerBin file...
Checking the integrity of the NBPB file...
Reading NBaitsPerBin file...
[1] "featuresmESC.txt"                                               
[2] "unitTestCTCF_ENCFF001ZQY.broadPeak.bed"                         
[3] "unitTestH3K27me3_ENCFF001ZJO.broadPeak.bed"                     
[4] "unitTestwgEncodeLicrHistoneEse14H3k27acME0129olaStdPk.broadPeak"
[5] "unitTestwgEncodeSydhHistEse14H3k04me3StdPk.narrowPeak"          
[6] "unitTestwgEncodeSydhHistEse14H3k09me3StdPk.narrowPeak"          
Input is a CHiCAGO object...
Filtering out bait2bait interactions...
Removing trans interactions from analysis...
Overlap our reads with Features...
Separate significant interactions from non-significant interactions...
No distance from bait to trim sample was provided...
Removing duplicated other-ends from significant interactions (same will happen with samples)...
Bin non-significant interactions according to distance from bait before drawing random samples...
Draw random samples...
Sum number of overlaps with feature in our significant interactions and in our samples...
Plotting barplot number of overlaps for features and samples...
Some (or all) overlaps are zero - warnings will be generated.
Returning table with results...

         OLwithSI MeanOLwithSamples SDOLwithSample    LowerCI   HigherCI
CTCF           16              6.50      1.6605950  3.2452338  9.7547662
H3K4me3         2              1.05      0.6871843 -0.2968812  2.3968812
H3k27ac         6              3.51      1.4872862  0.5949191  6.4250809
H3K27me3       12              8.21      2.1286644  4.0378178 12.3821822
H3K9me3         0              0.12      0.3265986 -0.5201333  0.7601333