Help for package RcppTN

Type:

Package

Title:

Rcpp-Based Truncated Normal Distribution RNG and Family

Version:

0.2-2

Date:

2017-11-21

Author:

Jonathan Olmsted [aut, cre]

Maintainer:

Jonathan Olmsted <jpolmsted@gmail.com>

Description:

R-level and C++-level functionality to generate random deviates from and calculate moments of a Truncated Normal distribution using the algorithm of Robert (1995) <doi:10.1007/BF00143942>. In addition to RNG, functions for calculating moments, densities, and entropies are provided at both levels.

URL:

http://github.com/olmjo/RcppTN

BugReports:

http://github.com/olmjo/RcppTN/issues

License:

GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]

Suggests:

testthat

LinkingTo:

Rcpp

Imports:

Rcpp

RoxygenNote:

6.0.1

NeedsCompilation:

yes

Packaged:

2017-11-21 10:36:54 UTC; olmjo

Repository:

CRAN

Date/Publication:

2017-11-21 11:42:30 UTC

Truncated Normal Distribution Density

Description

Calculate density of Truncated Normal distributions

Usage

dtn(.x = 0, .mean = rep(0, length(.x)), .sd = rep(1, length(.x)),
  .low = rep(-Inf, length(.x)), .high = rep(Inf, length(.x)),
  .checks = TRUE)

Arguments

.x

Length K vector of the points at which to evaluate the density

.mean

Length K vector with the means of the K Normal distributions *prior* to truncation

.sd

Length K vector with the standard deviations of the K Normal distributions *prior* to truncation

.low

Length K vector with the lower truncation bound of the K Normal distributions *prior* to truncation

.high

Length K vector with the upper truncation bound of the K Normal distributions *prior* to truncation

.checks

Logical indicating whether inputs and outputs should be checked and either stop (for bad inputs) or warn (for likely bad outputs)

Value

Length K vector with the entropies associated with each of the K Truncated Normal distributions

Author(s)

Jonathan Olmsted

Examples

lows <- c(-1, 5, -100, 4, 4, -100, 7)
highs <- c(1, 100, 10, 7, 4.1, 100, 100)
dtn(.x = rep(0, length(lows)),
    .mean = rep(0, length(lows)),
    .sd = rep(1, length(lows)),
    .high = highs
    )

Truncated Normal Distribution Entropy

Description

Calculate entropy of Truncated Normal distributions

Usage

enttn(.mean = rep(0, 1), .sd = rep(1, length(.mean)), .low = rep(-Inf,
  length(.mean)), .high = rep(Inf, length(.mean)))

Arguments

.mean

Length K vector with the means of the K Normal distributions prior to truncation

.sd

Length K vector with the standard deviations of the K Normal distributions prior to truncation

.low

Length K vector with the lower truncation bound of the K Normal distributions prior to truncation

.high

Length K vector with the upper truncation bound of the K Normal distributions prior to truncation

Value

Length K vector with the entropies associated with each of the K Truncated Normal distributions

Author(s)

Jonathan Olmsted

Examples

lows <- c(-1, 5, -100, 4, 4, -100, 7)
highs <- c(1, 100, 10, 7, 4.1, 100, 100)
enttn(.mean = rep(0, length(lows)),
      .sd = rep(1, length(lows)),
      .low = lows,
      .high = highs
      )

Truncated Normal Distribution Expectation

Description

Calculate expectation of Truncated Normal distributions

Usage

etn(.mean = rep(0, 1), .sd = rep(1, length(.mean)), .low = rep(-Inf,
  length(.mean)), .high = rep(Inf, length(.mean)), .checks = TRUE)

Arguments

.mean

Length K vector with the means of the K Normal distributions prior to truncation

.sd

Length K vector with the standard deviations of the K Normal distributions prior to truncation

.low

Length K vector with the lower truncation bound of the K Normal distributions prior to truncation

.high

Length K vector with the upper truncation bound of the K Normal distributions prior to truncation

.checks

Length 1 logical vector indicating whether to perform checks (safer) or not (faster) on the input parameters

Details

The special values of -Inf and Inf are valid values in the .low and .high arguments, respectively.

