R: Left-truncation of density, probability and quantile of...

dtrunc {sads} | R Documentation

## Left-truncation of density, probability and quantile of distributions

### Description

Returns density, probability, quantile values and random generation for distribution functions left-truncated at a specified value.

### Usage

    dtrunc(f, x, trunc, coef, log = FALSE)
    ptrunc(f, q, trunc, coef, lower.tail=TRUE, log.p=FALSE)
    qtrunc(f, p, trunc, coef, lower.tail = TRUE, log.p = FALSE)
    rtrunc(f, n, trunc, coef)

### Arguments

`f` | character; root name of the density or distribution function to be truncated - e.g., `"lnorm"` for the lognormal distribution; `"geom"` for the geometric distribution.
`x, q` | vector of quantiles.
`trunc` | numeric, `trunc > min(x)`. Truncation value (see details).
`p` | vector of probabilities.
`n` | number of random values to return.
`coef` | numeric named list; parameters values of the density or distribution function, named accordingly (see details).
`log, log.p` | logical; if TRUE, probabilities p are given as log(p).
`lower.tail` | logical; if TRUE (default), probabilities are P[X <= x], otherwise, P[X > x].

### Details

Given a distribution with probability distribution function (PDF) g and cumulative distribution function (CDF) G, a random variable `x` with these distributions left-truncated at `trunc` has its PDF:

g'(x) = g(x)/(1 - G(trunc)) for any x <= trunc and zero otherwise

and CDF:

G'(x) = (G(max(x,trunc)) - G(trunc)) / (1 - G(trunc))

`dtrunc` and `ptrunc` calculates the left-truncated distributions functions g'(x) and G'(x) defined above for a vector of values `x` from any standard distribution function available in R. This means the 'upper tail' of a continuous distribution is rescaled to integrate to one. Accordingly, for discrete distributions, the probabilities for all `x`>trunc are rescaled to sum one. `qtrunc` is the inverse function of `ptrunc`.

Left-truncated distributions can be used to describe the species abundance distributions (SADs), specially for continuous distributions (e.g., truncated lognormal distribution).

### Value

`dtrunc` gives the (log) density defined by `f` left-truncated at `trunc`. `ptrunc` gives the (log) distribution function defined by `f` left-truncated at `trunc`. `qtrunc` gives the quantile of the density defined by `f` left-truncated at `trunc`. `rtrunc` generates a sample from the density defined by `f` left-truncated at `trunc`.

### Source

Codes from Nadarajah and Kotz (2006), which provide a more generic solution for left and right truncation.

### References

Nadarajah, S. and Kotz, S. 2006. R Programs for Computing Truncated Distributions. Journal of Statistical Software 16:Code Snippet 2.

### See Also

Distributions for standard distributions in R; many functions in package sads have an argument `trunc` that allows to simulate and fit truncated distributions for species abundance distributions (e.g., `fitsad` `rsad`, `radpred`, `octavpred`. Package 'VGAM' has truncated versions of many standard functions; see `Truncate-methods` in package distr for general methods to build R objects of truncated distributions.

### Examples

    A <- dtrunc("lnorm", x = 1:5, trunc = 0.5,
           coef = list( meanlog=1, sdlog=1.5 ) )
    ## same as
    B <- dlnorm( 1:5 , meanlog = 1, sdlog = 1.5 ) /
      ( plnorm ( 0.5 , meanlog = 1, sdlog = 1.5, lower = FALSE))
    ## checking
    identical( A, B )

    A <- ptrunc("pois", q = 1:5, trunc = 0,
           coef = list( lambda = 1.5 ) )
    ## same as
    B <- (ppois( 1:5 , lambda = 1.5 ) -
          ppois(0 , lambda = 1.5 ) ) /
      (ppois(0 , lambda = 1.5, lower = FALSE))
    ## checking
    identical(A,B)

    # Random generation
    rtrunc("ls", 100, coef=list(N=1000, alpha=50), trunc=5)

[Package sads version 0.4.2 Index]