# -------------------------------------------------------------------------------------------------------------------------  #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #           File Name              :  PlotMCestimateWithSE.R                                                                 #
  #           Last Updated Funclist  :  08 Feb 2015,  5:12 AM (Sunday)                                                         #
  #                                                                                                                            #
  #           Author Name            :  Rick Saporta                                                                           #
  #           Author Email           :  RickSaporta@gmail.com                                                                  #
  #           Author URL             :  www.github.com/rsaporta                                                                #
  #                                                                                                                            #
  #           Packages Called        :  ggplot2                                                                                #
  #           Packages Used via NS   :  NA                                                                                     #
  #                                                                                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  #                                                                                                                            #
  #   PlotMCestimateWithSE ( Estim, SE, addSELines=TRUE, scaleToEstim=TRUE, burnIn=0, SELinesColor="gold"                      #
  #                          , Title="Monte Carlo Simuls", secondTitle="With Error Bars" )                                     #
  #                                                                                                                            #
  #                                                                                                                            #
  #                                                     <END FUNCS>                                                            #
  #  -----------------------------------------------------------------------------------------------------------------------   #
  # -------------------------------------------------------------------------------------------------------------------------  #

PlotMCestimateWithSE <- function(Estim, SE, addSELines=TRUE, scaleToEstim=TRUE, burnIn=0, SELinesColor="gold", Title="Monte Carlo Simuls", secondTitle="With Error Bars") { 

  require(ggplot2)

  # @ ~~~~~~~~~ @ #
  #  CLEAN UP FIRST FEW VALUES OF SE #
    .h <- head(SE, length(SE)*.001)
    if (length(.h)) {
      .sd <- sd(.h)
      .mean <- mean(.h)

      .firstVal <- min(which(!(abs(.h - .mean) > abs(1.5*.sd))), length(.h))
      SE[1:.firstVal] <- SE[.firstVal]
    }
    suppressWarnings(rm(.h, .mean, .sd, .firstVal))
  # @ ~~~~~~~~~ @ #

  dat <- data.frame(N=seq_along(Estim), Estim=Estim, SE=SE, Minus_2SE = Estim - 2*SE, Plus_2SE = Estim + 2*SE)
  
  # only burn in if != 0 
  if(burnIn)
    dat <- tail(dat, -burnIn)

  Title <- paste0(Title, " (N = ", N, ") \n", 
          if(!(is.null(secondTitle)|secondTitle=="")) paste0(secondTitle, "\n"), 
          "Mean Estimate: ", round(mean(Estim), 2) )
  P <- 
  ggplot(dat, aes(x=N)) + 
    geom_line(aes(y=Estim)) + 

    # add Mean line
    geom_hline(aes(yintercept=mean(Estim)), color="red", alpha=0.6)  + 

    # craete title
    ylab("Estimates") + 
    xlab("Simulations") + 
    ggtitle(Title)


  if(addSELines) 
    P <- P + geom_line(aes(y=Plus_2SE),  color=SELinesColor)  +
             geom_line(aes(y=Minus_2SE), color=SELinesColor)  

  if(!scaleToEstim) { 
    yscale <- range(dat[, "Estim"]) 
    print(yscale)
    P + scale_y_continuous(limits=yscale)
  }

  return(P)
}