# R/norm.R In Distributacalcul: Probability Distribution Functions

#### Documented in expValLimNormexpValNormexpValTruncNormmeanExcessNormmgfNormstopLossNormTVatRNormvarNormVatRNorm

#' Normal Distribution
#'
#' @description
#' Normal distribution
#'
#' @details
#' The Normal distribution with mean \eqn{\mu}{mu} and standard deviation
#' \eqn{\sigma}{sigma} has density:
#'   \deqn{\frac{1}{\sqrt{2\pi}\sigma}\textrm{e}^{-\frac{1}{2}\left(\frac{x - \mu}{\sigma}\right)^2}}{f(x) = e^(-(1/2) ((x - mu)/sigma)^2) / ((2 pi)^(1/2) sigma}
#' for \eqn{x \in \mathcal{R}}{x real}, \eqn{\mu \in \mathcal{R}, \sigma > 0}{mu real, sigma > 0}.
#'
#' @template mean-mu-template
#' @template sd-sigma-template
#'
#' @return
#' Function :
#'   \itemize{
#'     \item \code{\link{expValNorm}}  gives the expected value.
#'     \item \code{\link{varNorm}}  gives the variance.
#'     \item \code{\link{expValLimNorm}}  gives the limited mean.
#'     \item \code{\link{expValTruncNorm}}  gives the truncated mean.
#'     \item \code{\link{stopLossNorm}}  gives the stop-loss.
#'     \item \code{\link{meanExcessNorm}}  gives the mean excess loss.
#'     \item \code{\link{VatRNorm}}  gives the Value-at-Risk.
#'     \item \code{\link{TVatRNorm}}  gives the Tail Value-at-Risk.
#'     \item \code{\link{mgfNorm}}  gives the moment generating function (MGF).
#'   }
#'  Invalid parameter values will return an error detailing which parameter is problematic.
#'
#' @name Norm
#'
NULL

#' @rdname Norm
#'
#' @export
#'
#' @examples
#' expValNorm(mean = 3, sd = 5)
#'
expValNorm <- function(mean, sd) {
stopifnot(sd > 0)

mean
}

#' @rdname Norm
#'
#' @export
#'
#' @examples
#' varNorm(mean = 3, sd = 5)
#'
varNorm <- function(mean, sd) {
stopifnot(sd > 0)

sd^2
}

#' @rdname Norm
#'
#' @template d-template
#'
#' @importFrom stats dnorm pnorm
#' @export
#'
#' @examples
#' expValLimNorm(d = 2, mean = 2, sd = 5)
#'
expValLimNorm <- function(d, mean = 0, sd = 1) {
stopifnot(sd > 0)

mean *
stats::pnorm(q = d, mean = mean, sd = sd) -
sd^2 *
stats::dnorm(x = d, mean = mean, sd = sd) +
d *
stats::pnorm(q = d, mean = mean, sd = sd, lower.tail = FALSE)
}

#' @rdname Norm
#'
#' @template d-template
#' @template less.than.d-template
#'
#' @importFrom stats pnorm dnorm
#' @export
#'
#' @examples
#' expValTruncNorm(d = 2, mean = 2, sd = 5)
#'
expValTruncNorm <- function(d, mean = 0, sd = 1, less.than.d = TRUE) {
stopifnot(sd > 0)

if (less.than.d) {
expValTrunc.norm <- mean * stats::pnorm(q = d, mean = mean, sd = sd) -
sd^2 * stats::dnorm(x = d, mean = mean, sd = sd)
} else {
expValTrunc.norm <- mean * stats::pnorm(q = d, mean = mean, sd = sd, lower.tail = FALSE) +
sd^2 * stats::dnorm(x = d, mean = mean, sd = sd)
}

return(expValTrunc.norm)
}

#' @rdname Norm
#'
#' @template d-template
#'
#' @importFrom stats pnorm dnorm
#' @export
#'
#' @examples
#' stopLossNorm(d = 2, mean = 2, sd = 5)
#'
stopLossNorm <- function(d, mean = 0, sd = 1) {
stopifnot(sd > 0)

(mean + d) *
stats::pnorm(q = d, mean = mean, sd = sd, lower.tail = FALSE) -
(sd^2) *
stats::dnorm(x = d, mean = mean, sd = sd)
}

#' @rdname Norm
#'
#' @template d-template
#'
#' @importFrom stats pnorm dnorm
#' @export
#'
#' @examples
#' meanExcessNorm(d = 2, mean = 2, sd = 5)
#'
meanExcessNorm <- function(d, mean = 0, sd = 1) {
stopifnot(sd > 0)

mean +
d -
(sd^2) *
stats::dnorm(x = d, mean = mean, sd = sd) /
stats::pnorm(q = d, mean = mean, sd = sd, lower.tail = FALSE)
}

#' @rdname Norm
#'
#' @note Function VatRNorm is a wrapper of the \code{\link[stats]{qnorm}}
#' function from the stats package.
#'
#' @template kap-template
#'
#' @importFrom stats qnorm
#' @export
#'
#' @examples
#' VatRNorm(kap = 0.8, mean = 3, sd = 5)
#'
VatRNorm <- function(kap, mean = 0, sd = 1) {
stopifnot(kap <= 1, kap >= 0, sd > 0)

stats::qnorm(p = kap, mean = mean, sd = sd)
}

#' @rdname Norm
#'
#' @template kap-template
#'
#' @importFrom stats qnorm dnorm
#' @export
#'
#' @examples
#' TVatRNorm(kap = 0.8, mean = 2, sd = 5)
#'
TVatRNorm <- function(kap, mean = 0, sd = 1) {
stopifnot(kap >= 0, kap < 1, sd > 0)

mean +
(sd / (1 - kap)) *
stats::dnorm(x = stats::qnorm(p = kap))
}

#' @rdname Norm
#'
#' @template t-template
#'
#' @export
#'
#' @examples
#' mgfNorm(t = 1, mean = 3, sd = 5)
#'
mgfNorm <- function(t, mean = 0, sd = 1) {
stopifnot(sd > 0)

exp(mean * t + t^2 * (sd^2) / 2)
}


## Try the Distributacalcul package in your browser

Any scripts or data that you put into this service are public.

Distributacalcul documentation built on May 29, 2024, 9:25 a.m.