R/AllGenerics.R

In rscharpf/MixModelViz: Plot mixture models with applications to copy number or batch effects

#' @include help.R
NULL

#' Observed variables
#'
#' This function shows that column names that must be present in an observed model summary. These must be present in the character vector `names(getObserved(object))`. Checked by `validObject(object)`.
#' @param object see \code{showMethods(ObservedNames)}
#' @return A character vector.
#' @export
#' @docType methods
#' @rdname ObservedNames-method
setGeneric("ObservedNames", function(object) standardGeneric("ObservedNames"))


#' Theoretical variables
#'
#' This function shows that column names that must be present in a theoretical model summary. These must be present in the character vector `names(getTheoretical(object))`. Checked by `validObject(object)`.
#' @param object see \code{showMethods(TheoreticalNames)}
#' @return A character vector.
#' @export
#' @docType methods
#' @rdname TheoreticalNames-method
setGeneric("TheoreticalNames", function(object) standardGeneric("TheoreticalNames"))


#' Observed model summary
#'
#' This function retrieves a summary of the an observed model.
#' @param object see \code{showMethods(getObserved)}
#' @return A data.frame. Column names must include those returned by `ObservedNames(object)`.
#' @export
#' @docType methods
#' @rdname getObserved-method
setGeneric("getObserved", function(object) standardGeneric("getObserved"))

#' Observed model summary
#'
#' This function retrieves a summary of the a theoretical model.
#' @param object see \code{showMethods(getTheoretical)}
#' @return A data.frame. Column names must include those returned by `TheoreticalNames(object)`.
#' @export
#' @docType methods
#' @rdname getTheoretical-method
setGeneric("getTheoretical", function(object) standardGeneric("getTheoretical"))

#' Number of bins
#'
#' This function retrieves the number of bins suggested for plotting an observed model summary as a histogram over the range of it's x values.
#' @param object see \code{showMethods(nBins)}
#' @return integer
#' @export
#' @docType methods
#' @rdname nBins-method
setGeneric("nBins", function(object) standardGeneric("nBins"))

#' TODO add title
#'
#' TODO document
#' @param summ see \code{showMethods(addMarginalBatch)}
#' @return A `MixtureSummary` object
#' @export
#' @docType methods
#' @rdname addMarginalBatch-method
setGeneric("addMarginalBatch", function(summ) standardGeneric("addMarginalBatch"))

#' TODO add title
#'
#' TODO document
#' @param summ see \code{showMethods(addMarginalModel)}
#' @return A `MixtureSummary` object
#' @export
#' @docType methods
#' @rdname addMarginalModel-method
setGeneric("addMarginalModel", function(summ) standardGeneric("addMarginalModel"))

#' Create a plottable summary of the observed mixture model.
#'
#' This function retrieves the observed values, predicted component, and batch identifiers from a `MixtureModel` object. Suitable for plotting counts with a histogram.
#' @param model A `MixtureModel` object
#' @return A data.frame containing the varibles described by `ObservedNames(model)` for each observed object in the model.
#' @export
#' @docType methods
#' @rdname summarizeObserved-method
setGeneric("summarizeObserved", function(model) standardGeneric("summarizeObserved"))

#' Create a plottable summary of the theoretical mixture model.
#'
#' This function retrieves the theoretical distribution from a `MixtureModel` object and generates density points over the range of x values given in the model's observed data. Suitable for plotting as a line. Y values have been scaled to fit the histogram over the range of the observed data when split using `nBins(MixtureSummary.obj)`.
#' @param model A `MixtureModel` object
#' @param obs.df data.frame of observed values generated by `getObserved(model)`. Column names must include those returned by `ObservedNames(model)`.
#' @return A data.frame containing the varibles described by `TheoreticalNames(model)` for each of the observed distributions.
#' @export
#' @docType methods
#' @rdname summarizeTheoretical-method
setGeneric("summarizeTheoretical", function(model, obs.df) standardGeneric("summarizeTheoretical"))

