Package 'admvn'

Description

Genz quasi-Monte Carlo MVN probabilities with gradient and Hessian, SUN(3,3)/SUN(4,4) log-densities with derivatives with respect to a block-Cholesky parameter vector, and KL minimisation of SUN approximations on weighted Gauss-Hermite quadrature.

Author(s)

Maintainer: Patrick Brown [email protected] [copyright holder]

Authors:

• Patrick Brown [email protected] [copyright holder]

Description

Evaluates the log-density (or density) of a SUN(3,3) distribution using the block-Cholesky parameterization from make_sun_params(). For a matrix of observations the returned value is the summed log-likelihood, or a weighted sum if weights is supplied. Derivatives are with respect to the 21-component parameter vector only; the data are treated as fixed.

Usage

dsun(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Value

A list with value and error. If deriv >= 1, also gradient (length 21). If deriv >= 2, also hessian ($21 \times 21$).

See Also

make_sun_params(), dsun_fun()

Description

Builds per-observation CppAD shard tapes for the summed SUN log-likelihood with the data x fixed and the independent variables equal to the 21-parameter vector. Use this for MLE: build once, then call $eval(par) at new parameter values. Pass weights for a weighted sum (e.g. Gauss–Hermite KL objectives).

Usage

dsun_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Value

An object of class "admvn_sun_tape" with components eval(par, log = TRUE, deriv = 0, n_threads = 0) and optim_fns() for optim(): fn/gr share one deriv = 1 evaluation cached by parameter value.

Description

Like dsun(), but the length-21 parameter vector uses the joint hyperspherical map of make_sun_hs_params() instead of the block-Cholesky layout of make_sun_params().

Usage

dsun_hs(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Value

A list with value and error. If deriv >= 1, also gradient. If deriv >= 2, also hessian.

See Also

make_sun_hs_params(), dsun_hs_fun(), dsun()

Description

Like dsun_fun(), for the joint hyperspherical parameterization of make_sun_hs_params().

Usage

dsun_hs_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Value

An object of class "admvn_sun_tape" with eval() and optim_fns() (same interface as dsun_fun()).

See Also

dsun_hs(), sun_mle()

Description

Evaluates the log-density (or density) of a SUN(2,2) distribution using the block-Cholesky parameterization from make_sun22_params(). For a matrix of observations the returned value is the summed log-likelihood, or a weighted sum if weights is supplied. Derivatives are with respect to the 10-component parameter vector only.

Usage

dsun22(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Value

A list with value and error. If deriv >= 1, also gradient (length 10). If deriv >= 2, also hessian ($10 \times 10$).

See Also

make_sun22_params(), dsun22_fun(), dsun()

Description

Builds per-observation CppAD shard tapes for the (weighted) SUN(2,2) log-likelihood with data x fixed. Use for KL / MLE: build once, then call $eval(par) or $optim_fns().

Usage

dsun22_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Value

An object of class "admvn_sun22_tape" with eval() and optim_fns() (cached fn/gr).

Description

SUN(2,2) density with joint hyperspherical parameterization

Usage

dsun22_hs(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Description

Create a reusable SUN(2,2) hyperspherical likelihood tape

Usage

dsun22_hs_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Description

SUN(3,2) density with joint hyperspherical parameterization

Usage

dsun32_hs(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Description

Create a reusable SUN(3,2) hyperspherical likelihood tape

Usage

dsun32_hs_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Description

SUN(4,2) density with joint hyperspherical parameterization

Usage

dsun42_hs(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Description

Create a reusable SUN(4,2) hyperspherical likelihood tape

Usage

dsun42_hs_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Description

SUN(4,3) density with joint hyperspherical parameterization

Usage

dsun43_hs(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Description

Create a reusable SUN(4,3) hyperspherical likelihood tape

Usage

dsun43_hs_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Description

Evaluates the log-density (or density) of a SUN(4,4) distribution using the block-Cholesky parameterization from make_sun44_params(). For a matrix of observations the returned value is the summed log-likelihood, or a weighted sum if weights is supplied. Derivatives are with respect to the 36-component parameter vector only.

Usage

dsun44(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Details

Orthant probabilities use Genz QMC with CppAD (dimension 4), so prefer a modest n_points/n_shifts budget for speed.

Value

A list with value and error. If deriv >= 1, also gradient (length 36). If deriv >= 2, also hessian ($36 \times 36$).

See Also

make_sun44_params(), dsun44_fun(), dsun()

Description

Builds per-observation CppAD shard tapes for the (weighted) SUN(4,4) log-likelihood with data x fixed. Use for KL / MLE: build once, then call $eval(par) or $optim_fns().

Usage

dsun44_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Value

An object of class "admvn_sun44_tape" with eval() and optim_fns() (cached fn/gr).

Description

SUN(4,4) density with joint hyperspherical parameterization

Usage

dsun44_hs(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Description

Create a reusable SUN(4,4) hyperspherical likelihood tape

Usage

dsun44_hs_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Description

SUN(5,2) density with joint hyperspherical parameterization

Usage

dsun52_hs(
  x,
  par,
  log = TRUE,
  deriv = 0L,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = 1L,
  weights = NULL
)

Arguments

Description

Create a reusable SUN(5,2) hyperspherical likelihood tape

Usage

dsun52_hs_fun(
  x,
  par_seed,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L,
  n_threads = NULL,
  weights = NULL
)

Arguments

Description

Uses dsun22_fun() (not sn) so the score matches the AD optim objective.

Usage

evaluate_sun22_slice(par, quad, n_points = 64L, n_shifts = 2L, n_threads = 1L)

Arguments

Value

Named vector c(kl, neg_Elq). kl is NA if logp is missing.

Description

Slice KL / cross-entropy of a SUN(3,2) hyperspherical fit

Usage

evaluate_sun32_hs_slice(
  par,
  quad,
  n_points = 64L,
  n_shifts = 2L,
  n_threads = 1L
)

Arguments

Description

Like evaluate_sun33_slice(), but uses dsun_hs_fun() and make_sun_hs_params().

Usage

evaluate_sun33_hs_slice(
  par,
  quad,
  n_points = 64L,
  n_shifts = 2L,
  n_threads = 1L
)

Arguments

Description

Uses dsun_fun() (not sn) so the score matches the AD optim objective.

Usage

evaluate_sun33_slice(par, quad, n_points = 64L, n_shifts = 2L, n_threads = 1L)

Arguments

Value

Named vector c(kl, neg_Elq). kl is NA if logp is missing.

Description

Slice KL / cross-entropy of a SUN(4,2) hyperspherical fit

Usage

evaluate_sun42_hs_slice(
  par,
  quad,
  n_points = 64L,
  n_shifts = 2L,
  n_threads = 1L
)

Arguments

Description

Slice KL / cross-entropy of a SUN(4,3) hyperspherical fit

Usage

evaluate_sun43_hs_slice(
  par,
  quad,
  n_points = 64L,
  n_shifts = 2L,
  n_threads = 1L
)

Arguments

Description

Uses dsun44_fun() (not sn).

Usage

evaluate_sun44_slice(par, quad, n_points = 256L, n_shifts = 4L, n_threads = 1L)

Arguments

Description

Slice KL / cross-entropy of a SUN(5,2) hyperspherical fit

Usage

evaluate_sun52_hs_slice(
  par,
  quad,
  n_points = 64L,
  n_shifts = 2L,
  n_threads = 1L
)

Arguments

Description

Minimises the weighted cross-entropy $-\sum_i w_i \log q(x_i)$ with analytic gradients from dsun22_fun().

Usage

fit_sun22_quad(
  quad,
  start,
  lower = NULL,
  upper = NULL,
  obj_scale = 10000,
  mc.cores = 1L,
  verbose = FALSE,
  mvquad_opts = list(),
  optim_opts = list()
)

Arguments

Value

A list with fit, par, dp, start, gradient (objective-scale at par), KL / cross-entropy summaries, and engine.

Description

Fit SUN(3,2) hyperspherical by minimising KL on a weighted quadrature

Usage

fit_sun32_hs_quad(
  quad,
  start,
  lower = NULL,
  upper = NULL,
  obj_scale = 10000,
  mc.cores = 1L,
  verbose = FALSE,
  mvquad_opts = list(),
  optim_opts = list()
)

Arguments

Description

Like fit_sun33_quad(), but uses dsun_hs_fun() and defaults from sun33_hs_bounds() / make_sun33_hs_start_from_normal().

Usage

fit_sun33_hs_quad(
  quad,
  start,
  lower = NULL,
  upper = NULL,
  obj_scale = 10000,
  mc.cores = 1L,
  verbose = FALSE,
  mvquad_opts = list(),
  optim_opts = list()
)

Arguments

Description

Minimises the weighted cross-entropy $-\sum_i w_i \log q(x_i)$ with analytic gradients from dsun_fun().

Usage

fit_sun33_quad(
  quad,
  start,
  lower = NULL,
  upper = NULL,
  obj_scale = 10000,
  mc.cores = 1L,
  verbose = FALSE,
  mvquad_opts = list(),
  optim_opts = list()
)

Arguments

Value

A list with fit, par, dp, start, gradient (objective-scale at par), KL / cross-entropy summaries, and engine.

Description

Fit SUN(4,2) hyperspherical by minimising KL on a weighted quadrature

Usage

fit_sun42_hs_quad(
  quad,
  start,
  lower = NULL,
  upper = NULL,
  obj_scale = 10000,
  mc.cores = 1L,
  verbose = FALSE,
  mvquad_opts = list(),
  optim_opts = list()
)

Arguments

Description

Fit SUN(4,3) hyperspherical by minimising KL on a weighted quadrature

Usage

fit_sun43_hs_quad(
  quad,
  start,
  lower = NULL,
  upper = NULL,
  obj_scale = 10000,
  mc.cores = 1L,
  verbose = FALSE,
  mvquad_opts = list(),
  optim_opts = list()
)

Arguments

Description

Like fit_sun33_quad() for SUN(4,4) via dsun44_fun(). Default QMC budget is n_points = 256, n_shifts = 4.

Usage

fit_sun44_quad(
  quad,
  start,
  lower = NULL,
  upper = NULL,
  obj_scale = 10000,
  mc.cores = 1L,
  verbose = FALSE,
  mvquad_opts = list(),
  optim_opts = list()
)

Arguments

Description

Fit SUN(5,2) hyperspherical by minimising KL on a weighted quadrature

Usage

fit_sun52_hs_quad(
  quad,
  start,
  lower = NULL,
  upper = NULL,
  obj_scale = 10000,
  mc.cores = 1L,
  verbose = FALSE,
  mvquad_opts = list(),
  optim_opts = list()
)

Arguments

Description

Product Gauss-Hermite quadrature for $N(\mu,\Sigma)$, returned as abscissae in the original scale and corresponding product weights.

Usage

gh_points(mu, Sigma, n = 15)

Arguments

Value

A list with x ($n^d \times d$ matrix) and w (length $n^d$ weights).

Description

Alternative to make_sun_params(): the latent joint correlation of $(U_\star, V)\in\mathbb{R}^6$ is $J = B B^\top$ with unit-row Cholesky factor $B$ from fifteen unconstrained coordinates $z_{ij}$ via $t_{ij}=\tanh(z_{ij})$. Then $C_u=J_{UU}$, $\Delta=J_{UV}$, $\Gamma=J_{VV}$, and $\Omega=D_u C_u D_u$ with $D_u=\operatorname{diag}(\nu)$.

Usage

make_sun_hs_params(par)

Arguments

Details

The leading six parameters match the block-Cholesky layout (xi, nu), so the C++ sun_mle() driver works unchanged on hyperspherical tapes.

Independent skew-normals. Only the pair slots $z_{4,1},z_{5,2},z_{6,3}$ nonzero (equal to $\operatorname{atanh}(d_i)$) yields $J=\begin{bmatrix}I&D\\D&I\end{bmatrix}$ with $D=\operatorname{diag}(d)$. All $z=0$ recovers a Gaussian.

Fill order. For dimension $d=6$, free entries are filled by rows $i=2,\ldots,6$, columns $j=1,\ldots,i-1$.

Value

A list with components xi, Omega, Delta, tau (fixed at zero), and Gamma.

See Also

make_sun_params(), dsun_hs(), sun33_hs_bounds()

Examples

par <- c(
  xi1 = 0, xi2 = 0, xi3 = 0,
  nu1 = 1, nu2 = 1, nu3 = 1,
  z21 = 0, z31 = 0, z32 = 0,
  z41 = atanh(0.4), z42 = 0, z43 = 0,
  z51 = 0, z52 = atanh(0.3), z53 = 0, z54 = 0,
  z61 = 0, z62 = 0, z63 = atanh(0.2), z64 = 0, z65 = 0
)
dp <- make_sun_hs_params(par)
diag(dp$Gamma)

Description

Converts the SUN(3,3) block-Cholesky parameterization used in the supervision notes into the dp list expected by the sn package (xi, Omega, Delta, tau, Gamma).

Usage

make_sun_params(par)

Arguments

Details

Correlation-scale SUN, then scale. With correlation $C_u$ from the unit-row Cholesky of $(\omega_{12},\omega_{13},\omega_{23})$ and marginal standard deviations $\nu_j>0$, writing $D_u=\operatorname{diag}(\nu)$,

$\Omega = D_u C_u D_u.$

Skew loadings $L$ multiply $C_u$ (not $\Omega$):

$M = L C_u L^\top,\qquad \Sigma_{uv} = D_u C_u L^\top.$

Free $(\gamma_{12},\gamma_{13},\gamma_{23})$ build residual correlation $C$. With $D = \operatorname{diag}(1 - \operatorname{diag}(M))$,

$R = D^{1/2} C D^{1/2},$

so $\Sigma_{vv} = M + R$ is a correlation matrix. Then $\Gamma = \Sigma_{vv}$ and $\Delta = D_u^{-1}\Sigma_{uv} = C_u L^\top$.

Skew loadings. All nine entries of $L$ are free:

$L = \begin{bmatrix} L_{11} & L_{12} & L_{13} \\ L_{21} & L_{22} & L_{23} \\ L_{31} & L_{32} & L_{33} \end{bmatrix}.$

Value

A list with components xi, Omega, Delta, tau (fixed at zero), and Gamma.

Examples

par <- c(
  xi1 = 0, xi2 = 0, xi3 = 0,
  nu1 = 1, nu2 = 1, nu3 = 1,
  omega12 = 0.2, omega13 = 0.1, omega23 = 0.2,
  L11 = 0.4, L12 = 0.1, L13 = 0.1,
  L21 = 0.1, L22 = 0.4, L23 = 0.1,
  L31 = 0, L32 = 0.1, L33 = 0.35,
  gamma12 = 0.3, gamma13 = 0.2, gamma23 = 0.3
)
make_sun_params(par)

Description

The joint correlation of $(U,V)$ is formed from six unconstrained unit-row Cholesky coordinates in row-major order.

Usage

make_sun22_hs_params(par)

Arguments

Value

A SUN dp list with xi, Omega, Delta, zero tau, and Gamma.

See Also

dsun22_hs(), make_sun22_params(), sun22_hs_bounds()

Description

SUN(2,2) hyperspherical start from weighted sample moments

Usage

make_sun22_hs_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-10 parameter vector.

Description

Map mean and covariance to a SUN(2,2) hyperspherical start

Usage

make_sun22_hs_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-10 vector for make_sun22_hs_params().

Description

Converts the SUN(2,2) block-Cholesky parameterization into the dp list expected by the sn package (xi, Omega, Delta, tau, Gamma).

Usage

make_sun22_params(par)

Arguments

Details

As in make_sun_params(): $\Omega = D_u C_u D_u$ with $D_u=\operatorname{diag}(\nu)$, $M = L C_u L^\top$, $\Sigma_{uv} = D_u C_u L^\top$, and $\Sigma_{vv} = M + D^{1/2} C D^{1/2}$ with unit diagonal.

Value

A list with components xi, Omega, Delta, tau (fixed at zero), and Gamma.

See Also

make_sun_params(), dsun22(), dsun22_fun()

Description

SUN(2,2) start from weighted sample moments on a quadrature

Usage

make_sun22_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-10 parameter vector.

Description

Uses marginal standard deviations and unconstrained correlation free parameters for (nu, omega). Skew loadings and residual-correlation free parameters are zero, or a tiny diagonal loading if skew_strength > 0.

Usage

make_sun22_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-10 parameter vector for make_sun22_params().

Description

The joint correlation of $(U,V)\in\mathbb{R}^5$ is formed from ten unconstrained unit-row Cholesky coordinates in row-major order.

Usage

make_sun32_hs_params(par)

Arguments

Value

A SUN dp list with xi, Omega ($3\times 3$), Delta ($3\times 2$), zero tau (length 2), and Gamma ($2\times 2$).

See Also

dsun32_hs(), sun32_hs_bounds()

Description

SUN(3,2) hyperspherical start from weighted sample moments

Usage

make_sun32_hs_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-16 parameter vector.

Description

Exact Gaussian start on the joint hyperspherical layout of make_sun32_hs_params(): the three $U$-block free coordinates come from inverting cov2cor(Sigma); all cross / $V$ coordinates are zero. Optional skew_strength sets pair slots z41,z52 to atanh(skew_strength).

Usage

make_sun32_hs_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-16 parameter vector for make_sun32_hs_params().

Description

SUN(3,3) hyperspherical start from weighted sample moments

Usage

make_sun33_hs_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-21 parameter vector.

Description

Exact Gaussian start on the joint hyperspherical layout of make_sun_hs_params(): the three $U$-block free coordinates come from inverting cov2cor(Sigma); all cross / $V$ coordinates are zero (so $J=\operatorname{blockdiag}(C_u,I)$). Optional skew_strength sets the independent-SN pair slots to atanh(skew_strength).

Usage

make_sun33_hs_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-21 parameter vector for make_sun_hs_params().

Description

SUN(3,3) start from weighted sample moments on a quadrature

Usage

make_sun33_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-21 parameter vector.

Description

Uses marginal standard deviations and unconstrained correlation free parameters for (nu, omega). Skew loadings and residual-correlation free parameters are zero, or a tiny diagonal loading if skew_strength > 0.

Usage

make_sun33_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-21 parameter vector for make_sun_params().

Description

The joint correlation of $(U,V)\in\mathbb{R}^6$ is formed from 15 unconstrained unit-row Cholesky coordinates in row-major order.

Usage

make_sun42_hs_params(par)

Arguments

Value

A SUN dp list with xi, Omega ($4\times 4$), Delta ($4\times 2$), zero tau (length 2), and Gamma ($2\times 2$).

See Also

dsun42_hs(), sun42_hs_bounds()

Description

SUN(4,2) hyperspherical start from weighted sample moments

Usage

make_sun42_hs_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-23 parameter vector.

Description

Exact Gaussian start on the joint hyperspherical layout of make_sun42_hs_params(): the six $U$-block free coordinates come from inverting cov2cor(Sigma); all cross / $V$ coordinates are zero. Optional skew_strength sets pair slots z51,z62 to atanh(skew_strength).

Usage

make_sun42_hs_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-23 parameter vector for make_sun42_hs_params().

Description

The joint correlation of $(U,V)\in\mathbb{R}^7$ is formed from 21 unconstrained unit-row Cholesky coordinates in row-major order.

Usage

make_sun43_hs_params(par)

Arguments

Value

A SUN dp list with xi, Omega ($4\times 4$), Delta ($4\times 3$), zero tau (length 3), and Gamma ($3\times 3$).

See Also

dsun43_hs(), sun43_hs_bounds()

Description

SUN(4,3) hyperspherical start from weighted sample moments

Usage

make_sun43_hs_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-29 parameter vector.

Description

Exact Gaussian start on the joint hyperspherical layout of make_sun43_hs_params(): the six $U$-block free coordinates come from inverting cov2cor(Sigma); all cross / $V$ coordinates are zero. Optional skew_strength sets pair slots z51,z62,z73 to atanh(skew_strength).

Usage

make_sun43_hs_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-29 parameter vector for make_sun43_hs_params().

Description

The joint correlation of $(U,V)$ is formed from 28 unconstrained unit-row Cholesky coordinates in row-major order.

Usage

make_sun44_hs_params(par)

Arguments

Value

A SUN dp list with xi, Omega, Delta, zero tau, and Gamma.

See Also

dsun44_hs(), make_sun44_params(), sun44_hs_bounds()

Description

SUN(4,4) hyperspherical start from weighted sample moments

Usage

make_sun44_hs_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-36 parameter vector.

Description

Map mean and covariance to a SUN(4,4) hyperspherical start

Usage

make_sun44_hs_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-36 vector for make_sun44_hs_params().

Description

Converts the SUN(4,4) block-Cholesky parameterization into the dp list expected by the sn package (xi, Omega, Delta, tau, Gamma).

Usage

make_sun44_params(par)

Arguments

Details

As in make_sun_params(): $\Omega = D_u C_u D_u$ with $D_u=\operatorname{diag}(\nu)$, $M = L C_u L^\top$, $\Sigma_{uv} = D_u C_u L^\top$, and $\Sigma_{vv} = M + D^{1/2} C D^{1/2}$ with unit diagonal.

Value

A list with components xi, Omega, Delta, tau (fixed at zero), and Gamma.

See Also

make_sun_params(), dsun44(), dsun44_fun()

Description

SUN(4,4) start from weighted sample moments on a quadrature

Usage

make_sun44_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-36 parameter vector.

Description

Map mean and covariance to a SUN(4,4) start (zero / tiny skewness)

Usage

make_sun44_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-36 parameter vector for make_sun44_params().

Description

The joint correlation of $(U,V)\in\mathbb{R}^7$ is formed from 21 unconstrained unit-row Cholesky coordinates in row-major order.

Usage

make_sun52_hs_params(par)

Arguments

Value

A SUN dp list with xi, Omega ($5\times 5$), Delta ($5\times 2$), zero tau (length 2), and Gamma ($2\times 2$).

See Also

dsun52_hs(), sun52_hs_bounds()

Description

SUN(5,2) hyperspherical start from weighted sample moments

Usage

make_sun52_hs_start_from_gh(quad, skew_strength = 0.01)

Arguments

Value

Named length-31 parameter vector.

Description

Exact Gaussian start on the joint hyperspherical layout of make_sun52_hs_params(): the ten $U$-block free coordinates come from inverting cov2cor(Sigma); all cross / $V$ coordinates are zero. Optional skew_strength sets pair slots z61,z72 to atanh(skew_strength).

Usage

make_sun52_hs_start_from_normal(mu, Sigma, skew_strength = 0)

Arguments

Value

Named length-31 parameter vector for make_sun52_hs_params().

Description

Converts a covariance matrix into the Genz reordered correlation Cholesky factor and marginal scales used by the CppAD tape. The permutation perm must match the frozen order from pmvn_fun().

Usage

pack_genz_ch(sigma, perm)

Arguments

Value

A list with components scale and ch.

Description

Evaluates $P(\code{lower} < X < \code{upper})$ for $X \sim N(\code{mean}, \code{sigma})$ using Genz's quasi-Monte Carlo algorithm. Returns the probability, a Monte Carlo error estimate, and derivatives of the approximation with respect to upper.

Usage

pmvn(
  upper,
  lower = -Inf,
  mean = 0,
  sigma,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L
)

Arguments

Value

A list with components value, error, gradient, and hessian. The gradient and Hessian are with respect to upper.

Examples

sigma <- matrix(c(1, 0.5, 0.5, 1), 2, 2)
pmvn(c(1, 1), lower = c(-Inf, -Inf), sigma = sigma)

Description

Builds a CppAD tape for the multivariate normal CDF over upper, mean, marginal scales, and the Genz Cholesky factor. The tape is built once; subsequent evaluations pass new parameter values without re-taping. Derivatives with respect to upper use sparse inner patterns (as in adlaplace).

Usage

pmvn_fun(
  lower = -Inf,
  mean = 0,
  sigma,
  n_points = 1021L,
  n_shifts = 8L,
  seed = 1L
)

Arguments

Details

eval(upper, mean = NULL, sigma = NULL, inner = TRUE) evaluates the taped function. When mean or sigma are omitted, build-time values are used. inner = TRUE (default) returns the gradient and Hessian with respect to upper only; inner = FALSE also returns gradient_mean and includes mean, scale, and Cholesky blocks in the sparse derivatives.

Value

An object of class "admvn_tape" with components perm (frozen Genz permutation) and eval().

Examples

sigma <- matrix(c(1, 0.3, 0.3, 1), 2, 2)
f <- pmvn_fun(lower = c(-Inf, -Inf), mean = c(0, 0), sigma = sigma)
f$eval(c(0.5, 0.5))

Description

Print SUN KL fit diagnostics (including gradient)

Usage

print_sun_kl_fit(fit, label = NULL)

Arguments

Value

fit, invisibly.

Description

Maximizes the taped SUN log-likelihood using the quasi-Newton trust-region solver from trustOptim (SR1 by default). The nu components are optimized on the log scale so that they remain positive. The entire optimization runs in C++ with one OpenMP-parallel value+gradient evaluation per iteration.

Usage

sun_mle(tape, start, control = list(), n_threads = 0L)

Arguments

Value

A list with par, value (log-likelihood), gradient, iterations, status, and related fields.

Description

Diagonal loadings L11,L22 are in [-1, 1] (correlation scale). Off-diagonal loadings L12,L21 are in [-0.5, 0.5], matching sun33_bounds().

Usage

sun22_bounds()

Value

List with lower and upper length-10 numeric vectors.

See Also

make_sun22_params(), fit_sun22_quad()

Description

Independent-SN pair slots use atanh(+/-0.8) and all other joint coordinates use atanh(+/-0.5).

Usage

sun22_hs_bounds()

Value

List of length-10 lower and upper vectors.

Description

Pair slots linking $V_i$ to $U_i$ for $i=1,2$ (z41, z52) use atanh(+/-0.8); other joint coordinates use atanh(+/-0.5).

Usage

sun32_hs_bounds()

Value

List of length-16 lower and upper vectors.

Description

Diagonal loadings L11,L22,L33 are in [-1, 1] (correlation scale). Off-diagonal loadings Lij/Lji are in [-0.5, 0.5].

Usage

sun33_bounds()

Value

List with lower and upper length-21 numeric vectors.

See Also

make_sun_params(), fit_sun33_quad()

Description

Soft boxes on the joint unit-row Cholesky coordinates of make_sun_hs_params(): independent-SN pair slots z41,z52,z63 lie in atanh(+/-0.8); all other z* lie in atanh(+/-0.5). These are regularization / start boxes, not a Gershgorin PD certificate.

Usage

sun33_hs_bounds()

Value

List with lower and upper length-21 numeric vectors.

See Also

make_sun_hs_params(), dsun_hs()

Description

Pair slots linking $V_i$ to $U_i$ for $i=1,2$ (z51, z62) use atanh(+/-0.8); other joint coordinates use atanh(+/-0.5).

Usage

sun42_hs_bounds()

Value

List of length-23 lower and upper vectors.

Description

Pair slots linking $V_i$ to $U_i$ for $i=1,2,3$ (z51, z62, z73) use atanh(+/-0.8); other joint coordinates use atanh(+/-0.5).

Usage

sun43_hs_bounds()

Value

List of length-29 lower and upper vectors.

Description

Skew loadings Lij act on the correlation scale, so they are restricted to [-1, 1].

Usage

sun44_bounds()

Value

List with lower and upper length-36 numeric vectors.

See Also

make_sun44_params(), fit_sun44_quad()

Description

Independent-SN pair slots use atanh(+/-0.8) and all other joint coordinates use atanh(+/-0.5).

Usage

sun44_hs_bounds()

Value

List of length-36 lower and upper vectors.

Description

Pair slots linking $V_i$ to $U_i$ for $i=1,2$ (z61, z72) use atanh(+/-0.8); other joint coordinates use atanh(+/-0.5).

Usage

sun52_hs_bounds()

Value

List of length-31 lower and upper vectors.

Description

Weighted covariance

Usage

weighted_cov(X, w)

Arguments

Value

Symmetric ncol(X) covariance matrix.

Description

Weighted column means

Usage

weighted_mean(X, w)

Arguments

Value

Named numeric vector of length ncol(X).