plotPeakLocations: Plot locations of mapped peaks relative to start of closest...
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, plots the distribution of peaks relative to the start position of their closest feature. On the resulting plot, the position of each dot gives how many peaks overlap with the interval found that distance upstream or downstream of their closest feature's start point. By default, 2500 bases upstream and 2500 bases downstream of feature start positions are shown, and the user can specify how many bases upstream and downstream of feature start positions should be plotted. This function uses createMatrices to create the matrices of relative peak locations used for plotting (for more details on these matrices, see the documentation for createMatrices). The matrices used for plotting can optionally be returned.

plotPeakLocations(mappingResult, upstreamBins = 250,
  downstreamBins = 250, basesPerBin = 10, returnMatrix = F,
  plotColor = "red",
  mainTitle = "Peak positions relative to feature start",
  xTitle = "Position relative to feature start (bp)",
  yTitle = "Number of peaks", backgroundStyle = "blackAndWhite")

`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 (plotted points) upstream of each feature start position to be used for plotting. The total distance plotted upstream of feature starts is (upstreaBins * basesPerBin) base pairs
`downstreamBins`	The number of bins (plotted points) downstream of each feature start position to be used for plotting. The total distance plotted downstream of feature starts is (upstreaBins * basesPerBin) base pairs
`basesPerBin`	The width of each bin in the computed matrices, in base pairs. Combined with upstreamBins and downstreamBins, this parameter controls how far upstream and downstream of feature starts the matrices cover.
`returnMatrix`	If True, the list of matrices calculated by createMatrices will be returned to the user.
`plotColor`	The color of the points on the resulting plot
`mainTitle`	The main title of the resulting plot
`xTitle`	The x-axis title of the resulting plot
`yTitle`	The y-axis title of the resulting plot
`backgroundStyle`	The style of the plot background. This must be one of either "grey" (for a grey-panelled background), "blackAndWhite" (for a white-panelled background), or "minimal" (for a background with no panelling).

The idea for this function, its parameters, and its helper createMatrix (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 all code within this function is my own unless otherwise noted; no code was actually taken from deepTools. Plots are made using ggplot2, with the use of ggplot's expand_limits function to control y-axis limits inspired by a StackOverflow post by Brian Diggs (see References), and use of ggplot's geom_point and geom_vline functions based on an online tutorial for ggplot2 (see References)

If returnMatrix is True, the list of matrices calculated by createMatrices will be returned (see documentation of createMatrices for more details); otherwise, NULL is returned. In either case, a graph showing the distribution of peak locations relative to the start position of their mapped feature is shown, with dots on the graph representing peaks overlapping the interval found that many bases up/downstream of the start of their closest feature.

Brian Diggs. "set only lower bound of a limit for ggplot". 26 June 2012. Accessed 29 September 2019. https://stackoverflow.com/a/11214406

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.

"ggplot2 line plot : Quick start guide - R software and data visualization" Accessed 29 September 2019. http://www.sthda.com/english/wiki/ggplot2-line-plot-quick-start-guide-r-software-and-data-visualization

## Not run: 
  mappingResult <- mapPeaks(H3K27me3Peaks, WS263Genes)
  plotPeakLocations(mappingResult)
  matrixList <- plotPeakLocations(mappingResult, 500, 500, returnMatrix = T)
  featureOneUpstreamScores <- matrixList[[1]][1, ]
  featureTwoDownstreamScores <- matrixList[[2]][2, ]

## End(Not run)