Convert parameters from the math scale to the biological scale

Transforms an unconstrained "math-scale" parameter vector into the corresponding biologically interpretable parameters. The input must be a **named numeric vector** whose names exactly match the canonical schema returned by make_mask_names(p) for some integer \(p \ge 1\).

The canonical names are (in order):

• mu1, mu2, ..., mup

• sigltil1, sigltil2, ..., sigltilp

• sigrtil1, sigrtil2, ..., sigrtilp

• ctil

• pd

• o_par1, o_par2, ..., o_parq where \(q = p(p-1)/2\)

These are the names generated by make_mask_names(p).

Usage

math_to_bio(param_vector)

Arguments

param_vector

A **named** numeric vector of math-scale parameters. The names must be exactly those returned by make_mask_names(p), and the length must equal num_par(p). No missing values are allowed. Passing an unnamed vector or a vector whose names do not match the canonical order will raise an error.

Value

A named list of biological-scale parameters with elements: mu, sigltil, sigrtil, ctil, pd, o_mat.

Details

The transformations applied are:

• mu: identity (unchanged)

• sigltil, sigrtil: exp()

• ctil: identity (unchanged)

• pd: expit()

• o_par: used to build an orthogonal matrix via build_orthogonal_matrix

For p = 1 there are no o_par entries; the orthogonal matrix is simply a 1-by-1 identity.

This is a thin R wrapper around the internal C++ implementation xsdm:::.math_to_bio_cpp. The pre-port pure-R implementation is preserved internally as xsdm:::math_to_bio_r for parity testing.

See also

make_mask_names, num_par, num_env_var, loglik_math, bio_to_math

Examples

# Create your own vector of parameter for p = 1 (no o_par entries),
# We use the function make_mask_names with p = 1 to get the correct names and
# length 
p1_names <- make_mask_names(1)
math_vec <- p1_names
math_vec[] <- c(11, log(1.2), log(0.8), -6.7, -1.13)
# We get a list with parameters in biological scale
math_to_bio(math_vec)
#> $mu
#> [1] 11
#> 
#> $sigltil
#> [1] 1.2
#> 
#> $sigrtil
#> [1] 0.8
#> 
#> $ctil
#> [1] -6.7
#> 
#> $pd
#> [1] 0.2441611
#> 
#> $o_mat
#>      [,1]
#> [1,]    1
#> 

# For p = 2 (includes o_par1) -- using the shipped example vector
math_to_bio(example_1$par_vec)
#> $mu
#> [1] 14.2  6.8
#> 
#> $sigltil
#> [1] 1.4 0.5
#> 
#> $sigrtil
#> [1] 1.35 0.10
#> 
#> $ctil
#> [1] -17.6
#> 
#> $pd
#> [1] 0.9
#> 
#> $o_mat
#>           [,1]       [,2]
#> [1,] 0.9800666 -0.1986693
#> [2,] 0.1986693  0.9800666
#>