R/utils.R

In baruuum/btoolbox: random toolbox

#' Logarithm of sum of exponentials of two real numbers
#' 
#' Stable calculation of \code{log(exp(x) + exp(y))} of two numbers \code{x} and \code{y}
#' 
#' @param x real number
#' @param y real number
#' @return returns \code{log(exp(x) + exp(y))}.
#' @export 
log_add_exp = function(x, y) {
    
    d = x - y;
        
    if (d > 0.0) x + log1p(exp(-d)) else y + log1p(exp(d))
    
}

#' Logarithm of sum of exponentials
#' 
#' Stable calculation of \code{log(sum(exp(x)))} of a numeric or integer object \code{x}
#' 
#' @param x numeric or integer object in either vector or matrix form
#' @return the logarithm of the sum of exponentials in \code{x}
#' @export
log_sum_exp = function(x) {
    
    m = max(x)
    y = exp(x - m)
    log(sum(y)) + m
    
}

#' Softmax
#' 
#' Stable calculation of \code{exp(x)/sum(exp(x))} of a numeric 
#' or integer object \code{x}
#' 
#' @param x numeric or integer object in either vector or matrix form
#' @return returns the softmax vector
#' @export 
softmax = function(x) {
    
    m = max(x)
    y = exp(x - m)
    y / sum(y)
    
}

#' Log-Softmax
#' 
#' Stable calculation of \code{log(exp(x)/sum(exp(x)))} of a numeric 
#' or integer object \code{x}
#' 
#' @param x numeric or integer object in either vector or matrix form
#' @return returns the log-softmax vector
#' @export 
log_softmax = function(x) {
    
    x - log_sum_exp(x)
    
}

#' Logit Function
#' 
#' Calculates the logit function
#' 
#' @param x numeric
#' @return returns the logit of \code{x}
#' @export
logit = function(x) {
    
    log(x) - log1p(-x)
    
}

#' Inverse-Logit Function
#' 
#' Calculates the inverse of the logit function (also called the logistic transform)
#' 
#' @param x numeric
#' @return returns the inverse-logit of \code{x}
#' @export
inv_logit = function(x) {
    
    1 / (1 + exp(-x))
    
}

#' Running average over numeric vector
#' 
#' Calculates the running average (moving average) over a numeric vector
#' 
#' @param x numeric vector
#' @param w size of window
#' @param org_length if TRUE, returns a vector of the same length as \code{x}
#' @return returns the running average of vector \code{x} with window \code{w}
#' @details if \code{org_length = TRUE}, the function returns a vector of the same length as \code{x} by appending \code{NA} values at the start and the end of the vector of running averages. If \code{w} is an odd number greater than 1, \code{(w - 2) / 2} \code{NA} values will be attached at the start and the end of the running average, so that each running average is matched with the mid-point of the interval over which it is calculated. If \code{w} is an even number greater than 0, \code{w/2} \code{NA} values will be attached at the start and \code{w/2 - 1} values at the end of vector of running averages, so that the running averages are matched with corresponding elements in \code{x} with the smallest integer value larger than the midpoint of the window. For example, the 6th element of the returned vector will correspond to the average of the \code{c(4,5,6,7)} elements of \code{x} when a window size of 4 is requested.
#' @export 
run_mean = function(x, w = 1, org_length = FALSE) {
    
    y = .run_mean(x, w)
    
    if (!org_length) return(y)
    
    if (w != 1 && w %% 2 == 0) 
        y = c(rep(NA, w/2), y, rep(NA, w/2 - 1))
    else 
        y = c(rep(NA, (w - 1)/2), y, rep(NA, (w - 1)/2))
        
    return (y)
        
}