R/1_gR2.R

In heatherjzhou/gR2.2: Generalized R Square Measures for Mixtures of Bivariate Linear Dependences

#' gR2
#'
#' Add description of \code{gR2} here
#'
#' Add details here
#'
#' Add details here
#'
#' Add details here
#'
#' @param x Add description here
#' @param y Add description here
#' @param z Add description here
#' @param K Add description here
#' @param cand.Ks Add description here
#' @param nstart Add description here
#' @param mc.cores Add description here
#' @param inference Add description here
#' @param conf.level Add description here
#' @param method Add description here
#'
#' @return \code{gR2} returns a list consisting of the following items:
#' \item{estimate}{Add description here}
#' \item{conf.level}{Add description here}
#' \item{conf.int}{Add description here}
#' \item{p.val}{Add description here}
#' \item{K}{Add description here}
#' \item{membership}{Add description here}
#'
#' @author Heather J Zhou, \email{heatherjzhou@ucla.edu}
#' @author Jingyi Jessica Li, \email{jli@stat.ucla.edu}
#'
#' @references
#' Li, J.J., Tong, X., and Bickel, P.J. (2018). Generalized R2 Measures for a Mixture of Bivariate Linear Dependences. arXiv.
#'
#' @examples
#' library(mvtnorm)
#' #Simulate data from a mixture of bivariate normal distributions
#' n=200 #sample size
#' K=2 #number of components (lines)
#' p_s=c(0.5,0.5) #proportions of components
#' mu_s=list(c(0,-2),c(0,2)) #mean vectors
#' Sigma_s=list(rbind(c(1,0.8),c(0.8,1)),rbind(c(1,0.8),c(0.8,1))) #covariance matrices
#' z=sample(1:K,size=n,prob=p_s,replace=TRUE) #line memberships
#' data=matrix(0,nrow=n,ncol=2)
#' for (i in 1:K){
#'   idx=which(z==i)
#'   data[idx,]=rmvnorm(n=length(idx),mean=mu_s[[i]],sigma=Sigma_s[[i]])
#' }
#'
#' x<-data[,1]
#' y<-data[,2]
#' plot(x,y)
#'
#' #Specified scenario
#' gR2(x,y,z) #No inference
#' gR2(x,y,z,inference=TRUE) #Inference
#'
#' #Unspecified scenario
#' gR2(x,y,K=2,mc.cores=2) #K chosen, no inference
#' #gR2(x,y,K=2,inference=TRUE,mc.cores=2) #K chosen, inference
#' #gR2(x,y,mc.cores=2) #K not chosen, no inference
#' #gR2(x,y,inference=TRUE,mc.cores=2) #K chosen, inference
#'
#' @export
#' @importFrom lmodel2 lmodel2
#' @importFrom parallel detectCores mclapply
#' @importFrom mvtnorm dmvnorm

gR2<-function(x,y,z=NULL, #basic arguments
              K=NULL,cand.Ks=1:4,nstart=30,mc.cores=detectCores()-1, #arguments for unspecified scenario
              inference=FALSE,conf.level=0.95,method=c("general","binorm") #arguments for inference
              ){

  #Specified vs. unspecified
  if (!is.null(z)){
    #Specified scenario
    #If inference is false, then return a list of one item: estimate.
    #If inference is true, then return a list of four items: estimate, conf.level, conf.int, and p.val.
    toReturn<-gR2_Specified(x,y,z,
                            inference,conf.level,method)
    return(toReturn)
  }else{
    #Unspecified scenario
    #First,
    #if K is chosen, get membership.
    #If K is not chosen, choose K and get membership (and print explanations along the way).
    #Then,
    #if inference is false, then return a list of three item: estimate, K, membership.
    #If inference is true, then return a list of six items: estimate, conf.level, conf.int, p.val, K, membership.
    toReturn<-gR2_Unspecified(x,y,
                              K,cand.Ks,num_init=nstart,mc.cores,
                              inference,conf.level,method)
    return(toReturn)
  }
}