createMatrices: Create matrices of peak locations before and after feature...
In fuscada2/PeakMapper: Flexible Mapping of Genomic Coordinates to Nearest Features

Description Usage Arguments Details Value References Examples

Given a dataframe of mapped peaks as returned by mapPeaks, returns 2 matrices to be used by plotPeakLocations to plot peak distributions relative to the start of closest features. Every matrix row corresponds to a different feature, and every column is a different "bin" - a genomic interval which is a fixed distance upstream or downstream of a feature's start position. Each matrix entry gives the number of peaks mapped to that feature which overlap with that bin (i.e. the number of peaks that overlap an interval a fixed distance up/downstream of the feature's start position, accounting for feature strandedness). One matrix contains bins found upstream of the feature start, and one matrix contains bins downstream of the feature start. The user can specify how many bins each matrix will use and how wide each bin should be, allowing the user to customize how far upstream or downstream of the feature start will be used for plotting. Note that this is a helper function for plotPeakLocation and should NOT be called directly by the user.

1 2	createMatrices(mappingResult, upstreamBins = 250, downstreamBins = 250, basesPerBin = 10)

`mappingResult`	A dataframe returned by mapPeaks giving the nearest feature(s) to each peak. Format of the dataframe is peak information, followed by feature information, followed by peak position and distance relative to feature, and percent of feature overlapped by peak (see documentation for mapPeaks for more details).
`upstreamBins`	The number of bins upstream of the feature start to be used in the returned matrices. The resulting plot will include all closest peaks witin (upstreamBins * basesPerBin) base pairs upstream of the feature start
`downstreamBins`	The number of bins downstream of the feature start to be used in the returned matrices. The resulting plot will include all closest peaks within (downstreamBins * basesPerBin) base pairs downstream of the feature start
`basesPerBin`	The width of each bin in the returned matrices, in base pairs. Combined with upstreamBins and downstreamBins, this parameter controls how far upstream and downstream of feature starts the matrices cover.

The idea for this function, its parameters and the structure of its output (creating a matrix of bin scores relative to the start of genomic features, in order to plot scores relative to feature starts) is based on the computeMatrix and plotHeatmap functions from the deepTools software suite (see References), but the output is slightly different and all code within this function is my own; no code was actually taken from deepTools.

A list of two matrices. The first matrix (upstreamMatrix) counts peaks in the region upstream of feature starts, and the second matrix (downstreamMatrix) counts peaks in the region downstream of feature starts. Each matrix row is a different feature in mapPeaks, and each column is a bin - an interval that is a fixed distance away from the start of that feature (e.g. with default settings, column 1 of upstreamMatrix represents the intervals 2500-2490 bases upstream of the start of that row's feature). Each matrix entry gives the number of peaks which overlap a given bin for a given feature. (Note that only peaks mapped to this feature are considered for this calculation). Bins in the rightmost column of upstreamMatrix are closest to the feature start, and move further upstream of the feature from right to left in the matrix. Similarly, bins in the leftmost column of downstreamMatrix are closest to the feature start, and move further downstream from left to right in the matrix. The width of each bin is determined by basesPerBin, and the number of bins in upstreamMatrix and downstreamMatrix are determined by upstreamBins and downstreamBins, respectively.

Fidel Ramirez, Devon P. Ryan, Bjorn Gruning, Vivek Bhardwaj, Fabian Kilpert, Andreas S. Richter, Steffen Heyne, Friederike Dundar, and Thomas Manke. deepTools2: A next Generation Web Server for Deep-Sequencing Data Analysis. Nucleic Acids Research (2016). doi:10.1093/nar/gkw257.

## Not run: 
  mappingResult <- mapPeaks(H3K27me3Peaks, WS263Genes)
  matrices <- createMatrices(mappingResult)
  featureOneUpstreamScores <- matrices[[1]][1, ]
  featureTwoDownstreamScores <- matrices[[2]][2, ]
  widerMatrices <- createMatrices(mappingResult, 500, 500)

## End(Not run)