% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/summary_functions.R
\name{bias}
\alias{bias}
\title{Compute (relative/standardized) bias summary statistic}
\usage{
bias(
  estimate,
  parameter = NULL,
  type = "bias",
  center = mean,
  deviance = colSDs,
  abs = FALSE,
  percent = FALSE,
  unname = FALSE
)
}
\arguments{
\item{estimate}{a \code{numeric} vector, \code{matrix}/\code{data.frame}, or \code{list}
of parameter estimates. If a vector,
the length is equal to the number of replications. If a \code{matrix}/\code{data.frame},
the number of rows must equal the number of replications. \code{list} objects will be looped
over using the same rules after above after first translating the information into one-dimensional
vectors and re-creating the structure upon return}

\item{parameter}{a \code{numeric} scalar/vector indicating the fixed parameters.
If a single value is supplied and \code{estimate} is a \code{matrix}/\code{data.frame}
then the value will be recycled for each column; otherwise, each element will be associated
with each respective column in the \code{estimate} input.
If \code{NULL} then it will be assumed that the \code{estimate} input is in a deviation
form (therefore \code{mean(estimate))} will be returned)}

\item{type}{type of bias statistic to return. Default (\code{'bias'}) computes the standard bias
(average difference between sample and population), \code{'relative'} computes
the relative bias statistic (i.e., divide the bias by the value
in \code{parameter}; note that multiplying this by 100 gives the "percent bias" measure, or
if Type I error rates (\eqn{\alpha}) are supplied will result in the "percentage error"),
\code{'abs_relative'} computes the relative bias for each replication independently, takes the
absolute value of each term, then computes the mean estimate,
and \code{'standardized'} computes the standardized bias estimate
(standard bias divided by the standard deviation of the sample estimates)}

\item{center}{function to compute the central tendency. Default uses \code{\link{mean}},
reflecting the canonical \eqn{mean(\hat{p}_i - p)} difference,
 but other options can be supplied to provide more robust central tendency estimates, such as
\code{\link{median}} or \code{\(x) mean(x, trim = 0.1)}}

\item{deviance}{function to compute the deviance criterion, currently used when
\code{type = 'standardize'}. Default uses \code{\link{colSDs}},
reflecting the canonical standard deviation of an incoming \code{matrix} object (required),
but other options can be supplied to provide more robust deviation estimates, such as
\code{\(x) apply(x, 2, IQR)} for the interquartile range. Note that if using an alternative
\code{center} then, if relevant, this should be adjusted too}

\item{abs}{logical; find the absolute bias between the parameters and estimates? This effectively
just applies the \code{\link{abs}} transformation to the returned result. Default is FALSE}

\item{percent}{logical; change returned result to percentage by multiplying by 100?
Default is FALSE}

\item{unname}{logical; apply \code{\link{unname}} to the results to remove any variable
names?}
}
\value{
returns a \code{numeric} vector indicating the overall (relative/standardized)
  bias in the estimates
}
\description{
Computes the (relative) bias of a sample estimate from the parameter value.
Accepts estimate and parameter values, as well as estimate values which are in deviation form.
If relative bias is requested the \code{estimate} and \code{parameter} inputs are both required.
}
\examples{

pop <- 2
samp <- rnorm(100, 2, sd = 0.5)
bias(samp, pop)
bias(samp, pop, type = 'relative')
bias(samp, pop, type = 'standardized')
bias(samp, pop, type = 'abs_relative')

dev <- samp - pop
bias(dev)

# equivalent here
bias(mean(samp), pop)

# different center function
bias(samp, pop, center=median)  # median instead of mean

# matrix input
mat <- cbind(M1=rnorm(100, 2, sd = 0.5), M2 = rnorm(100, 2, sd = 1))
bias(mat, parameter = 2)
bias(mat, parameter = 2, type = 'relative')
bias(mat, parameter = 2, type = 'standardized')

# different parameter associated with each column
mat <- cbind(M1=rnorm(1000, 2, sd = 0.25), M2 = rnorm(1000, 3, sd = .25))
bias(mat, parameter = c(2,3))
bias(mat, parameter = c(2,3), type='relative')
bias(mat, parameter = c(2,3), type='standardized')

# same, but with data.frame
df <- data.frame(M1=rnorm(100, 2, sd = 0.5), M2 = rnorm(100, 2, sd = 1))
bias(df, parameter = c(2,2))

# parameters of the same size
parameters <- 1:10
estimates <- parameters + rnorm(10)
bias(estimates, parameters)


# relative difference dividing by the magnitude of parameters
bias(estimates, parameters, type = 'abs_relative')

# relative bias as a percentage
bias(estimates, parameters, type = 'abs_relative', percent = TRUE)

# percentage error (PE) statistic given alpha (Type I error) and EDR() result
# edr <- EDR(results, alpha = .05)
edr <- c(.04, .05, .06, .08)
bias(matrix(edr, 1L), .05, type = 'relative', percent = TRUE)


}
\references{
Chalmers, R. P., & Adkins, M. C.  (2020). Writing Effective and Reliable Monte Carlo Simulations
with the SimDesign Package. \code{The Quantitative Methods for Psychology, 16}(4), 248-280.
\doi{10.20982/tqmp.16.4.p248}

Sigal, M. J., & Chalmers, R. P. (2016). Play it again: Teaching statistics with Monte
Carlo simulation. \code{Journal of Statistics Education, 24}(3), 136-156.
\doi{10.1080/10691898.2016.1246953}
}
\seealso{
\code{\link{RMSE}}
}
\author{
Phil Chalmers \email{rphilip.chalmers@gmail.com}
}
