parameter_restriction {glinvci}R Documentation

Restrict the parameters space of OU and Brownian motion models.

Description

ou_diagH, ou_diagH_fixedtheta_diagSig, etc., restricts the OU model's parameters. For example, ou_diagH restricts the drift HH to diagonal matrix, and ou_diagH_fixedtheta_diagSig further restricts theta to be a constant and Σx\Sigma_x' to be diagonal. A Brownian motion model can be made by these restriction.

Usage

avail_restrictions

brn_diagSig(parfn)

ou_logdiagH(parfn)

dou_logdiagH(jacfn)

hou_logdiagH(hessfn)

ou_logdiagH_diagSig(parfn)

ou_logspdH_fixedtheta(parfn, theta)

ou_spdH_fixedSig(parfn, Sig)

ou_fixedH_diagSig(parfn, H)

dou_logdiagH_diagSig(jacfn)

dou_logspdH_fixedtheta(jacfn, theta)

dou_spdH_fixedSig(jacfn, Sig)

dou_fixedH_diagSig(jacfn, H)

hou_logdiagH_diagSig(hessfn)

hou_logspdH_fixedtheta(hessfn, jacfn, theta)

hou_spdH_fixedSig(hessfn, jacfn, Sig)

hou_spdH_fixedtheta_fixedSig(hessfn, jacfn, theta, Sig)

hou_fixedH_diagSig(hessfn, H)

nparams_ou_logdiagH(k)

nparams_brn(k)

nparams_ou_spdH_fixedSig(k)

Arguments

parfn

