R/YuleSimon.R

In kyoustat/T4mle: What the Package Does Using Title Case

#' (Weighted) MLE of Yule-Simon Distribution
#' 
#' Yule-Simon distribution is characterized by the following probability mass function,
#' \deqn{f(x;\rho) = \rho B (x, \rho+1)}
#' where the domain is positive integers \eqn{x \in \lbrace 1,2,\ldots \rbrace} with the shape parameter \eqn{\rho > 0}. 
#' 
#' @param x a length-\eqn{n} vector of positive integers.
#' @param weight a length-\eqn{n} weight vector. If set as \code{NULL}, it gives an equal weight, leading to standard MLE.
#' 
#' @return a named list containing (weighted) MLE of \describe{
#' \item{rho}{shape parameter.}
#' }
#' 
#' @examples
#' #  generate data
#' x = sample(1:20, 50, replace=TRUE)
#' 
#' #  fit unweighted
#' YuleSimon(x)
#' 
#' \dontrun{
#' # put random weights to see effect of weights
#' niter = 500
#' ndata = 200
#' 
#' # generate data and fit unweighted MLE
#' x    = sample(1:20, ndata, replace=TRUE)
#' xmle = YuleSimon(x)
#' 
#' # iteration
#' vec.rho = rep(0,niter)
#' for (i in 1:niter){
#'   # random weight
#'   ww = abs(stats::rnorm(ndata))
#' 
#'   MLE = YuleSimon(x, weight=ww)
#'   vec.rho[i] = MLE$rho
#'   if ((i%%10) == 0){
#'     print(paste0(" iteration ",i,"/",niter," complete.."))
#'   }
#' }
#' 
#' # distribution of weighted esti
#' opar <- par(no.readonly=TRUE)
#' hist(vec.rho, main="shape 'rho' and MLE")
#' abline(v=xmle$rho, lwd=3, col="red")
#' par(opar)
#' } 
#' 
#' @author Kisung You
#' @export
YuleSimon <- function(x, weight=NULL){
  #############################################
  # Preprocessing
  # inputs
  x  = handle_ivec_pos("YuleSimon", x)
  nx = length(x)
  weight = handle_weight("YuleSimon", weight, nx)
  
  # others
  maceps  = 10*.Machine$double.eps
  
  #############################################
  # Optimize : R's optimize
  fopt.YuleSimon <- function(rho){
    return(sum((rep(log(rho),nx) + base::lbeta(x, rho+1))*weight))
  }
  sol = stats::optimize(fopt.YuleSimon, lower=maceps, upper=1e+5, maximum = TRUE)$maximum
  
  #############################################
  # Return
  output = list(rho=sol)
  return(output)
}