Differentiate and expand a matrix exponential model with forward sensitivities

The system is split the way indLin() splits it: a rate matrix that is constant in the states, expressed as k_from_to micro-constants, plus an indLin() forcing carrying everything else. Each sensitivity compartment gets the same rate matrix, the (dA/dp).X cross terms as non-depleting transfers, and its own forcing d(f)/dp + (df/dy).S^p.

Usage

rxSensMatExp(
  model,
  calcSens,
  calcSens2 = NULL,
  calcSens3 = NULL,
  doConst = FALSE,
  env = NULL
)

Arguments

model

rxode2 model, text, or function

calcSens

A character vector of parameter names for which sensitivities should be calculated.

calcSens2

character vector (or NULL) requesting second-order sensitivities rx__sens_<x>_BY_<p>_BY_<q>__ (p over calcSens, q over calcSens2; every calcSens2 element must also be in calcSens). Ignored for linCmt() states (those use Stan forward-AD).

calcSens3

character vector (or NULL) requesting third-order sensitivities rx__sens_<x>_BY_<p>_BY_<q>_BY_<r>__ (r over calcSens3). Requires calcSens2; every calcSens3 element must also be in calcSens2.

doConst

Replace constants with values; By default this is FALSE.

env

A pre-loaded symengine environment (from .rxLoadPrune()) to reuse instead of reloading model; when NULL it is built internally.

Value

A character string representing the matrix exponential sensitivity-expanded model code

See also

Other Sensitivities: rxControlUpdateSens(), rxDfdy(), rxSolveAdjoint(), rxSolveAdjointRk4()

Author

Matthew L. Fidler

Examples

# \donttest{
pk <- function() {
  model({
    d/dt(depot) <- -ka * depot
    d/dt(central) <- ka * depot - cl / v * central
  })
}
sens <- rxSensMatExp(pk, calcSens = c("ka", "cl"))
#>  
#>  
#> ℹ parameter labels from comments are typically ignored in non-interactive mode
#> ℹ Need to run with the source intact to parse comments
#>  
#>  
#> ℹ parameter labels from comments are typically ignored in non-interactive mode
#> ℹ Need to run with the source intact to parse comments
#>  
#>  
#> ℹ parameter labels from comments are typically ignored in non-interactive mode
#> ℹ Need to run with the source intact to parse comments
writeLines(sens)
#> matExp()
#> cmt(depot)
#> cmt(central)
#> cmt(rx__sens_depot_BY_ka__)
#> cmt(rx__sens_central_BY_ka__)
#> cmt(rx__sens_depot_BY_cl__)
#> cmt(rx__sens_central_BY_cl__)
#> k_depot_central = ka
#> k_central_output = cl/v
#> df(depot)/dy(depot) = -ka
#> df(central)/dy(depot) = ka
#> df(central)/dy(central) = -cl/v
#> k_rx__sens_depot_BY_ka___rx__sens_central_BY_ka__ = k_depot_central
#> k_rx__sens_central_BY_ka___output = k_central_output
#> k_depot_rx__sens_depot_BY_ka___nd = -1
#> k_depot_rx__sens_central_BY_ka___nd = 1
#> k_rx__sens_depot_BY_cl___rx__sens_central_BY_cl__ = k_depot_central
#> k_rx__sens_central_BY_cl___output = k_central_output
#> k_central_rx__sens_central_BY_cl___nd = -1/v
# solve the sensitivity model with the matrix exponential
m <- rxode2(sens)
#>  
#>  
ev <- et(amt = 100, cmt = "depot") |> et(c(1, 4, 12))
rxSolve(m, ev, params = c(ka = 1.2, cl = 3.5, v = 25), method = "indLin")
#> ── Solved rxode2 object ──
#> ── Parameters (value$params): ──
#>                                  ka                                  cl 
#>                                 1.2                                 3.5 
#>                                   v   k_depot_rx__sens_depot_BY_ka___nd 
#>                                25.0                                -1.0 
#> k_depot_rx__sens_central_BY_ka___nd 
#>                                 1.0 
#> ── Initial Conditions (value$inits): ──
#>                    depot                  central   rx__sens_depot_BY_ka__ 
#>                        0                        0                        0 
#> rx__sens_central_BY_ka__   rx__sens_depot_BY_cl__ rx__sens_central_BY_cl__ 
#>                        0                        0                        0 
#>                   output 
#>                        0 
#> ── First part of data (object): ──
#> # A tibble: 3 × 15
#>    time k_depot_central k_central_output k_rx__sens_depot_BY_ka___rx__sens_cen…¹
#>   <dbl>           <dbl>            <dbl>                                   <dbl>
#> 1     1             1.2             0.14                                     1.2
#> 2     4             1.2             0.14                                     1.2
#> 3    12             1.2             0.14                                     1.2
#> # ℹ abbreviated name: ¹​k_rx__sens_depot_BY_ka___rx__sens_central_BY_ka__
#> # ℹ 11 more variables: k_rx__sens_central_BY_ka___output <dbl>,
#> #   k_rx__sens_depot_BY_cl___rx__sens_central_BY_cl__ <dbl>,
#> #   k_rx__sens_central_BY_cl___output <dbl>,
#> #   k_central_rx__sens_central_BY_cl___nd <dbl>, depot <dbl>, central <dbl>,
#> #   rx__sens_depot_BY_ka__ <dbl>, rx__sens_central_BY_ka__ <dbl>,
#> #   rx__sens_depot_BY_cl__ <dbl>, rx__sens_central_BY_cl__ <dbl>, …
# }