Value

A length K vector of expectations corresponding to the Truncated Normal distributions. NAs are returned (with a warning) for invalid parameter values.

Author(s)

Jonathan Olmsted

Examples

etn() ## 0
etn(0, 1, -Inf, Inf) ## 0
etn(0, 1, -9999, 9999) ## 0

etn(0, 1, 0, Inf) ## 0.798

etn(0, 1, Inf, -Inf) ## NA with warning

etn(c(0, 0),
    c(1, 1),
    c(-Inf, 5),
    c(1, Inf)
    ) ## multiple expectations

Truncated Normal Distribution RNG

Description

Sample from Truncated Normal distributions

Usage

rtn(.mean = rep(0, 1), .sd = rep(1, length(.mean)), .low = rep(-Inf,
  length(.mean)), .high = rep(Inf, length(.mean)), .checks = TRUE)

Arguments

.mean

Length K vector with the means of the K Normal distributions prior to truncation

.sd

Length K vector with the standard deviations of the K Normal distributions prior to truncation

.low

Length K vector with the lower truncation bound of the K Normal distributions prior to truncation

.high

Length K vector with the upper truncation bound of the K Normal distributions prior to truncation

.checks

Length 1 logical vector indicating whether to perform checks (safer) or not (faster) on the input parameters

Details

The special values of -Inf and Inf are valid values in the .low and .high arguments, respectively. The implementation is from Robert (1995). The computation is written in Rcpp-based C++ code, but respects R's RNG state. The draws from this function are reproducible because it respects R's RNG state. Draws using this algorithm (whether implemented in R code or C++) will be the same if seeded correctly. However, you should not expect these draws to match those from another algorithm.

Value

A length K vector of expectations corresponding to the Truncated Normal distributions. NAs are returned (with a warning) for invalid parameter values.

Author(s)

Jonathan Olmsted

References

Robert, Christian P. “Simulation of truncated normal variables”. Statistics and Computing 5.2 (1995): 121-125. http://dx.doi.org/10.1007/BF00143942

Examples

set.seed(1)
rtn(0, 1, -Inf, Inf) # single draw from a single distribution

## [1] -0.6264538

set.seed(1)
rtn(0, 1, -Inf, Inf) # again, because it respects the RNG state

## [1] -0.6264538

rtn(rep(0, 3),
    rep(1, 3),
    rep(-Inf, 3),
    rep(Inf, 3)
    ) # multiple draws from a single distribution

## [1]  0.1836433 -0.8356286  1.5952808

rtn(c(0, 0),
    c(1, 1),
    c(-Inf, 5),
    c(1, Inf)
    ) # multiple draws, each from a different distribution
## [1] 0.3295078 5.3917301

Truncated Normal Distribution Variance

Description

Calculate variance of Truncated Normal distributions

Usage

vtn(.mean = rep(0, 1), .sd = rep(1, length(.mean)), .low = rep(-Inf,
  length(.mean)), .high = rep(Inf, length(.mean)), .checks = TRUE)

Arguments

.mean

Length K vector with the means of the K Normal distributions prior to truncation

.sd

Length K vector with the standard deviations of the K Normal distributions prior to truncation

.low

Length K vector with the lower truncation bound of the K Normal distributions prior to truncation

.high

Length K vector with the upper truncation bound of the K Normal distributions prior to truncation

.checks

Length 1 logical vector indicating whether to perform checks (safer) or not (faster) on the input parameters

Details

The special values of -Inf and Inf are valid values in the .low and .high arguments, respectively.

Value

A length K vector of expectations corresponding to the Truncated Normal distributions. NAs are returned (with a warning) for invalid. parameter values.

Author(s)

Jonathan Olmsted

Examples

vtn() ## 1
vtn(0, 1, -Inf, Inf) ## 1
vtn(0, 1, -9999, 9999) ## 1

vtn(0, 1, 0, Inf) ## 0.36338

vtn(0, 1, Inf, -Inf) ## NA with warning

vtn(c(0, 0),
    c(1, 1),
    c(-Inf, 5),
    c(1, Inf)
    ) ## multiple variances