hpa (version 1.1.2)

ihpaDiff: Calculate gradient of interval distribution function hermite polynomial approximation

Description

This function calculates gradient of interval distribution function hermite polynomial approximation.

Usage

ihpaDiff(
  x_lower = matrix(1, 1),
  x_upper = matrix(1, 1),
  pol_coefficients = numeric(0),
  pol_degrees = numeric(0),
  given_ind = logical(0),
  omit_ind = logical(0),
  mean = numeric(0),
  sd = numeric(0),
  type = "pol_coefficients",
  is_parallel = FALSE,
  is_log = FALSE
)

Arguments

x_lower

numeric matrix of lower integration limits. Note that x_lower rows are observations while variables are columns.

x_upper

numeric matrix of upper integration limits. Note that x_upper rows are observations while variables are columns.

pol_coefficients

numeric vector of polynomial coefficients.

pol_degrees

non-negative integer vector of polynomial degrees.

given_ind

logical vector indicating wheather corresponding component is conditioned. By default it is a logical vector of FALSE values.

omit_ind

logical vector indicating wheather corresponding component is omitted. By default it is a logical vector of FALSE values.

mean

numeric vector of expected values.

sd

positive numeric vector of standard deviations.

type

determines the partial derivatives to be included into gradient. If type="pol_coefficients" then gradient will contain partial derivatives respect to polynomial coefficients listed in the same order as pol_coefficients. Other available types are type="mean" and type="sd". For function dhpaDiff it is possible to take gradient respect to the x points setting type="x". For function ihpaDiff it is possible to take gradient respect to the x lower and upper points setting type="x_lower" or type="upper" correspondingly. In order to get full gradient please set type="all".

is_parallel

if TRUE then multiple cores will be used for some calculations. It usually provides speed advantage for large enough samples (about more than 1000 observations).

is_log

logical; if TRUE then probabilities p are given as log(p) or derivatives will be given respect to log(p)

Value

This function returns gradient of interval distribution function hermite polynomial approximation at point x. Gradient elements are determined by the type argument.

Details

Interval distribution function represents probability that random vector components will be greater then values given in x_lower and lower then values that are in x_upper.

Densities hermite polynomial approximation approach has been proposed by A. Gallant and D. W. Nychka in 1987. The main idea is to approximate unknown distribution density with hermite polynomial of degree pol_degree. In this framework hermite polynomial represents adjusted (to insure integration to 1) product of squared polynomial and normal distribution densities. Parameters mean and sd determine means and standard deviations of normal distribution density functions which are parts of this polynomial. For more information please refer to the literature listed below.

Parameters mean, sd, given_ind, omit_ind should have the same length as pol_degrees parameter.

If x has more then one row then the output will be jacobian matrix where rows are gradients.

References

A. Gallant and D. W. Nychka (1987) <doi:10.2307/1913241>

Examples

# NOT RUN {
## Let's approximate some three random variables joint interval distribution
## function (idf) at lower and upper points (0,1, 0.2, 0.3) and 
## (0,4, 0.5, 0.6) correspondingly with hermite polynomial of (1,2,3) 
## degrees which polynomial coefficients equals 1 except coefficient 
## related to x1*(x^3) polynomial element which equals 2.
## Also suppose that normal density related mean vector equals 
## (1.1, 1.2, 1.3) while standard deviations vector is (2.1, 2.2, 2.3).
## In this example let's calculate interval distribution approximating 
## function gradient respect to polynomial coefficients.

# Prepare initial values
x_lower <- matrix(c(0.1, 0.2, 0.3), nrow=1)
x_upper <- matrix(c(0.4, 0.5, 0.6), nrow=1)
mean <- c(1.1, 1.2, 1.3)
sd <- c(2.1, 2.2, 2.3)
pol_degrees <- c(1, 2, 3)

# Create polynomial powers and indexes correspondence matrix
pol_ind <- polynomialIndex(pol_degrees)

# Set all polynomial coefficients to 1
pol_coefficients <- rep(1, ncol(pol_ind))
pol_degrees_n <- length(pol_degrees)

# Assign coefficient 2 to the polynomial element(x1 ^ 1)*(x2 ^ 0)*(x3 ^ 2)
pol_coefficients[apply(pol_ind, 2, function(x) all(x == c(1, 0, 2)))] <- 2

# Visualize correspondence between polynomial 
# elements and their coefficients
as.data.frame(rbind(pol_ind, pol_coefficients),
 row.names = c("x1 power", "x2 power", "x3 power", "coefficients"),
 optional = TRUE)
printPolynomial(pol_degrees, pol_coefficients)

# Calculate idf approximation gradient respect to 
# polynomial coefficients at points x_lower and x_upper
ihpaDiff(x_lower = x_lower, x_upper = x_upper, 
	pol_coefficients = pol_coefficients, pol_degrees = pol_degrees,
	mean = mean, sd = sd)
	
# Condition second component to be 0.7
# Substitute x second component with conditional value 0.7
x_upper <- matrix(c(0.4, 0.7, 0.6), nrow = 1)

# Set TRUE to the second component indicating that it is conditioned
given_ind <- c(FALSE, TRUE, FALSE)

# Calculate conditional(on x2 = 0.5) idf approximation
# respect to polynomial coefficients at points x_lower and x_upper
ihpaDiff(x_lower = x_lower, x_upper = x_upper,
	pol_coefficients = pol_coefficients, pol_degrees = pol_degrees,
	mean = mean, sd = sd,
	given_ind = given_ind)
	
# Consider third component marginal distribution
# conditioned on the second component 0.7 value
# Set TRUE to the first component indicating that it is omitted
omit_ind <- c(TRUE, FALSE, FALSE)

# Calculate conditional (on x2=0.5) marginal (for x3) idf approximation
# respect to:
  # polynomial coefficients
ihpaDiff(x_lower = x_lower, x_upper = x_upper,
	pol_coefficients = pol_coefficients, pol_degrees = pol_degrees,
	mean = mean, sd = sd,
	given_ind = given_ind, omit_ind = omit_ind)
 # mean
ihpaDiff(x_lower = x_lower, x_upper = x_upper,
	pol_coefficients = pol_coefficients, pol_degrees = pol_degrees,
	mean = mean, sd = sd,
	given_ind = given_ind, omit_ind = omit_ind,
	type = "mean")
# sd
ihpaDiff(x_lower = x_lower, x_upper = x_upper,
	pol_coefficients = pol_coefficients, pol_degrees = pol_degrees,
	mean = mean, sd = sd,
	given_ind = given_ind, omit_ind = omit_ind,
	type = "sd")
# x_lower
ihpaDiff(x_lower = x_lower, x_upper = x_upper,
	pol_coefficients = pol_coefficients, pol_degrees = pol_degrees,
	mean = mean, sd = sd,
	given_ind = given_ind, omit_ind = omit_ind,
	type = "x_lower")
# x_upper
ihpaDiff(x_lower = x_lower, x_upper = x_upper,
	pol_coefficients = pol_coefficients, pol_degrees = pol_degrees,
	mean = mean, sd = sd,
	given_ind = given_ind, omit_ind = omit_ind,
	type = "x_upper")
# }