docopulae (version 0.4.0)

buildf: Build probability density or mass Function

Description

buildf builds a joint probability density or mass function from marginal distributions and a copula.

Usage

buildf(margins, continuous, copula, parNames = NULL,
  simplifyAndCache = T)

Arguments

margins

either

• function(y, theta, ...), where theta is a list of parameters. It shall return a column matrix of two, the probability densities and cumulative distributions.

• a list of pairs of expressions, each named "pdf" and "cdf", the probability density and cumulative distribution.

continuous

TRUE if margins are continuous. See details.

copula

if margins is

• a function then either a copula object from package copula or function(u, theta, ...), a probability density function if continuous else a cumulative distribution function.

• a list then either a copula object from package copula which contains distribution expressions or an expression for the probability density if continuous else the cumulative distribution which uses u1,u2,...

parNames

if

• (optional) margins is a function and copula is a copula object then a vector of names or indices, the sequence of copula parameters in theta. 0 or "" identifies copula parameters to skip.

• margins is a list and copula is a copula object then a named list of names or indices, mapping parameters in theta to copula parameter variables. See copula@exprdist.

simplifyAndCache

(if margins is a list) simplify and cache the result using Simplify and Cache from package Deriv if available.

Value

buildf returns function(y, theta, ...), the joint probability density or mass function.

Details

Please note that expressions are not validated.

If continuous is FALSE, dimensionality shall be 2 and both dimensions shall be discrete. The joint probability mass is defined by $$C(F_{1}(y_{1}),F_{2}(y_{2}))-C(F_{1}(y_{1}-1),F_{2}(y_{2}))-C(F_{1}(y_{1}),F_{2}(y_{2}-1))+C(F_{1}(y_{1}-1),F_{2}(y_{2}-1))$$ where \(C\), \(F_{1}\), and \(F_{2}\) depend on \(\theta\) and \(y_{i}\ge0\).

See Also

copula, Simplify, Cache, numDerivLogf, DerivLogf, fisherI

Examples

# NOT RUN {
## for an actual use case see examples for param

library(copula)
library(mvtnorm)

## build bivariate normal
margins = function(y, theta) {
    mu = c(theta$mu1, theta$mu2)
    cbind(dnorm(y, mean=mu, sd=1), pnorm(y, mean=mu, sd=1))
}
copula = normalCopula()

# args: function, copula object, parNames
f1 = buildf(margins, TRUE, copula, parNames='alpha1')
f1 # uses theta[['alpha1']] as copula parameter

## evaluate and plot
theta = list(mu1=2, mu2=-3, alpha1=0.4)

y1 = seq(0, 4, length.out=51)
y2 = seq(-5, -1, length.out=51)
v1 = outer(y1, y2, function(z1, z2) apply(cbind(z1, z2), 1, f1, theta))
str(v1)
contour(y1, y2, v1, main='f1', xlab='y1', ylab='y2')

## compare with bivariate normal from mvtnorm
copula@parameters = theta$alpha1
v = outer(y1, y2, function(yy1, yy2)
    dmvnorm(cbind(yy1, yy2), mean=c(theta$mu1, theta$mu2),
                             sigma=getSigma(copula)))
all.equal(v1, v)


## build bivariate pdf with normal margins and Clayton copula
margins = list(list(pdf=quote(dnorm(y[1], theta$mu1, 1)),
                    cdf=quote(pnorm(y[1], theta$mu1, 1))),
               list(pdf=quote(dnorm(y[2], theta$mu2, 1)),
                    cdf=quote(pnorm(y[2], theta$mu2, 1))))
copula = claytonCopula()

# args: list, copula object, parNames
f2 = buildf(margins, TRUE, copula, list(alpha='alpha1'))
f2

## evaluate and plot
theta = list(mu1=2, mu2=-3, alpha1=2)

y1 = seq(0, 4, length.out=51)
y2 = seq(-5, -1, length.out=51)
v2 = outer(y1, y2, function(z1, z2) apply(cbind(z1, z2), 1, f2, theta))
str(v2)
contour(y1, y2, v2, main='f2', xlab='y1', ylab='y2')

## build alternatives
cexpr = substituteDirect(copula@exprdist$pdf,
                         list(alpha=quote(theta$alpha1)))
# args: list, expression
f3 = buildf(margins, TRUE, cexpr) # equivalent to f2
f3

margins = function(y, theta) {
    mu = c(theta$mu1, theta$mu2)
    cbind(dnorm(y, mean=mu, sd=1), pnorm(y, mean=mu, sd=1))
}
# args: function, copula object, parNames
f4 = buildf(margins, TRUE, copula, 'alpha1')
f4

cpdf = function(u, theta) {
    copula@parameters = theta$alpha1
    dCopula(u, copula)
}
# args: function, function
f5 = buildf(margins, TRUE, cpdf) # equivalent to f4
f5

# args: function, copula object
copula@parameters = 2
f6 = buildf(margins, TRUE, copula)
f6 # uses copula@parameters

cpdf = function(u, theta) dCopula(u, copula)
# args: function, function
f7 = buildf(margins, TRUE, cpdf) # equivalent to f6
f7

## compare all
vv = lapply(list(f3, f4, f5, f6, f7), function(f)
    outer(y1, y2, function(z1, z2) apply(cbind(z1, z2), 1, f, theta)))
sapply(vv, all.equal, v2)
# }