What features are available?
Tidying up
It is by design that xpose attempts to align well with
the tidyverse family of R packages, so one focus of the
extension package is to make that alignment a bit more consistent. For
example, xpose::set_var_types accepts character vectors of
column names, but not tidyselection. As such, columns named in a
consistent and tidyselect-friendly way cannot be used to an advantage. A
minimal example can be seen below, but of course there are more complex
situations where this is convenient.
# Unset all example covariates
xpdb_ex_covs <- xp_var(xpdb_ex_pk, type = c("catcov","contcov"), .problem=1) %>%
pull(col)
xpdb_ex_covs
#> [1] "MED1" "MED2" "SEX" "AGE" "CLCR" "WT"
no_covs <- set_var_types(xpdb_ex_pk, .problem=1, na = xpdb_ex_covs)
# set_var_types on xpose_data objects uses xpose::set_var_types
set_var_types(no_covs, .problem=1, catcov = c("MED1","MED2")) %>%
xp_var(type = c("catcov"), .problem=1) %>%
pull(col)
#> [1] "MED1" "MED2"
no_covs %>%
as_xpdb_x() %>%
set_var_types(catcov = starts_with("MED"), .problem=1) %>%
xp_var(type = c("catcov"), .problem=1) %>%
pull(col)
#> [1] "MED1" "MED2"Tidyselection is used fairly heavily in the xpose.xtras
package where it seems intuitive to include it. There are likely
functions that could use it but do not currently. As such, the
documentation does attempt to distinguish where tidyselect
is expected.
Labels, units and (also) levels
Another feature includes a few visual confirmations of variable
units, labels and (new to this package) levels. In xpose,
users are able to add units and labels to any variable, which are stored
in the object and are theoretically used somewhere. This package
attempts to use these communication features more liberally in plots and
for the user, but broader implementation (some of which require changes
to existing xpose functions) is not complete just yet.
With labels and units, these are applied using the conventional
xpose functions. However, unlike in xpose,
these can be confirmed using list_vars() in
xpose.xtras.
w_unit_labs <- xpdb_x %>%
set_var_labels(AGE="Age", MED1 = "Digoxin", .problem = 1) %>%
set_var_units(AGE="yrs")
list_vars(w_unit_labs, .problem = 1)
#> List of available variables for problem no. 1
#> - Subject identifier (id) : ID
#> - Dependent variable (dv) : DV
#> - Independent variable (idv) : TIME
#> - Time after dose (tad) (tad) : TAD
#> - Dose amount (amt) : AMT
#> - Event identifier (evid) : EVID
#> - Model typical predictions (pred) : PRED
#> - Model individual predictions (ipred) : IPRED
#> - Model parameter (param) : KA, CL, V, ALAG1
#> - Eta (eta) : ETA1, ETA2, ETA3
#> - Residuals (res) : CWRES, IWRES, RES, WRES
#> - Categorical covariates (catcov) : SEX [0], MED1 ('Digoxin') [0], MED2 [0]
#> - Continuous covariates (contcov) : CLCR, AGE ('Age', yrs), WT
#> - Compartment amounts (a) : A1, A2
#> - Not attributed (na) : DOSE, SS, II, CPREDLevels can also be added to any variable, but can be especially
useful for categorical covariates (catcov) and categorical
DVs (type catdv, added by this package). The documentation
for set_var_levels() can be referenced for more information
about this, but the example below shows how this feature can be used and
checked.
w_levels <- w_unit_labs %>%
set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin())
list_vars(w_levels, .problem = 1)
#> List of available variables for problem no. 1
#> - Subject identifier (id) : ID
#> - Dependent variable (dv) : DV
#> - Independent variable (idv) : TIME
#> - Time after dose (tad) (tad) : TAD
#> - Dose amount (amt) : AMT
#> - Event identifier (evid) : EVID
#> - Model typical predictions (pred) : PRED
#> - Model individual predictions (ipred) : IPRED
#> - Model parameter (param) : KA, CL, V, ALAG1
#> - Eta (eta) : ETA1, ETA2, ETA3
#> - Residuals (res) : CWRES, IWRES, RES, WRES
#> - Categorical covariates (catcov) : SEX [2], MED1 ('Digoxin') [2], MED2 [0]
#> - Continuous covariates (contcov) : CLCR, AGE ('Age', yrs), WT
#> - Compartment amounts (a) : A1, A2
#> - Not attributed (na) : DOSE, SS, II, CPREDLabels, units and levels also appear in new plotting functions. There are some more complex functions where this renaming has not been implemented, but the plan is to have it be universal eventually.
Note in the categorical plots, the number of individuals represented
by each category is underneath the value. This is similar to the
presentation in the package pmplots,
but uses the existing xpose framework. This option requires
the use of an xp_xtra object, and can be disabled with the
argument show_n=FALSE.
Parameter tables
The get_prm() function in xpose has been
extended to output coefficient of variation percent (CV%) for \(\omega^2\) parameters and shrinkages where
relevant.
get_prm(pheno_final) %>%
select(-c(fixed,m,n))
#> Returning parameter estimates from $prob no.1, subprob no.1, method foce
#> # A tibble: 7 × 9
#> type name label value se rse diagonal cv shk
#> <chr> <chr> <chr> <num:4> <num:4> <num:4> <lgl> <num:4> <num:>
#> 1 the THETA1 "CLpkg" 0.004813 0.0002365 0.04914 NA NA NA
#> 2 the THETA2 "Vpkg" 0.9964 0.02642 0.02652 NA NA NA
#> 3 the THETA3 "RUVADD" 2.784 0.2513 0.09027 NA NA NA
#> 4 ome OMEGA(1,1) "IIVCL" 0.2009 0.05108 0.2543 TRUE 20.30 20.1
#> 5 ome OMEGA(2,1) "" 0.7236 0.2654 0.3668 FALSE NA NA
#> 6 ome OMEGA(2,2) "IIVV" 0.1576 0.02614 0.1659 TRUE 15.86 11.6
#> 7 sig SIGMA(1,1) "" 1 NA NA TRUE NA 19.6There are a few options to change CV% where an opinion might conflict with the default. One such option is to add a description of how the parameter is used, which results in an exact CV% determined through integration to be used. For example, if variability on the weight-normalized clearance and volume of distribution parameters in one of the example models was logit-normally distributed, it could be described as follows.
pheno_final %>%
add_prm_association(CLpkg~logit(IIVCL),Vpkg~logit(IIVV)) %>%
get_prm() %>%
select(-c(fixed,m,n))
#> Returning parameter estimates from $prob no.1, subprob no.1, method foce
#> # A tibble: 7 × 9
#> type name label value se rse diagonal cv shk
#> <chr> <chr> <chr> <num:4> <num:4> <num:4> <lgl> <num:4> <num>
#> 1 the THETA1 "CLpkg" 0.004813 0.0002365 0.04914 NA NA NA
#> 2 the THETA2 "Vpkg" 0.9964 0.02642 0.02652 NA NA NA
#> 3 the THETA3 "RUVADD" 2.784 0.2513 0.09027 NA NA NA
#> 4 ome OMEGA(1,1) "IIVCL" 0.2009 0.05108 0.2543 TRUE 20.19 20.1
#> 5 ome OMEGA(2,1) "" 0.7236 0.2654 0.3668 FALSE NA NA
#> 6 ome OMEGA(2,2) "IIVV" 0.1576 0.02614 0.1659 TRUE 0.05778 11.6
#> 7 sig SIGMA(1,1) "" 1 NA NA TRUE NA 19.6
#> # Parameter table includes the following associations: CLpkg~logit(IIVCL) and
#> Vpkg~logit(IIVV)There is a fair amount of complexity in the get_prm()
extensions, including ability to change parameter value while also
changing standard error and relevant variance-covariance (in position
for the .cov and .cor files). See
?add_prm_association and ?mutate_prm.
