# R/theil.wtd.R In ReneSchulenberg/test: Decomposition of (income) inequality

#### Documented in theil.wtd

#' @title Theil index
#'
#' @description Returns the (optional weighted) Theil index for a vector.
#'
#' @details The Theil index is a measure of inequality among values of a distribution. It is a
#' member of the Generalized Entropy Measures. Also refered to as GE(1). The index can have a value between 0 and ln N
#' (the logaritm of the number of values), with 0 being the lowest possible inequality. It uses
#' a logarithmic transformation of the values of the distribution. Therefore it cannot
#' handle negative or zero values. Those are excluded from the computation in this function. The
#' Theil Index is more sensitive for changes in the upper tail of the distribution.
#'
#' Extension of the calcGEI function in IC2 package in order to handle missings.
#'
#' @param x a numeric vector containing at least non-negative elements.
#' @param weights an optional vector of weigths of x to be used in the computation of the Theil
#' index. Should be NULL or a numeric vector.
#'
#' @return The value of the Theil index.
#'
#' @examples
#' #calculate Theil Index using Mexican Income data set
#' data(mex_inc_2008)
#'
#' #unweighted Theil Index:
#' theil.wtd(mex_inc_2008$income) #' #' #weighted Theil Index: #' theil.wtd(x=mex_inc_2008$income, weights=mex_inc_2008\$factor)
#'
#' @source
#' Plat, D. (2012). IC2: Inequality and Concentration Indices and Curves. R package
#' version 1.0-1. https://CRAN.R-project.org/package=IC2
#'
#' @references
#' Haughton, J. and S. Khandker. (2009) \emph{Handbook on poverty and inequality},
#' Washington, DC: World Bank.
#'
#' Cowell F. (2000) Measurement of Inequality. In Atkinson A. and Bourguignon F. (eds.) \emph{
#' Handbook of Income Distribution}. Amsterdam: Elsevier, p. 87-166.
#'
#' @export

theil.wtd <- function(x,weights=NULL)
{
if (is.null(weights)){
weights <- rep(1, length(x))}

missing <- !(is.na(x) | is.na(weights))
x <- x[missing]
weights <- weights[missing]
if (!all(weights>=0)) stop("At least one weight is negative", call.=FALSE)
if (all(weights == 0)) stop("All weights are zero", call.=FALSE)

x_sel <- x[x>0]
weights_sel <- weights[x>0]
weights_sel <- weights_sel/sum(weights_sel)
mean <- stats::weighted.mean(x_sel,weights_sel)
x_sel <- x_sel/mean
theil <- (sum(weights_sel*x_sel*log(x_sel)))
return(theil)
}

ReneSchulenberg/test documentation built on Feb. 6, 2018, 3:05 p.m.