#' Summarize a MixtureModel into a set of data.frames that can be plotted.
#'
#' This function returns a list of two data.frames (observed and predicted) that can be plotted over each other. The observed values can be plotted as a histogram when split by `nBins(MixtureSumamry.obj)`. The theoretical distribution has been scaled to be plotted over the histogram when plotted as described.
#' @param model a MixtureModel-derived object
#' @return A MixtureSummary object.
#' @export
#' @rdname summarize-method
setGeneric("summarize", function(model) standardGeneric("summarize"))

#' Wrapper function for a `MixtureModel`'s theta accessor.
#'
#' This function retrieves the model's theta values as a matrix.
#' @param model see \code{showMethods(k)}
#' @return A "b X k" numeric matrix where b is the number batches and k is the number of predicted components.
#' @export
#' @docType methods
#' @rdname getThetaMatrix-method
setGeneric("getThetaMatrix", function(model) standardGeneric("getThetaMatrix"))

#' Wrapper function for a `MixtureModel`'s sigma accessor.
#'
#' This function retrieves the model's sigma values as a matrix.
#' @param model see \code{showMethods(k)}
#' @return A "b X k" numeric matrix where b is the number batches and k is the number of predicted components.
#' @export
#' @docType methods
#' @rdname getSigmaMatrix-method
setGeneric("getSigmaMatrix", function(model) standardGeneric("getSigmaMatrix"))


#' Get graphical parameters for plotting a histogram of observed values.
#'
#' This function retrieves the non-NULL values from histogram.* slots in a GraphicalParameters object.
#' @param params see \code{showMethods(k)}
#' @return A named list of parameters that may be passed to a ggplot::geom_histogram function call.
#' @export
#' @docType methods
#' @rdname getHistogramParams-method
setGeneric("getHistogramParams", function(params) standardGeneric("getHistogramParams"))


#' Get graphical parameters for plotting a density line of theoretical models.
#'
#' This function retrieves the non-NULL values from line.* slots in a GraphicalParameters object.
#' @param params see \code{showMethods(k)}
#' @return A named list of parameters that may be passed to a ggplot::geom_line function call.
#' @export
#' @docType methods
#' @rdname getLineParams-method
setGeneric("getLineParams", function(params) standardGeneric("getLineParams"))


setGeneric("fill_palette", function(params) standardGeneric("fill_palette"))


setGeneric("color_palette", function(params) standardGeneric("color_palette"))


setGeneric("init_plot", function(summ) standardGeneric("init_plot"))


setGeneric("init_scales", function(summ, params) standardGeneric("init_scales"))

#' Plotting function for `MixtureSummary` objects
#'
#' Plots normal densities from theoretical mixture models over a histogram of observed data.
#'
#' @param summ a `MixtureSummary` object.
#' @param params A GraphicalParamters object. If missing, a new object will be
#'      instantiated.
#'      GraphicalParameters includes a color palette for fill and color
#'      aesthetics, which will be included via `scale_*_manual`. Setting these
#'      palettes to NULL will cause the `scale_*_manual` function call to be
#'      removed from the ggplot object.
#'      GraphicalParameters also includes default alpha, linetype, and size
#'      aesthetics for the geom_histogram and geom_line layers. These values
#'      may be set by vectors of length 1 or of a length equal to number of
#'      data points represented in these layers. Setting a value to NULL will
#'      cause the aesthetic to be removed from the geom_* function call.
#' @return An object of class `ggplot`
#' @examples
#' data(CNPBayes_SBP, package="MixModelViz")
#' sbp.summ <- summarize(CNPBayes_SBP)
#' sbp.summ <- addMarginalModel(sbp.summ)
#' plot_summary(sbp.summ)
#'
#' data(CNPBayes_MBP, package="MixModelViz")
#' mbcnp.summ <- summarize(CNPBayes::CopyNumberModel(CNPBayes_MBP))
#' mbcnp.summ <- addMarginalModel(mbcnp.summ)
#' mbcpn.summ <- addMarginalBatch(mbcnp.summ)
#' plot_summary(mbcnp.summ, new("GraphicalParameters", line.size=2))
#'
#' @export
#' @docType methods
#' @rdname plot_summary-method
setGeneric("plot_summary", function(summ, params) standardGeneric("plot_summary"))