#' Plot calibration graphs from univariate linear models
#' 
#' Produce graphics of calibration data, the fitted model as well as
#' confidence, and, for unweighted regression, prediction bands.
#' 
#' @aliases calplot calplot.default calplot.lm
#' @param object A univariate model object of class \code{\link{lm}} or
#' \code{\link[MASS:rlm]{rlm}} with model formula \code{y ~ x} or \code{y ~ x -
#' 1}.
#' @param xlim The limits of the plot on the x axis.
#' @param ylim The limits of the plot on the y axis.
#' @param xlab The label of the x axis.
#' @param ylab The label of the y axis.
#' @param legend_x An optional numeric value for adjusting the x coordinate of
#' the legend.
#' @param alpha The error tolerance level for the confidence and prediction
#' bands. Note that this includes both tails of the Gaussian distribution,
#' unlike the alpha and beta parameters used in \code{\link{lod}} (see note
#' below).
#' @param varfunc The variance function for generating the weights in the
#' model.  Currently, this argument is ignored (see note below).
#' @return A plot of the calibration data, of your fitted model as well as
#' lines showing the confidence limits. Prediction limits are only shown for
#' models from unweighted regression.
#' @note Prediction bands for models from weighted linear regression require
#' weights for the data, for which responses should be predicted. Prediction
#' intervals using weights e.g. from a variance function are currently not
#' supported by the internally used function \code{\link{predict.lm}},
#' therefore, \code{calplot} does not draw prediction bands for such models.
#' 
#' It is possible to compare the \code{\link{calplot}} prediction bands with
#' the \code{\link{lod}} values if the \code{lod()} alpha and beta parameters
#' are half the value of the \code{calplot()} alpha parameter.
#' @author Johannes Ranke
#' @importFrom graphics legend matlines plot points
#' @examples
#' 
#' data(massart97ex3)
#' m <- lm(y ~ x, data = massart97ex3)
#' calplot(m)
#' 
#' @export calplot
calplot <- function(object, 
  xlim = c("auto", "auto"), ylim = c("auto", "auto"), 
  xlab = "Concentration", ylab = "Response",
  legend_x = "auto", 
  alpha = 0.05, varfunc = NULL)
{
  UseMethod("calplot")
}

#' @export
calplot.default <- function(object, 
  xlim = c("auto","auto"), ylim = c("auto","auto"), 
  xlab = "Concentration", ylab = "Response",
  legend_x = "auto",
  alpha=0.05, varfunc = NULL)
{
  stop("Calibration plots only implemented for univariate lm objects.")
}

#' @export
calplot.lm <- function(object,
  xlim = c("auto","auto"), ylim = c("auto","auto"), 
  xlab = "Concentration", ylab = "Response",
  legend_x = "auto", 
  alpha=0.05, varfunc = NULL)
{
  if (length(object$coef) > 2)
    stop("More than one independent variable in your model - not implemented")

  if (alpha <= 0 | alpha >= 1)
    stop("Alpha should be between 0 and 1 (exclusive)")

  m <- object
  level <- 1 - alpha
  y <- m$model[[1]]
  x <- m$model[[2]]
  if (xlim[1] == "auto") xlim[1] <- 0
  if (xlim[2] == "auto") xlim[2] <- max(x)
  xlim <- as.numeric(xlim)
  newdata <- list(
    x = seq(from = xlim[[1]], to = xlim[[2]], length=250))
  names(newdata) <- names(m$model)[[2]]
  if (is.null(varfunc)) {
    varfunc <- if (length(m$weights)) {
        function(variable) mean(m$weights)
      } else function(variable) rep(1,250)
  }
  pred.lim <- predict(m, newdata, interval = "prediction",
    level=level, weights.newdata = varfunc(m))
  conf.lim <- predict(m, newdata, interval = "confidence",
    level=level)
  yrange.auto <- range(c(0,pred.lim))
  if (ylim[1] == "auto") ylim[1] <- yrange.auto[1]
  if (ylim[2] == "auto") ylim[2] <- yrange.auto[2]
  if (legend_x[1] == "auto") legend_x <- min(object$model[[2]])
  plot(1,
    type = "n", 
    xlab = xlab,
    ylab = ylab,
    xlim = as.numeric(xlim),
    ylim = as.numeric(ylim)
  )
  points(x,y, pch = 21, bg = "yellow")
  matlines(newdata[[1]], pred.lim, lty = c(1, 4, 4), 
    col = c("black", "red", "red"))
  if (length(object$weights) > 0) {
    legend(min(x), 
      max(pred.lim, na.rm = TRUE), 
      legend = c("Fitted Line", "Confidence Bands"),
      lty = c(1, 3), 
      lwd = 2, 
      col = c("black", "green4"), 
      horiz = FALSE, cex = 0.9, bg = "gray95")
  } else {
  matlines(newdata[[1]], conf.lim, lty = c(1, 3, 3), 
    col = c("black", "green4", "green4"))
  legend(legend_x,
    max(pred.lim, na.rm = TRUE), 
    legend = c("Fitted Line", "Confidence Bands", 
        "Prediction Bands"), 
    lty = c(1, 3, 4), 
    lwd = 2, 
    col = c("black", "green4", "red"), 
    horiz = FALSE, cex = 0.9, bg = "gray95")
  }
}