A function that maps from the user-parametrisation to the underlying Gaussian parameters. Each of them returns a vector of concatenated (Φ,w,V)(\Phi, w, V'), where VV' is the lower triangular part of VV, and accepts four arguments: a vector of parameters whose length is specified by the pardims argument to the glinv_gauss function, the branch length leading to the currently processing node, a vector of factors with three levels indicating which dimensions are missing or lost in the mother of the current node, and a vector of factors with the same three levels indicating missingness of the current node.

jacfn

A function that accepts the same arguments as parfn and returns the Jacobian of parfn.

hessfn

A function that accepts the same arguments as parfns and returns a list of three 3D arrays, named Phi, w, V respectively inside the list. ((hessfn)(...))$Phi[m,i,j] contains the cross second-order partial derivative of Φm\Phi_m (here we treat the matrix Φ\Phi as a column-major-flattened vector) with respect to the ii-th andjj-th parameters in the joint (H,θ,Σx)(H,\theta,\Sigma_x') vector, and ((hessfn)(...))$w[m,i,j] and ((hessfn)(...))$V[m,i,j] analogously contains second-order derivative with respect to wmw_m and VmV'_m.

H

A numerical vector containing the (flattened) fixed parameter HH.

theta

A numerical vector containing the (flattened) fixed parameter thetatheta.

Sig

A numerical vector containing the (flattened) fixed parameter Σx\Sigma_x'.

k

An integer. The total number of dimensions of the multivariate traits.

Format

An object of class list of length 4.

Details

How reparametrisation and restriction works

In the simplest form, without any restriction or reparametrisation, the user typically needs to pass oupar, oujac, ouhess, all of which are simply functions which maps from the OU parameters (H,θ,Σx)(H,\theta,\Sigma_x') to the Gaussian paramters (Φi,wi,Vi)(\Phi_i,w_i,V'_i) for each node. For example:

        mod.full = glinv(tree, x0, my_data,
                         parfns  = oupar,
                         pardims = nparams_ou(k),
                         parjacs = oujac,
                         parhess = ouhess)

If one would like to restrict HH to only positively definite diagonal matrices, then the call should become

        mod.pddiag = glinv(tree, x0, my_data,
                           parfns  = ou_logdiagH(oupar),
                           pardims = nparams_ou_logdiagH(k),
                           parjacs = dou_logdiagH(oujac),
                           parhess = hou_logdiagH(ouhess))

Note that there is a naming convention that ou_* should be applied to 'oupar', dou_* to 'oujac', and hou_* to 'ouhess'. d stands for ‘derivative’ and h stands for ‘Hessian’.

In the above call, ou_logdiagH(oupar) accepts the oupar function as argument and returns a new function. This new function behaves the same way as oupar itself, except that it expects its first argument (which is the model parameters) to be of lower dimension, only consisting of (h,θ,Σx)(h,\theta,\Sigma_x') where hh is the diagonal vector of HH. The following example should be illustrative:

        f = ou_logdiagH(oupar)
        par.full = list(H     = matrix(c(3,0,0,2),2,2), # diagonal matrix
                        theta = c(4,5),
                        sig_x = c(1,0.1,1))
        par.restricted = list(H     = log(diag(par.full$H)),
                              theta = par.full$theta,
                              sig_x = par.full$sig_x)
        print(all.equal(f(unlist(par.restricted),1,NULL,NULL),
                        oupar(unlist(par.full),1,NULL,NULL)))
        # [1] TRUE

Pre-defined restrictions

The following table summarises all the pre-defined ou_* functions. See oupar for precise meaning of the (H,θ,Σx)(H,\theta,\Sigma_x') mentioned below.

R function Parameter Format after Restriction
brn* Σx\Sigma_x'. The Brownian motion. HH and θ\theta are zero, thus missing.
*_diagH_* (h,θ,Σx)(h,\theta,\Sigma_x'), with h=diag(H)h=diag(H), and H is a diagonal matrix
*_logdiagH_* (log(h),θ,Σx)(log(h),\theta,\Sigma_x'), with h=diag(H)h=diag(H), and H is a diagonal matrix
*_symH_* (L,θ,Σx)(L,\theta,\Sigma_x'), with LL being lower-triangular part of the symmetric matrix HH
*_spdH_* (L,θ,Σx)(L,\theta,\Sigma_x'), with LL being Cholesky factor of the S.P.D. matrix HH
*_logspdH_* (L,θ,Σx)(L',\theta,\Sigma_x') where LL' equals LL, except that on the diagonals LiL'_i = logLilog L_i
*_fixedH_* (θ,Σx)(\theta,\Sigma_x'). HH is constant, hence missing
*_fixedtheta_* (H,Σx)(H,\Sigma_x'). θ\theta is constant, hence missing
*_fixedSig_* (H,θ)(H,\theta). Σx\Sigma_x is constant, hence missing
*_diagSig_* (H,θ,s)(H,\theta,s) where s=diag(Σxs=diag(\Sigma_x', with Σx\Sigma_x' being a diagonal matrix.

By Cholesky factor, we mean the only the non-zero part of the lower-triangular Cholesky factor. Restricting Σx\Sigma_x' to a diagonal matrix means that Σx\Sigma_x is also diagonal; and the variance of the Brownian motion is log(diag(Σx))log(diag(\Sigma_x')). In other words, the diagonal restriction is placed on Σx\Sigma_x', not Σx\Sigma_x.

Finding a list of these restriction functions

One can use print(avail_restrictions) to see a list of all of these restriction function names.

Calling these restriction functions

All *ou_* or *brn* functions accepts the same arguemnts as ou_logdiagH, dou_logdiagH, hou_logdiagH, nparams_ou_logdiagH as shown in the Usage and Arguments section, except that:

  1. If the reparametrisation contains any Cholesky decomposition (in other words, the function name contains spd or logspd) then in the Hessian-level reparameterisation function (named hou_*) an extra argument jacfn is required.

  2. If the reparametrisation contains any fixed parameters, extra arguments H, theta, or Sig are required, depending what is fixed.

For example, in the Usage section, ou_logspdH_fixedtheta takes an extra argument theta because of (2), and hou_spdH_fixedSig takes extra argument two extra arguments because of both (1) and (2) are true.


[Package glinvci version 1.2.4 Index]