# plot.freqMAP: Plotting Frequency Moving Average Plot (MAP) Objects In freqMAP: Frequency Moving Average Plots (MAP) of Multinomial Data by a Continuous Covariate

## Description

This function can plot a single frequency MAP object, can overlay two frequency MAP object plots, and can plot odds ratios (OR) comparing two frequency MAP objects.

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11 12``` ```## S3 method for class 'freqMAP' plot(x, y = NULL, xlim = NULL, ylim = NULL, legend = NULL, show.p.value.legend = FALSE, type = "freq", p.value.bar.alpha = c(0.05, 0.01), p.value.bar.color=c("gray90","darkgray"), cex=1,cex.axis=1,cex.lab=1,cex.main=1, pch.x=2,lty.x=1,lwd.x=1,col.x="red", pch.y=1,lty.y=2,lwd.y=1,col.y="blue", cex.legend=1, layout.matrix = NULL,...) ```

## Arguments

 `x` A `freqMAP` object, usually the result of a call to `freqMAP ` `y` An optional `freqMAP` object, usually the result of a call to `freqMAP ` `xlim` Limits on the x-axis. Must be a vector of length 2. The same limits will be used for all category or OR plots. If not specified, then the function will calculate reasonable limits. `ylim` Limits on the y-axis. If `type="freq"`, then `ylim` must be a matrix with 2 columns and as many rows as the length of `x\$cat.names`. In this case, row i will be used as the y limits on the frequency plot of category i. If `type="or"`, then ylim must be a vector of length 2 specifying the common y limits for all odds ratio plots. If ylim is not specified, then the function will calculate reasonable limits which will be common on all plots. `legend` A 2-vector of strings specifying legend text for the `x` and `y` `freqMAP` objects when `type="freq"`. This argument is ignored when `type="or"` or if `y` is not specified. `show.p.value.legend` When set to `TRUE`, a legend is generated for the two levels of Bayesian p-values plotted. This argument is ignored when `y` is not specified. `type` The type of plot to generate. Must be either `"freq"` or `"or"`. See Details below. `p.value.bar.alpha` A 2-vector of p-value cutoffs for the p-value bar at the bottom of plots. This argument is ignored if `y` is not specified. See Details below. `p.value.bar.color` A 2-vector of strings specifying the shading colors for the p-value bar at the bottom of plots. This argument is ignored if `y` is not specified. See Details below. `cex` The size of plotting characters. `cex.axis` The value passed to cex.axis in all plots. See ?par for details. `cex.lab` The value passed to cex.lab in all plots. See ?par for details. `cex.main` The value passed to cex.main in all plots. See ?par for details. `pch.x` The plotting character used for the `freqMAP` object in `x`. `lty.x` The line type `lty` for the posterior bounds in the `freqMAP` object in `x`. `lwd.x` The line width `lwd` for the posterior bounds in the `freqMAP` object in `x`. `col.x` The plotting color for the `freqMAP` object in `x`. `pch.y` The plotting character used for the `freqMAP` object in `y`. `lty.y` The line type `lty` for the posterior bounds in the `freqMAP` object in `y`. `lwd.y` The line width `lwd` for the posterior bounds in the `freqMAP` object in `y`. `col.y` The plotting color for the `freqMAP` object in `y`. `cex.legend` The cex parameter passed to all legends. See ?legend for details. `layout.matrix` The matrix passed to `layout()` prior to plotting. When this argument is not used, the default behavior is to show all plots on the same figure stacked vertically. `...` Not used at this time.

## Details

Three types of plots are possible. First, if `y` is not specified, then a frequency MAP will be plotted for each category in the `x` object. The mean is plotted surrounded by 95% central posterior intervals (CPI). Second, if `y` is specified and `type="freq"`, then a frequency MAP will be plotted for each category in the `x` and `y` objects, where the two frequency MAPs are overlaid on each category plot. Third, if `y` is specified and `type="or"`, then a plot is made for all odds ratios comparing each pair of categories. The posterior mean OR and 95% CPI on the OR are plotted. The title of each OR plot gives the direction of the OR. For example, if there are two categories "a" and "b", and the plot title says "b" vs. "a", this indicates the OR plotted is (t\_xb t\_ya) / (t\_xa t\_yb), where t\_xj and t\_yj indicate the true frequency of category j in the x and y MAPs, respectively. If type="or", plotting characters, line types, line widths, and colors are controlled by `pch.x`, `lty.x`, `lwd,x`, and `col.x`.

If `y` is specified, then `x` and `y` must have the same values in their elements `[["cat.names"]]`, `[["cat.short"]]`, and `[["hw"]]`. The `[["x.label"]]` element can be different. (This element indicates the name of the column in the `[["cat.ma"]]` element which contains the x values when plotting.)

When `y` is specified, a gray bar is added to the bottom of the plot when the two frequency plots are "significantly" different. When `type="freq"`, significance is defined as the posterior Pr(category frequency in MAP `x` > category frequency in MAP `y`) > alpha/2 or < (1-alpha/2). When `type="or"`, significance is defined as the posterior Pr( OR(category 1 vs. category 2) > 1 ) > alpha/2 or < (1-alpha/2). The value of alpha is defined at two levels by the `p.value.bar.alpha` argument and plotted in light gray (higher alpha) and dark gray (lower alpha). The shading colors of the two alpha levels can be overridden by the `p.value.bar.color` argument. This can be thought of as a Bayesian analog to a two-sided p-value. See `posterior.comparison.freqMAP` for further details.

Specifying a legend or asking for a p-value legend, while not specifying `xlim`, will cause the x axis limits to be expanded 20% on the left side to give room for the legend.

Along with the example given below, see `freqMAP-package` for an example based on genotype data.

## Author(s)

Colin McCulloch <colin.mcculloch@themccullochgroup.com>

## References

Payami, H., Kay, D.M., Zabetian, C.P., Schellenberg, G.D., Factor, S.A., and McCulloch, C.C. (2009) "Visualizing Disease Associations: Graphic Analysis of Frequency Distributions as a Function of Age Using Moving Average Plots (MAP) with Application to Alzheimer's and Parkinson's Disease", Genetic Epidemiology

`freqMAP`, `summary.freqMAP`, `layout`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27``` ``` #Make two sets of 2-category frequency data, y1 & y2, which both vary as #a function of a continuous variable x set.seed(5) x <- runif(2000,min=-2,max=2) y1 <- c("a","b")[1+rbinom(n=length(x),size=rep(1,length(x)),prob=pnorm(x/2))] y2 <- c("a","b")[1+rbinom(n=length(x),size=rep(1,length(x)),prob=pnorm(x/5))] #Create the frequency MAP objects for y1 and y2 fp1 <- freqMAP(data.frame(x=x,y=y1,stringsAsFactors=FALSE), x=seq(-2,2,by=.2),x.label="x",hw=.2) fp2 <- freqMAP(data.frame(x=x,y=y2,stringsAsFactors=FALSE), x=seq(-2,2,by=.2),x.label="x",hw=.2) #Examine the frequency MAP objects summary(fp1) print(fp2) #Compare the posterior distributions on the two frequency MAPs pc <- posterior.comparison.freqMAP(group1=fp1,group2=fp2) #Three example plots plot(fp1,ylim=matrix(c(0,1),nrow=2,ncol=2,byrow=TRUE)) plot(fp1,fp2,type="freq",legend=c("y1","y2"),show.p.value.legend=TRUE) plot(fp1,fp2,type="freq",legend=c("y1","y2"),show.p.value.legend=TRUE, p.value.bar.color=c("green","yellow")) plot(fp1,fp2,type="or") ```