| Title: | Extra Functionality for the 'xpose' Package |
|---|---|
| Description: | Adding some at-present missing functionality, or functions unlikely to be added to the base 'xpose' package. This includes some diagnostic plots that have been missing in translation from 'xpose4', but also some useful features that truly extend the capabilities of what can be done with 'xpose'. These extensions include the concept of a set of 'xpose' objects, and diagnostics for likelihood-based models. |
| Authors: | John Prybylski [aut, cre]
|
| Maintainer: | John Prybylski <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.0.2 |
| Built: | 2024-11-25 17:47:12 UTC |
| Source: | CRAN |
Binary check if LHS is parent of LHS
possible_parent %p% possible_childpossible_parent %p% possible_child
possible_parent |
< |
possible_child |
... < |
<logical> TRUE if LHS is parent of RHS
# Detect direct parent pheno_set$run6 %p% pheno_set$run7 # Detect non-parentage (does not try to "flip" parentage) pheno_set$run6 %p% pheno_set$run5 # Does not detect grand-parentage pheno_set$run6 %p% pheno_set$run13# Detect direct parent pheno_set$run6 %p% pheno_set$run7 # Detect non-parentage (does not try to "flip" parentage) pheno_set$run6 %p% pheno_set$run5 # Does not detect grand-parentage pheno_set$run6 %p% pheno_set$run13
The relationship between structural parameters and omega parameters can be described. This is useful if it deviates from the typical log-normal.
Default transformations are those that are built into
pmxcv, but see examples for how associations can be
described for other relationships.
add_prm_association(xpdb, ..., .problem, .subprob, .method, quiet) drop_prm_association(xpdb, ..., .problem, .subprob, .method, quiet)add_prm_association(xpdb, ..., .problem, .subprob, .method, quiet) drop_prm_association(xpdb, ..., .problem, .subprob, .method, quiet)
xpdb |
< |
... |
... < For |
.problem |
< |
.subprob |
< |
.method |
< |
quiet |
Silence extra output. |
At time of writing, the built-in distributions for pmxcv are below.
Those marked with an asterisk require a fixed effect parameter to calculate CV.
log typical log-normal. Optional exact parameter (if TRUE, default, will not
calculate with integration); this is unrelated to the cvtype option. Note,
if cvtype is set to "sqrt", log-normal gte_prm CVs will use the square root, not any integration
or analytical estimate, regardless of how this association is specified..
logexp* modified log-normal log(1+X)
logit* logit-normal
arcsin* arcsine-transform
nmboxcox* Box-Cox transform as typically implemented in pharmacometrics.
Requires a lambda parameter.
To pass a custom parameter, use custom transform, and pass pdist and qdist to
that transform. See Examples.
Reminder about qdist and pdist: Consider that qlogis transforms a proportion
to a continuous, unbounded number; it is the logit transform. The pdist function
converts a continuous, unbounded number to a proportion; it is the inverse logit
transform. Other R stats functions work similarly, and as such functions used as
qdist and pdist values are expected to act similarly.
Note that the functions used in describing associations are not real functions,
it is just the syntax for this application. Based on examples, be mindful of
where positional arguments would acceptable and where named arguments are
required. Care has been given to provide a modest amount of flexibility
with informative errors for fragile points, but not every error can be anticipated.
If this function or downstream results from it seem wrong, the association syntax
should be scrutinized. These "functions" are not processed like in mutate_prm,
so (eg) the2 will not be substituted for the value of the2; if
lambda is a fitted value (like the2), in that edge case the value of the2 should be written
explicitly in the association formula, and if any mutate_prm changes the2 then users
should be mindful of the new association needed. This may be updated in the future.
Format for associations is:
LHS~fun(OMEGA, args...)
LHS: Selector for a fixed effect parameter. Can be the{m} (eg, the1),
{name} (eg, THETA1) or {label} (eg, TVCL). These should not be quoted.
Multiple associations can be defined at once with +. Cannot be empty.
RHS: Should be a simple call to only one function, which should be
custom or one of the built-in distributions or custom(...). A lot of things
can look like simple calls, so may not break immediately; keep to the described
format and everything should be fine.
RHS OMEGA: Selector for omega variable. Similar rules to the fixed
effect selector. Can be ome{m}, {name} or {label}, limited to diagonal
elements. Should not be quoted. OMEGA is not a named argument (OMEGA={selector}
should not be considered valid); whatever is used as the first argument to the
"function" will be considered an OMEGA selector. NOTE, if selecting an OMEGA parameter
by name (eg, OMEGA(2,2)), backticks (eg `OMEGA(2,2)`) must be used or else the selection will throw
an error.
RHS args: Applies when the distribution has extra arguments. If these
are limited to 1, can be passed by position (eg, lambda for nmboxcox and
exact for log). For custom(), qdist, pdist and any arguments needed to
pass to them should be named.
For the nmboxcox transformation, a lambda value (especially negative ones) may
not work well with the integration-based CV estimation. This may occur even if
the lambda is fitted and stable in that fitting, but it cannot be predicted which
ones will be affected. This note is intended to forewarn that this might happen.
An updated xp_xtras object
Prybylski, J.P. Reporting Coefficient of Variation for Logit, Box-Cox and Other Non-log-normal Parameters. Clin Pharmacokinet 63, 133-135 (2024). https://doi.org/10.1007/s40262-023-01343-2
pheno_base %>% add_prm_association(the1~log(IIVCL),V~log(IIVV)) %>% get_prm() # get_prm is the only way to see the effect of associations # These values are not fitted as logit-normal, but # just to illustrate: pheno_final %>% add_prm_association(the1~logit(IIVCL),Vpkg~logit(IIVV)) %>% get_prm() # ... same for Box-Cox pheno_base %>% add_prm_association(V~nmboxcox(IIVV, lambda=0.5)) %>% # Naming the argument is optional add_prm_association(CL~nmboxcox(IIVCL, -0.1)) %>% get_prm() # A 'custom' use-case is when logexp, log(1+X), is # desired but 1 is too large. # Again, for this example, treating this like it applies here. pheno_base %>% add_prm_association(V~custom(IIVV, qdist=function(x) log(0.001+x), pdist=function(x) exp(x)-0.001)) %>% get_prm() # Dropping association is easy bad_assoc <- pheno_final %>% add_prm_association(the1~logit(IIVCL),Vpkg~logit(IIVV)) bad_assocpheno_base %>% add_prm_association(the1~log(IIVCL),V~log(IIVV)) %>% get_prm() # get_prm is the only way to see the effect of associations # These values are not fitted as logit-normal, but # just to illustrate: pheno_final %>% add_prm_association(the1~logit(IIVCL),Vpkg~logit(IIVV)) %>% get_prm() # ... same for Box-Cox pheno_base %>% add_prm_association(V~nmboxcox(IIVV, lambda=0.5)) %>% # Naming the argument is optional add_prm_association(CL~nmboxcox(IIVCL, -0.1)) %>% get_prm() # A 'custom' use-case is when logexp, log(1+X), is # desired but 1 is too large. # Again, for this example, treating this like it applies here. pheno_base %>% add_prm_association(V~custom(IIVV, qdist=function(x) log(0.001+x), pdist=function(x) exp(x)-0.001)) %>% get_prm() # Dropping association is easy bad_assoc <- pheno_final %>% add_prm_association(the1~logit(IIVCL),Vpkg~logit(IIVV)) bad_assoc
Add relationship(s) to an xpose_set
add_relationship(xpdb_s, ..., .warn = TRUE, .remove = FALSE) remove_relationship(xpdb_s, ...)add_relationship(xpdb_s, ..., .warn = TRUE, .remove = FALSE) remove_relationship(xpdb_s, ...)
xpdb_s |
< |
... |
< |
.warn |
< |
.remove |
< |
An xpose_set object with relationships added
xpdb_set %>% add_relationship(mod1~fix2) # ouroboros xpdb_set %>% remove_relationship(fix1~mod2) # split down the middlexpdb_set %>% add_relationship(mod1~fix2) # ouroboros xpdb_set %>% remove_relationship(fix1~mod2) # split down the middle
xpdb objects to an xpose_set
Add one or more xpdb objects to an xpose_set
add_xpdb(xpdb_s, ..., .relationships = NULL)add_xpdb(xpdb_s, ..., .relationships = NULL)
xpdb_s |
< |
... |
< |
.relationships |
< |
An xpose_set object with the new xpdb objects added
data("xpdb_ex_pk", package = "xpose") add_xpdb(xpdb_set, ttt=xpdb_ex_pk)data("xpdb_ex_pk", package = "xpose") add_xpdb(xpdb_set, ttt=xpdb_ex_pk)
Level-defining helper functions
as_leveler(x, .start_index = 1) is_leveler(x) lvl_bin(x = c("No", "Yes"), .start_index = 0) lvl_sex() lvl_inord(x, .start_index = 1)as_leveler(x, .start_index = 1) is_leveler(x) lvl_bin(x = c("No", "Yes"), .start_index = 0) lvl_sex() lvl_inord(x, .start_index = 1)
x |
< |
.start_index |
< |
Special character vector suitable to be used as leveler
set_var_levels(xpdb_x, SEX = lvl_sex(), MED1 = lvl_bin(), MED2 = lvl_inord(c("n","y"), .start_index = 0) )set_var_levels(xpdb_x, SEX = lvl_sex(), MED1 = lvl_bin(), MED2 = lvl_inord(c("n","y"), .start_index = 0) )
xpose_data and xp_xtras objectThis function masks the default in xpose package, adding the
xp_xtras class to default xpose_data objects.
as_xpdb_x(x) as_xp_xtras(x) check_xpdb_x(x, .warn = TRUE) check_xp_xtras(...)as_xpdb_x(x) as_xp_xtras(x) check_xpdb_x(x, .warn = TRUE) check_xp_xtras(...)
x |
Suspected |
.warn |
< |
... |
Forwarded |
<xpose_data> and <xp_xtras> object
xp_x <- as_xpdb_x(xpose::xpdb_ex_pk) check_xpdb_x(xp_x)xp_x <- as_xpdb_x(xpose::xpdb_ex_pk) check_xpdb_x(xp_x)
Add individual objective function to data
backfill_iofv(xpdb, .problem = NULL, .subprob = NULL, .label = "iOFV")backfill_iofv(xpdb, .problem = NULL, .subprob = NULL, .label = "iOFV")
xpdb |
< |
.problem |
Problem number |
.subprob |
Subproblem number |
.label |
The name of the new column. |
This function will only work for objects with software listed as
nonmem, which has a phi file and with an OBJ column in that
file.
<xp_xtras> object with new column in the data and a
column with iofv var type.
xpdb_x %>% backfill_iofv() %>% list_vars()xpdb_x %>% backfill_iofv() %>% list_vars()
These plots attempt to provide a means of verifying that the estimated likelihoods and probabilities for categorical outcomes are captured within the model.
When the smooth spline is included (type includes "s"), it is
expected that the overall trend is up and to the right; a relatively
flat trend suggests that the modeled likelihood is inconsistent with the
observed outcome.
catdv_vs_dvprobs( xpdb, mapping = NULL, cutpoint = 1, type = "vbs", title = "@y vs. @x | @run", subtitle = "Ofv: @ofv, Number of individuals: @nind", caption = "@dir", tag = NULL, xlab = c("probability", "basic"), facets, .problem, quiet, ... )catdv_vs_dvprobs( xpdb, mapping = NULL, cutpoint = 1, type = "vbs", title = "@y vs. @x | @run", subtitle = "Ofv: @ofv, Number of individuals: @nind", caption = "@dir", tag = NULL, xlab = c("probability", "basic"), facets, .problem, quiet, ... )
xpdb |
< |
mapping |
|
cutpoint |
< |
type |
See Details. |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
xlab |
Either use the typical basic x-axis label (the cutpoint-defined column name) or label it based on the probability/likelihood it is estimating. |
facets |
Additional facets |
.problem |
Problem number |
quiet |
Silence extra debugging output |
... |
Any additional aesthetics. |
The desired plot
# Test M3 model pkpd_m3 %>% # Need to ensure var types are set set_var_types(catdv=BLQ,dvprobs=LIKE) %>% # Set probs set_dv_probs(1, 1~LIKE, .dv_var = BLQ) %>% # Optional, but useful to set levels set_var_levels(1, BLQ = lvl_bin()) %>% # Plot with basic xlab makes no assumptions catdv_vs_dvprobs(xlab = "basic") # Test categorical model vismo_xpdb <- vismo_pomod %>% set_var_types(.problem=1, catdv=DV, dvprobs=matches("^P\\d+$")) %>% set_dv_probs(.problem=1, 0~P0,1~P1,ge(2)~P23) # Various cutpoints (note axes labels and texts) vismo_xpdb %>% catdv_vs_dvprobs(xlab = "basic") vismo_xpdb %>% catdv_vs_dvprobs(cutpoint = 2, xlab = "basic") vismo_xpdb %>% catdv_vs_dvprobs(cutpoint = 3, xlab = "basic") # Latter is arguably clearer with default xlab vismo_xpdb %>% catdv_vs_dvprobs(cutpoint = 3)# Test M3 model pkpd_m3 %>% # Need to ensure var types are set set_var_types(catdv=BLQ,dvprobs=LIKE) %>% # Set probs set_dv_probs(1, 1~LIKE, .dv_var = BLQ) %>% # Optional, but useful to set levels set_var_levels(1, BLQ = lvl_bin()) %>% # Plot with basic xlab makes no assumptions catdv_vs_dvprobs(xlab = "basic") # Test categorical model vismo_xpdb <- vismo_pomod %>% set_var_types(.problem=1, catdv=DV, dvprobs=matches("^P\\d+$")) %>% set_dv_probs(.problem=1, 0~P0,1~P1,ge(2)~P23) # Various cutpoints (note axes labels and texts) vismo_xpdb %>% catdv_vs_dvprobs(xlab = "basic") vismo_xpdb %>% catdv_vs_dvprobs(cutpoint = 2, xlab = "basic") vismo_xpdb %>% catdv_vs_dvprobs(cutpoint = 3, xlab = "basic") # Latter is arguably clearer with default xlab vismo_xpdb %>% catdv_vs_dvprobs(cutpoint = 3)
Verify validity of level list
check_levels(lvl_list, index)check_levels(lvl_list, index)
lvl_list |
< |
index |
Index of |
Nothing, warning or error
xpose_set objectCheck an xpose_set object
check_xpose_set(xpdb_s, .warn = TRUE) check_xpose_set_item(xpdb_s_i, .example = xpdb_set)check_xpose_set(xpdb_s, .warn = TRUE) check_xpose_set_item(xpdb_s_i, .example = xpdb_set)
xpdb_s |
< |
.warn |
< |
xpdb_s_i |
< |
.example |
< |
TRUE or error thrown
check_xpose_set(xpdb_set) check_xpose_set_item(xpdb_set$mod1)check_xpose_set(xpdb_set) check_xpose_set_item(xpdb_set$mod1)
A slightly more generic approach to getting model descriptions.
desc_from_comments( xpdb, start_check = ".*description", maxlines = 5, remove = paste0(start_check, ":\\s*"), extra_proc = c, collapse = " " )desc_from_comments( xpdb, start_check = ".*description", maxlines = 5, remove = paste0(start_check, ":\\s*"), extra_proc = c, collapse = " " )
xpdb |
< |
start_check |
Regular expression used to mark start of description. This is tested case-insensitively. |
maxlines |
If the number of lines after description to the first code block is more than 1, this allows a limit. |
remove |
By default, the start check and a colon, with optional whitespace. A regex. |
extra_proc |
Any extra processing that might be desired prior to collapsing the description lines. This should be a vectorized function. |
collapse |
Character to use when collapsing multiple lines. |
The description-updated <xpose_data) object
# This has a description, but it's not visible by default pheno_base # It can be added with the following pheno_base %>% desc_from_comments() # Extra processing for preference can also implemented pheno_base %>% desc_from_comments(extra_proc = tolower) # If a run label ($PROB) would make a good description, use the # following instead: pkpd_m3 %>% set_prop(descr=get_prop(pkpd_m3,"label"))# This has a description, but it's not visible by default pheno_base # It can be added with the following pheno_base %>% desc_from_comments() # Extra processing for preference can also implemented pheno_base %>% desc_from_comments(extra_proc = tolower) # If a run label ($PROB) would make a good description, use the # following instead: pkpd_m3 %>% set_prop(descr=get_prop(pkpd_m3,"label"))
xpose_set
![[Experimental]](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB3aWR0aD0iMTM4IiBoZWlnaHQ9IjIwIiByb2xlPSJpbWciIGFyaWEtbGFiZWw9ImxpZmVjeWNsZTogZXhwZXJpbWVudGFsIj4NCiAgICA8dGl0bGU+bGlmZWN5Y2xlOiBleHBlcmltZW50YWw8L3RpdGxlPg0KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0icyIgeDI9IjAiIHkyPSIxMDAlIj4NCiAgICAgICAgPHN0b3Agb2Zmc2V0PSIwIiBzdG9wLWNvbG9yPSIjYmJiIiBzdG9wLW9wYWNpdHk9Ii4xIiAvPg0KICAgICAgICA8c3RvcCBvZmZzZXQ9IjEiIHN0b3Atb3BhY2l0eT0iLjEiIC8+DQogICAgPC9saW5lYXJHcmFkaWVudD4NCiAgICA8Y2xpcFBhdGggaWQ9InIiPg0KICAgICAgICA8cmVjdCB3aWR0aD0iMTM4IiBoZWlnaHQ9IjIwIiByeD0iMyIgZmlsbD0iI2ZmZiIgLz4NCiAgICA8L2NsaXBQYXRoPg0KICAgIDxnIGNsaXAtcGF0aD0idXJsKCNyKSI+DQogICAgICAgIDxyZWN0IHdpZHRoPSI1NSIgaGVpZ2h0PSIyMCIgZmlsbD0iIzU1NSIgLz4NCiAgICAgICAgPHJlY3QgeD0iNTUiIHdpZHRoPSI4MyIgaGVpZ2h0PSIyMCIgZmlsbD0iI2ZlN2QzNyIgLz4NCiAgICAgICAgPHJlY3Qgd2lkdGg9IjEzOCIgaGVpZ2h0PSIyMCIgZmlsbD0idXJsKCNzKSIgLz4NCiAgICA8L2c+DQogICAgPGcgZmlsbD0iI2ZmZiIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZm9udC1mYW1pbHk9IlZlcmRhbmEsR2VuZXZhLERlamFWdSBTYW5zLHNhbnMtc2VyaWYiIHRleHQtcmVuZGVyaW5nPSJnZW9tZXRyaWNQcmVjaXNpb24iIGZvbnQtc2l6ZT0iMTEwIj4NCiAgICAgICAgPHRleHQgYXJpYS1oaWRkZW49InRydWUiIHg9IjI4NSIgeT0iMTUwIiBmaWxsPSIjMDEwMTAxIiBmaWxsLW9wYWNpdHk9Ii4zIiB0cmFuc2Zvcm09InNjYWxlKC4xKSIgdGV4dExlbmd0aD0iNDUwIj5saWZlY3ljbGU8L3RleHQ+DQogICAgICAgIDx0ZXh0IHg9IjI4NSIgeT0iMTQwIiB0cmFuc2Zvcm09InNjYWxlKC4xKSIgZmlsbD0iI2ZmZiIgdGV4dExlbmd0aD0iNDUwIj5saWZlY3ljbGU8L3RleHQ+DQogICAgICAgIDx0ZXh0IGFyaWEtaGlkZGVuPSJ0cnVlIiB4PSI5NTUiIHk9IjE1MCIgZmlsbD0iIzAxMDEwMSIgZmlsbC1vcGFjaXR5PSIuMyIgdHJhbnNmb3JtPSJzY2FsZSguMSkiIHRleHRMZW5ndGg9IjczMCI+ZXhwZXJpbWVudGFsPC90ZXh0Pg0KICAgICAgICA8dGV4dCB4PSI5NTUiIHk9IjE0MCIgdHJhbnNmb3JtPSJzY2FsZSguMSkiIGZpbGw9IiNmZmYiIHRleHRMZW5ndGg9IjczMCI+ZXhwZXJpbWVudGFsPC90ZXh0Pg0KICAgIDwvZz4NCjwvc3ZnPg0K)
In its current state, this function is intended to
provide a simple visual representation of an xpose_set.
Functionality and aesthetic enhancements are expected in
future releases.
diagram_lineage(xpdb_s, ...)diagram_lineage(xpdb_s, ...)
xpdb_s |
< |
... |
For later expansion. Will be ignored. |
A DiagrammeR-compliant graph object.
diagram_lineage(pheno_set) %>% DiagrammeR::render_graph(layout="tree")diagram_lineage(pheno_set) %>% DiagrammeR::render_graph(layout="tree")
xpose_set
If no base model is provided, and if lineage is unclear,
the first model in the xpose_set is used as the base model.
## S3 method for class 'xpose_set' diff(x, ...)## S3 method for class 'xpose_set' diff(x, ...)
x |
< |
... |
< |
<numeric> vector of deltaOFV values
Check if any xpose_data objects are repeated in xpose_set
## S3 method for class 'xpose_set' duplicated(x, incomparables = FALSE, ...)## S3 method for class 'xpose_set' duplicated(x, incomparables = FALSE, ...)
x |
< |
incomparables |
|
... |
Must be empty |
A logical vector or list of logical vectors
This is for use when the model averaging of a set is planned.
dv_vs_ipred_modavg( xpdb_s, ..., .lineage = FALSE, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet ) dv_vs_pred_modavg( xpdb_s, ..., .lineage = FALSE, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet ) ipred_vs_idv_modavg( xpdb_s, ..., .lineage = FALSE, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet ) pred_vs_idv_modavg( xpdb_s, ..., .lineage = FALSE, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet ) plotfun_modavg( xpdb_s, ..., .lineage = FALSE, avg_cols = NULL, avg_by_type = NULL, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", .fun = NULL, .funargs = list(), quiet )dv_vs_ipred_modavg( xpdb_s, ..., .lineage = FALSE, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet ) dv_vs_pred_modavg( xpdb_s, ..., .lineage = FALSE, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet ) ipred_vs_idv_modavg( xpdb_s, ..., .lineage = FALSE, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet ) pred_vs_idv_modavg( xpdb_s, ..., .lineage = FALSE, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet ) plotfun_modavg( xpdb_s, ..., .lineage = FALSE, avg_cols = NULL, avg_by_type = NULL, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", .fun = NULL, .funargs = list(), quiet )
xpdb_s |
< |
... |
< |
.lineage |
< |
algorithm |
< |
weight_type |
< |
auto_backfill |
< |
weight_basis |
< |
res_col |
< |
quiet |
< |
avg_cols |
< |
avg_by_type |
< |
.fun |
< |
.funargs |
< |
The desired plot
pheno_set %>% dv_vs_ipred_modavg(run8,run9,run10, auto_backfill = TRUE) pheno_set %>% dv_vs_pred_modavg(run8,run9,run10, auto_backfill = TRUE) pheno_set %>% ipred_vs_idv_modavg(run8,run9,run10, auto_backfill = TRUE) pheno_set %>% pred_vs_idv_modavg(run8,run9,run10, auto_backfill = TRUE) # Model averaged ETA covariates pheno_set %>% plotfun_modavg(run8,run9,run10, auto_backfill = TRUE, avg_by_type = "eta",.fun = eta_vs_catcov, # Note quoting .funargs = list(etavar=quote(ETA1)))pheno_set %>% dv_vs_ipred_modavg(run8,run9,run10, auto_backfill = TRUE) pheno_set %>% dv_vs_pred_modavg(run8,run9,run10, auto_backfill = TRUE) pheno_set %>% ipred_vs_idv_modavg(run8,run9,run10, auto_backfill = TRUE) pheno_set %>% pred_vs_idv_modavg(run8,run9,run10, auto_backfill = TRUE) # Model averaged ETA covariates pheno_set %>% plotfun_modavg(run8,run9,run10, auto_backfill = TRUE, avg_by_type = "eta",.fun = eta_vs_catcov, # Note quoting .funargs = list(etavar=quote(ETA1)))
This is essentially a wrapper around ggpairs,
except it uses xpose motifs and styling. Note that this function
produces a lot of repetitive output if quiet=FALSE; this may not
be an issue, but it could look like an error has occurred if many covariates
and individual parameter estimates are included.
eta_grid( xpdb, mapping = NULL, etavar = NULL, drop_fixed = TRUE, title = "Eta correlations | @run", subtitle = "Based on @nind individuals, Eta shrink: @etashk", caption = "@dir", tag = NULL, pairs_opts, .problem, quiet, ... ) cov_grid( xpdb, mapping = NULL, cols = NULL, covtypes = c("cont", "cat"), show_n = TRUE, drop_fixed = TRUE, title = "Covariate relationships | @run", subtitle = "Based on @nind individuals", caption = "@dir", tag = NULL, pairs_opts, .problem, quiet, ... ) eta_vs_cov_grid( xpdb, mapping = NULL, etavar = NULL, cols = NULL, covtypes = c("cont", "cat"), show_n = TRUE, drop_fixed = TRUE, title = "Eta covariate correlations | @run", subtitle = "Based on @nind individuals, Eta shrink: @etashk", caption = "@dir", tag = NULL, etacov = TRUE, pairs_opts, .problem, quiet, ... )eta_grid( xpdb, mapping = NULL, etavar = NULL, drop_fixed = TRUE, title = "Eta correlations | @run", subtitle = "Based on @nind individuals, Eta shrink: @etashk", caption = "@dir", tag = NULL, pairs_opts, .problem, quiet, ... ) cov_grid( xpdb, mapping = NULL, cols = NULL, covtypes = c("cont", "cat"), show_n = TRUE, drop_fixed = TRUE, title = "Covariate relationships | @run", subtitle = "Based on @nind individuals", caption = "@dir", tag = NULL, pairs_opts, .problem, quiet, ... ) eta_vs_cov_grid( xpdb, mapping = NULL, etavar = NULL, cols = NULL, covtypes = c("cont", "cat"), show_n = TRUE, drop_fixed = TRUE, title = "Eta covariate correlations | @run", subtitle = "Based on @nind individuals, Eta shrink: @etashk", caption = "@dir", tag = NULL, etacov = TRUE, pairs_opts, .problem, quiet, ... )
xpdb |
< |
mapping |
|
etavar |
|
drop_fixed |
As in |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
pairs_opts |
List of arguments to pass to |
.problem |
Problem number |
quiet |
Silence extra debugging output |
... |
Passed to |
cols |
|
covtypes |
Subset to specific covariate type? |
show_n |
Count the number of |
etacov |
For |
xp_tras_plot object
eta_grid(xpdb_x) cov_grid(xpdb_x) eta_vs_cov_grid(xpdb_x) # Labels and units are also supported xpdb_x %>% xpose::set_var_labels(AGE="Age", MED1 = "Digoxin") %>% xpose::set_var_units(AGE="yrs") %>% set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin()) %>% eta_vs_cov_grid()eta_grid(xpdb_x) cov_grid(xpdb_x) eta_vs_cov_grid(xpdb_x) # Labels and units are also supported xpdb_x %>% xpose::set_var_labels(AGE="Age", MED1 = "Digoxin") %>% xpose::set_var_units(AGE="yrs") %>% set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin()) %>% eta_vs_cov_grid()
Eta categorical covariate plots (typical)
eta_vs_catcov( xpdb, mapping = NULL, etavar = NULL, drop_fixed = TRUE, orientation = "x", show_n = check_xpdb_x(xpdb, .warn = FALSE), type = "bol", title = "Eta versus categorical covariates | @run", subtitle = "Based on @nind individuals, Eta shrink: @etashk", caption = "@dir", tag = NULL, facets, .problem, quiet, ... )eta_vs_catcov( xpdb, mapping = NULL, etavar = NULL, drop_fixed = TRUE, orientation = "x", show_n = check_xpdb_x(xpdb, .warn = FALSE), type = "bol", title = "Eta versus categorical covariates | @run", subtitle = "Based on @nind individuals, Eta shrink: @etashk", caption = "@dir", tag = NULL, facets, .problem, quiet, ... )
xpdb |
< |
mapping |
|
etavar |
|
drop_fixed |
As in |
orientation |
Passed to |
show_n |
Add "N=" to plot |
type |
Passed to |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
facets |
Additional facets |
.problem |
Problem number |
quiet |
Silence output |
... |
Any additional aesthetics. |
The ability to show number per covariate level is inspired
by the package pmplots, but is implements here within
the xpose ecosystem for consistency.
The desired plot
eta_vs_catcov(xpdb_x) # Labels and units are also supported xpdb_x %>% xpose::set_var_labels(AGE="Age", MED1 = "Digoxin") %>% xpose::set_var_units(AGE="yrs") %>% set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin()) %>% eta_vs_catcov()eta_vs_catcov(xpdb_x) # Labels and units are also supported xpdb_x %>% xpose::set_var_labels(AGE="Age", MED1 = "Digoxin") %>% xpose::set_var_units(AGE="yrs") %>% set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin()) %>% eta_vs_catcov()
Eta continuous covariate plots (typical)
eta_vs_contcov( xpdb, mapping = NULL, etavar = NULL, drop_fixed = TRUE, linsm = FALSE, type = "ps", title = "Eta versus continuous covariates | @run", subtitle = "Based on @nind individuals, Eta shrink: @etashk", caption = "@dir", tag = NULL, log = NULL, guide = TRUE, facets, .problem, quiet, ... )eta_vs_contcov( xpdb, mapping = NULL, etavar = NULL, drop_fixed = TRUE, linsm = FALSE, type = "ps", title = "Eta versus continuous covariates | @run", subtitle = "Based on @nind individuals, Eta shrink: @etashk", caption = "@dir", tag = NULL, log = NULL, guide = TRUE, facets, .problem, quiet, ... )
xpdb |
< |
mapping |
|
etavar |
|
drop_fixed |
As in |
linsm |
If |
type |
Passed to |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
log |
Log scale covariate value? |
guide |
Add guide line? |
facets |
Additional facets |
.problem |
Problem number |
quiet |
Silence output |
... |
Any additional aesthetics. |
The desired plot
eta_vs_contcov(xpdb_x) # Labels and units are also supported xpdb_x %>% xpose::set_var_labels(AGE="Age", MED1 = "Digoxin") %>% xpose::set_var_units(AGE="yrs") %>% set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin()) %>% eta_vs_contcov()eta_vs_contcov(xpdb_x) # Labels and units are also supported xpdb_x %>% xpose::set_var_labels(AGE="Age", MED1 = "Digoxin") %>% xpose::set_var_units(AGE="yrs") %>% set_var_levels(SEX=lvl_sex(), MED1 = lvl_bin()) %>% eta_vs_contcov()
Expose a model parameter of xpdb objects in an xpose_set
expose_param(xpdb_s, ..., .problem = NULL, .subprob = NULL, .method = NULL)expose_param(xpdb_s, ..., .problem = NULL, .subprob = NULL, .method = NULL)
xpdb_s |
< |
... |
< |
.problem |
< |
.subprob |
< |
.method |
< |
The parameter returned will be top-level, and to avoid conflicting
names will be prepended by .. (e.g., ..ome1). The selector
used to fetch the parameter will be used in this .. name. If
a better name is preferred, there are convenient renaming functions
from dplyr where needed.
When using parameter selectors, quotations should be used for more
complex names, like "OMEGA(1,1)", since these may be read incorrectly
otherwise.
The untransformed parameter is used for this exposure. The get_prm
call uses transform=FALSE.
An xpose_set object with the parameter exposed
pheno_set %>% expose_param(the1) %>% reshape_set() pheno_set %>% expose_param(RUVADD, "OMEGA(1,1)") %>% reshape_set() # This function is useful for generating a model-building table pheno_set %>% # Determine longest lineage select(all_of(xset_lineage(.))) %>% # Select key variability parameters expose_param(RUVADD, "OMEGA(1,1)") %>% # Make sure all models have descriptions focus_qapply(desc_from_comments) %>% # Extract description expose_property(descr) %>% # Transform to tibble reshape_set() # %>% pipe into other processingpheno_set %>% expose_param(the1) %>% reshape_set() pheno_set %>% expose_param(RUVADD, "OMEGA(1,1)") %>% reshape_set() # This function is useful for generating a model-building table pheno_set %>% # Determine longest lineage select(all_of(xset_lineage(.))) %>% # Select key variability parameters expose_param(RUVADD, "OMEGA(1,1)") %>% # Make sure all models have descriptions focus_qapply(desc_from_comments) %>% # Extract description expose_property(descr) %>% # Transform to tibble reshape_set() # %>% pipe into other processing
Expose a property of xpdb objects in an xpose_set
expose_property(xpdb_s, ..., .problem = NULL, .subprob = NULL, .method = NULL)expose_property(xpdb_s, ..., .problem = NULL, .subprob = NULL, .method = NULL)
xpdb_s |
< |
... |
< |
.problem |
< |
.subprob |
< |
.method |
< |
The property returned will be top-level, and to avoid conflicting
names will be prepended by .. (e.g., ..descr).
For some properties, transformations are applied automatically to make them more useful. This includes:
etashk and epsshk: transformed to numeric vectors as in <get_shk>
ofv and other per-problem properties: transformed as
needed and pulls from each xpdb default problem.
An xpose_set object with the properties exposed
xpdb_set <- expose_property(xpdb_set, descr) xpdb_set$mod1$..descr xpdb_set <- expose_property(xpdb_set, etashk) xpdb_set$mod1$..etashkxpdb_set <- expose_property(xpdb_set, descr) xpdb_set$mod1$..descr xpdb_set <- expose_property(xpdb_set, etashk) xpdb_set$mod1$..etashk
Since this is a common need, it is being functionalized to ensure consistency.
fill_prob_subprob_method( xpdb, .problem, .subprob, .method, envir = parent.frame() )fill_prob_subprob_method( xpdb, .problem, .subprob, .method, envir = parent.frame() )
xpdb |
< |
.problem |
|
.subprob |
|
.method |
|
envir |
< |
Filtration method for xpose_set
## S3 method for class 'xpose_set' filter(.data, ..., .rowwise = FALSE)## S3 method for class 'xpose_set' filter(.data, ..., .rowwise = FALSE)
.data |
< |
... |
< |
.rowwise |
< |
A filtered xpose_set
xpdb_set %>% filter(label=="mod1") xpdb_set %>% filter(length(parent)>1, .rowwise=TRUE)xpdb_set %>% filter(label=="mod1") xpdb_set %>% filter(length(parent)>1, .rowwise=TRUE)
For piping, set is passed, but with S3 method transformations are applied to the focused xpdb object.
focus_xpdb(xpdb_s, ..., .add = FALSE) unfocus_xpdb(xpdb_s) focused_xpdbs(xpdb_s) focus_function(xpdb_s, fn, ...) focus_qapply(xpdb_s, fn, ..., .mods = everything())focus_xpdb(xpdb_s, ..., .add = FALSE) unfocus_xpdb(xpdb_s) focused_xpdbs(xpdb_s) focus_function(xpdb_s, fn, ...) focus_qapply(xpdb_s, fn, ..., .mods = everything())
xpdb_s |
< |
... |
< |
.add |
< |
fn |
< |
.mods |
< |
While these functions are used internally, it is recognized that they may have value in user scripting. It is hoped these are self-explanatory, but the examples should address common uses.
Note: focus_qapply() (re)focuses as specified in .mods and then un-focuses all elements
of the set so should only be used in the case where a quick application
suffices. Otherwise, focusing with a sequence of focus_function calls
(or a monolithic single focus_function call with a custom function)
should be preferred.
An xpose_set object with the focused xpdb object(s)
# Select two xpdb objects to focus on xpdb_set %>% focus_xpdb(mod2,fix1) # Add a focus xpdb_set %>% focus_xpdb(mod2,fix1) %>% focus_xpdb(mod1, .add=TRUE) # Remove focus xpdb_set %>% focus_xpdb(mod2,fix1) %>% focus_xpdb() # Focus function and tidyselect pheno_set %>% focus_xpdb(everything()) %>% # Add iOFV col and iofv type to all xpdbs in set focus_function(backfill_iofv) %>% # Show 1... can do all like this, too, but no need unfocus_xpdb() %>% select(run6) %>% {.[[1]]$xpdb} %>% list_vars() # Quick-apply version of previous example pheno_set %>% focus_qapply(backfill_iofv) %>% select(run6) %>% {.[[1]]$xpdb} %>% list_vars()# Select two xpdb objects to focus on xpdb_set %>% focus_xpdb(mod2,fix1) # Add a focus xpdb_set %>% focus_xpdb(mod2,fix1) %>% focus_xpdb(mod1, .add=TRUE) # Remove focus xpdb_set %>% focus_xpdb(mod2,fix1) %>% focus_xpdb() # Focus function and tidyselect pheno_set %>% focus_xpdb(everything()) %>% # Add iOFV col and iofv type to all xpdbs in set focus_function(backfill_iofv) %>% # Show 1... can do all like this, too, but no need unfocus_xpdb() %>% select(run6) %>% {.[[1]]$xpdb} %>% list_vars() # Quick-apply version of previous example pheno_set %>% focus_qapply(backfill_iofv) %>% select(run6) %>% {.[[1]]$xpdb} %>% list_vars()
Get full index for xpose_data data
get_index(xpdb, .problem = NULL, ...) set_index(xpdb, index, ...)get_index(xpdb, .problem = NULL, ...) set_index(xpdb, index, ...)
xpdb |
< |
.problem |
< |
... |
Ignored. Here for future expansion |
index |
< |
Tibble of index
get_index(xpose::xpdb_ex_pk)get_index(xpose::xpdb_ex_pk)
Access model parameter estimates from an xpdb object.
Methods have been added to implement extensions. See Details.
get_prm( xpdb, .problem = NULL, .subprob = NULL, .method = NULL, digits = 4, transform = TRUE, show_all = FALSE, quiet )get_prm( xpdb, .problem = NULL, .subprob = NULL, .method = NULL, digits = 4, transform = TRUE, show_all = FALSE, quiet )
xpdb |
An |
.problem |
The problem to be used, by default returns the last one for each file. |
.subprob |
The subproblem to be used, by default returns the last one for each file. |
.method |
The estimation method to be used, by default returns the last one for each file |
digits |
The number of significant digits to be displayed. |
transform |
Should diagonal OMEGA and SIGMA elements be transformed to standard deviation and off diagonal elements be transformed to correlations. |
show_all |
Logical, whether the 0 fixed off-diagonal elements should be removed from the output. |
quiet |
Logical, if |
When using an <xp_xtra> object, this function will add a column to the output
where CV% for each diagonal element of omega is calculated. This CV% is with
respect to the resulting structural parameter, so unless the default log-normal
association is applicable update with add_prm_association.
For log-normal, users may prefer to use the first-order CV% ()
instead of the exact. In such case, xpdb <- set_option(xpdb, cvtype="sqrt") will
get that preferred form.
If a single omega parameter is associated with multiple fixed effect parameters,
the cv column will be a list. For the omega row associated with multiple
fixed effect parameters, there will be multiple CV values. This will be the case
even if the transformation is log-normal and therefore scale-invariant, given
the need for generality.
Note the approach used to calculate CV% assumes an untransformed scale for the
fitted parameter value (unrelated to transform=TRUE). That means, for example,
that for a logit-normal fitted parameter value, it is expected the value will be
something constrained between 0 and 1, not the unbounded, continuous transformed value.
The function <mutate_prm> is intended to help where that might be an issue.
A tibble for single problem/subprob or a named list for multiple problem|subprob.
Prybylski, J.P. Reporting Coefficient of Variation for Logit, Box-Cox and Other Non-log-normal Parameters. Clin Pharmacokinet 63, 133-135 (2024). https://doi.org/10.1007/s40262-023-01343-2
# xpose parameter table get_prm(xpose::xpdb_ex_pk, .problem = 1) # xpose.xtra parameter table (basically the same) get_prm(pheno_final, .problem = 1) # For the sake of example, even though these were all lognormal: pheno_final %>% add_prm_association(CLpkg~logit(IIVCL)) %>% add_prm_association(Vpkg~nmboxcox(IIVV, lambda = 0.01)) %>% get_prm(.problem = 1)# xpose parameter table get_prm(xpose::xpdb_ex_pk, .problem = 1) # xpose.xtra parameter table (basically the same) get_prm(pheno_final, .problem = 1) # For the sake of example, even though these were all lognormal: pheno_final %>% add_prm_association(CLpkg~logit(IIVCL)) %>% add_prm_association(Vpkg~nmboxcox(IIVV, lambda = 0.01)) %>% get_prm(.problem = 1)
Generic function to extract a property from a model summary
get_prop(xpdb, prop, .problem = NULL, .subprob = NULL, .method = NULL)get_prop(xpdb, prop, .problem = NULL, .subprob = NULL, .method = NULL)
xpdb |
< |
prop |
< |
.problem |
< |
.subprob |
< |
.method |
< |
Exact value for the property
data("xpdb_ex_pk", package = "xpose") get_prop(xpdb_ex_pk, "descr")data("xpdb_ex_pk", package = "xpose") get_prop(xpdb_ex_pk, "descr")
This function parses shrinkages as they are currently
presented in get_summary, so it
is dependent on the current implementation of that function.
get_shk(xpdb, wh = "eta", .problem = NULL, .subprob = NULL, .method = NULL)get_shk(xpdb, wh = "eta", .problem = NULL, .subprob = NULL, .method = NULL)
xpdb |
An |
wh |
The shrinkage to extract ( |
.problem |
Problem number to use. Uses the xpose default if not provided. |
.subprob |
< |
.method |
< |
A numeric vector of shrinkage estimates.
data("xpdb_ex_pk", package = "xpose") # eta Shrinkage get_shk(xpdb_ex_pk) # epsilon Shrinkage get_shk(xpdb_ex_pk, wh = "eps")data("xpdb_ex_pk", package = "xpose") # eta Shrinkage get_shk(xpdb_ex_pk) # epsilon Shrinkage get_shk(xpdb_ex_pk, wh = "eps")
xpose_plot
This function is very simple and unlikely to capture every possible situation. Paginated plots are not supported.
This is helpful for working with xpose plots in patchwork or
ggpubr functions.
grab_xpose_plot(plot)grab_xpose_plot(plot)
plot |
< |
Grob or list of grobs
single_plot <- xpdb_x %>% eta_vs_catcov(etavar = ETA1) %>% grab_xpose_plot() listof_plots <- xpdb_x %>% eta_vs_catcov(etavar = c(ETA1,ETA3)) %>% grab_xpose_plot()single_plot <- xpdb_x %>% eta_vs_catcov(etavar = ETA1) %>% grab_xpose_plot() listof_plots <- xpdb_x %>% eta_vs_catcov(etavar = c(ETA1,ETA3)) %>% grab_xpose_plot()
Another visualization of how individual objective functions change over the course of model development.
iofv_vs_mod( xpdb_s, ..., .lineage = FALSE, auto_backfill = FALSE, mapping = NULL, orientation = "x", type = "bjc", title = "Individual OFVs across models", subtitle = "Based on @nind individuals, Initial OFV: @ofv", caption = "Initial @dir", tag = NULL, axis.text = "@run", facets, .problem, quiet )iofv_vs_mod( xpdb_s, ..., .lineage = FALSE, auto_backfill = FALSE, mapping = NULL, orientation = "x", type = "bjc", title = "Individual OFVs across models", subtitle = "Based on @nind individuals, Initial OFV: @ofv", caption = "Initial @dir", tag = NULL, axis.text = "@run", facets, .problem, quiet )
xpdb_s |
< |
... |
< |
.lineage |
< |
auto_backfill |
< |
mapping |
|
orientation |
Defaults to |
type |
Passed to < |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
axis.text |
What to label the model. This is parsed on a per-model basis. |
facets |
Additional facets |
.problem |
Problem number |
quiet |
Silence output |
The desired plot
pheno_set %>% focus_qapply(backfill_iofv) %>% iofv_vs_mod() pheno_set %>% focus_qapply(backfill_iofv) %>% iofv_vs_mod(run3,run11,run14,run15) pheno_set %>% focus_qapply(backfill_iofv) %>% iofv_vs_mod(.lineage = TRUE)pheno_set %>% focus_qapply(backfill_iofv) %>% iofv_vs_mod() pheno_set %>% focus_qapply(backfill_iofv) %>% iofv_vs_mod(run3,run11,run14,run15) pheno_set %>% focus_qapply(backfill_iofv) %>% iofv_vs_mod(.lineage = TRUE)
For two models in an xpose_set, these functions are useful in comparing individual
and population predictions
ipred_vs_ipred( xpdb_s, ..., .inorder = FALSE, type = "pls", title = "Individual prediction comparison | @run", subtitle = "Ofv: @ofv, Eps shrink: @epsshk", caption = "@dir", tag = NULL, log = NULL, guide = TRUE, facets, .problem, quiet ) pred_vs_pred( xpdb_s, ..., .inorder = FALSE, type = "pls", title = "Population prediction comparison | @run", subtitle = "Ofv: @ofv, Eps shrink: @epsshk", caption = "@dir", tag = NULL, log = NULL, guide = TRUE, facets, .problem, quiet )ipred_vs_ipred( xpdb_s, ..., .inorder = FALSE, type = "pls", title = "Individual prediction comparison | @run", subtitle = "Ofv: @ofv, Eps shrink: @epsshk", caption = "@dir", tag = NULL, log = NULL, guide = TRUE, facets, .problem, quiet ) pred_vs_pred( xpdb_s, ..., .inorder = FALSE, type = "pls", title = "Population prediction comparison | @run", subtitle = "Ofv: @ofv, Eps shrink: @epsshk", caption = "@dir", tag = NULL, log = NULL, guide = TRUE, facets, .problem, quiet )
xpdb_s |
< |
... |
See < |
.inorder |
See < |
type |
Passed to |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
log |
Log scale covariate value? |
guide |
Add guide line? |
facets |
Additional facets |
.problem |
Problem number |
quiet |
Silence output |
The desired plot
pheno_set %>% ipred_vs_ipred(run5,run15) pheno_set %>% pred_vs_pred(run5,run15)pheno_set %>% ipred_vs_ipred(run5,run15) pheno_set %>% pred_vs_pred(run5,run15)
Add a column containing a simulation counter (irep). A new simulation is counted every time a value in x is different than its previous value and is a duplicate.
This version of the function does not require IDs be ascending, but does not work for
datasets where IDs are repeated (not in sequence). Both cases are read as separate
individuals for NONMEM, but NONMEM does not need to detect repetition of ID sequences (for NONMEM,
1,1,2,2,3,3,1,1,2,2,3,3 is 6 individuals, regardless of being 2 repeats of 3 individuals).
Given the vast majority of datasets use 1 individual per ID, (which cannot be said about IDs
always being ascending), only one of these corrections is implemented.
irep(x, quiet = FALSE)irep(x, quiet = FALSE)
x |
The column to be used for computing simulation number, usually the ID column. |
quiet |
Logical, if |
Bugfix for irep.
<numeric> vector tracking the number of simulations based on unique subject IDs.
data("xpdb_ex_pk", package = "xpose") xpdb_ex_pk_2 <- xpdb_ex_pk %>% mutate(sim_id = irep(ID), .problem = 2)data("xpdb_ex_pk", package = "xpose") xpdb_ex_pk_2 <- xpdb_ex_pk %>% mutate(sim_id = irep(ID), .problem = 2)
Convenience functions used in package
is_formula_list(x)is_formula_list(x)
x |
object to test |
<logical> TRUE if is a list of formulas
xp_xtras
Basic class checker for xp_xtras
is_xp_xtras(x)is_xp_xtras(x)
x |
Object to test |
<logical> TRUE if xp_xtras object
is_xp_xtras(xpose::xpdb_ex_pk) is_xp_xtras(xpdb_x)is_xp_xtras(xpose::xpdb_ex_pk) is_xp_xtras(xpdb_x)
A convenient quick check for how probabilities are currently
assigned, based on set_dv_probs.
list_dv_probs(xpdb, .problem = NULL, .dv_var = NULL)list_dv_probs(xpdb, .problem = NULL, .dv_var = NULL)
xpdb |
< |
.problem |
< |
.dv_var |
< |
<tibble> of probabilities
pkpd_m3 %>% set_dv_probs(1, 1~LIKE, .dv_var = BLQ) %>% list_dv_probs(.dv_var=BLQ)pkpd_m3 %>% set_dv_probs(1, 1~LIKE, .dv_var = BLQ) %>% list_dv_probs(.dv_var=BLQ)
list_vars
To accommodate changes made in xpose.xtras,
<list_vars> needed some minimal updates.
list_vars(xpdb, .problem = NULL, ...) ## Default S3 method: list_vars(xpdb, .problem = NULL, ...) ## S3 method for class 'xp_xtras' list_vars(xpdb, .problem = NULL, ...)list_vars(xpdb, .problem = NULL, ...) ## Default S3 method: list_vars(xpdb, .problem = NULL, ...) ## S3 method for class 'xp_xtras' list_vars(xpdb, .problem = NULL, ...)
xpdb |
< |
.problem |
< |
... |
Should be blank. |
<tibble> of variables
list_vars(xpose::xpdb_ex_pk) list_vars(xpdb_x)list_vars(xpose::xpdb_ex_pk) list_vars(xpdb_x)
This function is a helper for plotting functions where models in
an xpose_set can be averaged together. The implementation attempts
to match and extend from the cited prior work.
modavg_xpdb( xpdb_s, ..., .lineage = FALSE, avg_cols = NULL, avg_by_type = NULL, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet )modavg_xpdb( xpdb_s, ..., .lineage = FALSE, avg_cols = NULL, avg_by_type = NULL, algorithm = c("maa", "msa"), weight_type = c("individual", "population"), auto_backfill = FALSE, weight_basis = c("ofv", "aic", "res"), res_col = "RES", quiet )
xpdb_s |
< |
... |
< |
.lineage |
< |
avg_cols |
< |
avg_by_type |
< |
algorithm |
< |
weight_type |
< |
auto_backfill |
< |
weight_basis |
< |
res_col |
< |
quiet |
< |
Weight-averaged <xpose_data> object.
Uster, D.W., Stocker, S.L., Carland, J.E., Brett, J., Marriott, D.J.E., Day, R.O. and Wicha, S.G. (2021), A Model Averaging/Selection Approach Improves the Predictive Performance of Model-Informed Precision Dosing: Vancomycin as a Case Study. Clin. Pharmacol. Ther., 109: 175-183. https://doi.org/10.1002/cpt.2065
pheno_set %>% modavg_xpdb( avg_cols = IPRED, auto_backfill = TRUE, algorithm = "maa", weight_basis = "aic" )pheno_set %>% modavg_xpdb( avg_cols = IPRED, auto_backfill = TRUE, algorithm = "maa", weight_basis = "aic" )
mutate_x() adds new variables and preserves existing ones.
select() keeps only the listed variables; rename() keeps all variables.
Note: this function uses xpose.xtras::edit_xpose_data, but is otherwise
the same as <xpose::mutate>.
mutate_x(.data, ..., .problem, .source, .where) rename_x(.data, ..., .problem, .source, .where)mutate_x(.data, ..., .problem, .source, .where) rename_x(.data, ..., .problem, .source, .where)
.data |
An xpose database object. |
... |
Name-value pairs of expressions. Use |
.problem |
The problem from which the data will be modified |
.source |
The source of the data in the xpdb. Can either be 'data' or an output file extension e.g. 'phi'. |
.where |
A vector of element names to be edited in special (e.g.
|
An updated xpose data object
Apply transformations to fitted parameter values.
As fitted, sometimes parameter values are not as easy to communicate, but
to transform them outside of the xpose ecosystem limits some available
features. To have the best experience, this function can update the
parameter values that are used by xpose get_prm functions. At this
time these transformations are not applied to param vars (list_vars), but that can
already be done with the mutate method.
This only works for theta parameters.
All valid mutations are applied sequentially, so a double call to the2~the2^3
will result in effectively the2~the2^9, for example.
RSE values are calculated at runtime within get_prm, so they are not updated (or
updatable) with this function.
mutate_prm( xpdb, ..., .autose = TRUE, .problem = NULL, .subprob = NULL, .method = NULL, .sesim = 1e+05, quiet )mutate_prm( xpdb, ..., .autose = TRUE, .problem = NULL, .subprob = NULL, .method = NULL, .sesim = 1e+05, quiet )
xpdb |
< |
... |
... < |
.autose |
< |
.problem |
< |
.subprob |
< |
.method |
< |
.sesim |
< |
quiet |
Silence extra output. |
Covariance and correlation parameters are adjusted when standard error (SE)
values are changed directly or with .autose. When a transformation is applied
as a function for the fixed effect parameter (eg, ~plogis), the resulting SE may have
an unexpected scale; this is because it is now reporting the standard deviation
of a transformed and potentially non-normal distribution. If the parameter were fit
in the transformed scale (constrained to any appropriate bounds), it would likely have a
different SE given that most covariance estimation methods (excluding non-parametric and
resampling-based) will treat the constrained parameter as continuous and unconstrained.
The updates to variance-covariance values (and the correlation values, though that is mostly
invariant) are applied to the entire matrices. When piped directly into
get_prm, only the SE estimate is shown, but <get_file> can be used
to see the complete updated variance-covariance values. This could be useful if those
matrices are being used to define priors for a Bayesian model fitting, as the re-scaling
of off-diagonal elements is handled automatically.
A function to transform parameters will result in a more accurate autose result. If a call
(the1~exp(the)) or a value (the1~2) are used, the standard error will be simply scaled.
An updated xp_xtras object with mutated parameters
vismo_pomod %>% # Function mutate_prm(THETA11~exp) %>% # Value (se will not be scaled); plogis = inverse logit mutate_prm(THETA12~plogis(THETA12)) %>% get_prm()vismo_pomod %>% # Function mutate_prm(THETA11~exp) %>% # Value (se will not be scaled); plogis = inverse logit mutate_prm(THETA12~plogis(THETA12)) %>% get_prm()
Mutation method for xpose_set
## S3 method for class 'xpose_set' mutate(.data, ..., .force = FALSE, .retest = !.force, .rowwise = FALSE)## S3 method for class 'xpose_set' mutate(.data, ..., .force = FALSE, .retest = !.force, .rowwise = FALSE)
.data |
< |
... |
< |
.force |
< |
.retest |
< |
.rowwise |
< |
A set with updated top-level data (unless focused)
xpdb_set %>% # Adds foo = bar for all objects in the set mutate(foo = "bar") %>% # Reshape to visualize reshape_set()xpdb_set %>% # Adds foo = bar for all objects in the set mutate(foo = "bar") %>% # Reshape to visualize reshape_set()
xp_xtras example of a base modelBase model for phenobarbital in neonates.
pheno_basepheno_base
xp_xtrasAn xp_xtras object.
This is run6 in <pheno_set>
https://doi.org/10.1159/000457062 and nlmixr2data::pheno_sd
xp_xtras example of a final modelFinal model for phenobarbital in neonates.
pheno_finalpheno_final
xp_xtrasAn xp_xtras object.
This is re-parameterized from the covariate-building work, which in this case did not identify a relationship with Apgar score.
This is run16 in <pheno_set>
https://doi.org/10.1159/000457062 and nlmixr2data::pheno_sd
xp_xtras example of a final modelFinal model for phenobarbital in neonates.
pheno_saempheno_saem
xp_xtrasAn xp_xtras object.
This is the same as pheno_final but fitted with SAEM/IMP.
Not a part of <pheno_set>
https://doi.org/10.1159/000457062 and nlmixr2data::pheno_sd
xpose_set objectModel-building set for the phenobarbital in neonates PK data used across multiple packages.
pheno_setpheno_set
xpose_setAn xpose_set object of length 14 with a branched lineage.
This is not a demonstration of high-quality model-building, it is just a typical and simple example.
https://doi.org/10.1159/000457062 and nlmixr2data::pheno_sd
xp_xtras example of an M3 modelA representative PK/PD model with M3 fitting applied.
pkpd_m3pkpd_m3
xp_xtrasAn xp_xtras object.
https://doi.org/10.1002/psp4.13219
Beal, S.L. Ways to Fit a PK Model with Some Data Below the Quantification Limit. J Pharmacokinet Pharmacodyn 28, 481-504 (2001). https://doi.org/10.1023/A:1012299115260
Prybylski JP. Indirect modeling of derived outcomes: Are minor prediction discrepancies a cause for concern? CPT Pharmacometrics Syst Pharmacol. 2024; 00: 1-9. doi:10.1002/psp4.13219
xp_xtras example of an M3 model (dataset)The dataset used to fit the pkpd_m3 model.
pkpd_m3_dfpkpd_m3_df
xp_xtrasAn xp_xtras object.
https://doi.org/10.1002/psp4.13219
Prybylski JP. Indirect modeling of derived outcomes: Are minor prediction discrepancies a cause for concern? CPT Pharmacometrics Syst Pharmacol. 2024; 00: 1-9. doi:10.1002/psp4.13219
Differences are second listed model minus first listed. Eg, in
eta_waterfall(run1,run2), the when etas in run2 are greater than
those in run1, the difference will be positive.
prm_waterfall( xpdb_s, ..., .inorder = FALSE, type = "bh", max_nind = 0.7, scale_diff = TRUE, show_n = TRUE, title = "Parameter changes between models | @run", subtitle = "Based on @nobs observations in @nind individuals", caption = "@dir", tag = NULL, facets = NULL, facet_scales = "free_x", .problem, .subprob, .method, quiet ) eta_waterfall( xpdb_s, ..., .inorder = FALSE, type = "bh", max_nind = 0.7, scale_diff = TRUE, show_n = TRUE, title = "Eta changes between models | @run", subtitle = "Based on @nobs observations in @nind individuals", caption = "@dir", tag = NULL, facets = NULL, facet_scales = "free_x", .problem, .subprob, .method, quiet ) iofv_waterfall( xpdb_s, ..., .inorder = FALSE, type = "bh", max_nind = 0.7, scale_diff = FALSE, show_n = TRUE, title = "iOFV changes between models | @run", subtitle = "Based on @nobs observations in @nind individuals", caption = "@dir", tag = NULL, facets = NULL, facet_scales = "free_x", .problem, .subprob, .method, quiet )prm_waterfall( xpdb_s, ..., .inorder = FALSE, type = "bh", max_nind = 0.7, scale_diff = TRUE, show_n = TRUE, title = "Parameter changes between models | @run", subtitle = "Based on @nobs observations in @nind individuals", caption = "@dir", tag = NULL, facets = NULL, facet_scales = "free_x", .problem, .subprob, .method, quiet ) eta_waterfall( xpdb_s, ..., .inorder = FALSE, type = "bh", max_nind = 0.7, scale_diff = TRUE, show_n = TRUE, title = "Eta changes between models | @run", subtitle = "Based on @nobs observations in @nind individuals", caption = "@dir", tag = NULL, facets = NULL, facet_scales = "free_x", .problem, .subprob, .method, quiet ) iofv_waterfall( xpdb_s, ..., .inorder = FALSE, type = "bh", max_nind = 0.7, scale_diff = FALSE, show_n = TRUE, title = "iOFV changes between models | @run", subtitle = "Based on @nobs observations in @nind individuals", caption = "@dir", tag = NULL, facets = NULL, facet_scales = "free_x", .problem, .subprob, .method, quiet )
xpdb_s |
< |
... |
See < |
.inorder |
See < |
type |
See Details. |
max_nind |
If less than 1, the percentile of absolute change values above which to plot. If above 1, the absolute number of subjects is included. To show all, use an extreme positive number like 9999. |
scale_diff |
< |
show_n |
< |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
facets |
< |
facet_scales |
< |
.problem |
The problem to be used, by default returns the last one. |
.subprob |
The subproblem to be used, by default returns the last one. |
.method |
The estimation method to be used, by default returns the last one. |
quiet |
Silence extra debugging output |
For type-based customization of plots:
b bar plot (from geom_bar)
h hline at 0 (from geom_hline)
t text of change value (from geom_text)
<xpose_plot> object
# Parameter value changes pheno_set %>% # Ensure param is set focus_qapply(set_var_types, param=c(CL,V)) %>% prm_waterfall(run5,run6) # EBE value changes pheno_set %>% eta_waterfall(run5,run6) # iOFV changes pheno_set %>% focus_qapply(backfill_iofv) %>% # Note the default scaling is flipped here iofv_waterfall(run5,run6)# Parameter value changes pheno_set %>% # Ensure param is set focus_qapply(set_var_types, param=c(CL,V)) %>% prm_waterfall(run5,run6) # EBE value changes pheno_set %>% eta_waterfall(run5,run6) # iOFV changes pheno_set %>% focus_qapply(backfill_iofv) %>% # Note the default scaling is flipped here iofv_waterfall(run5,run6)
Consumes formula list and converts into corresponding tibble.
proc_levels(lvl_list)proc_levels(lvl_list)
lvl_list |
< |
<tibble> of levels
Pulling method for xpose_set
## S3 method for class 'xpose_set' pull(.data, ...)## S3 method for class 'xpose_set' pull(.data, ...)
.data |
< |
... |
< |
The top-level information for a set requested.
xpdb_set %>% pull(xpdb)xpdb_set %>% pull(xpdb)
Renaming method for xpose_set
## S3 method for class 'xpose_set' rename(.data, ...)## S3 method for class 'xpose_set' rename(.data, ...)
.data |
< |
... |
< |
Re-labeled set
xpdb_set %>% rename(Mod = mod1)xpdb_set %>% rename(Mod = mod1)
An opinionated function where for optimization routines that report number of significant digits (eg, FO-based), only those number of digits are considered reportable.
reportable_digits(xpdb, .default = 3, .problem, .subprob, .method)reportable_digits(xpdb, .default = 3, .problem, .subprob, .method)
xpdb |
< |
.default |
< |
.problem |
< |
.subprob |
< |
.method |
< |
Number of reportable digits
reportable_digits(xpdb_x)reportable_digits(xpdb_x)
This amounts to a convenience function for tidy manipulations.
reshape_set(x) unreshape_set(y)reshape_set(x) unreshape_set(y)
x |
< |
y |
< |
<tibble> Nested list, or <xpose_set>
rset <- reshape_set(xpdb_set) # Properties (exposed and top-level) can be seen. xpdb objects are nested in the xpdb column. rset %>% dplyr::select(-xpdb) %>% dplyr::glimpse() unreshape_set(rset) # The reversibility of reshaping can be confirmed: identical(xpdb_set,reshape_set(xpdb_set) %>% unreshape_set())rset <- reshape_set(xpdb_set) # Properties (exposed and top-level) can be seen. xpdb objects are nested in the xpdb column. rset %>% dplyr::select(-xpdb) %>% dplyr::glimpse() unreshape_set(rset) # The reversibility of reshaping can be confirmed: identical(xpdb_set,reshape_set(xpdb_set) %>% unreshape_set())
Selection method for xpose_set
## S3 method for class 'xpose_set' select(.data, ...)## S3 method for class 'xpose_set' select(.data, ...)
.data |
< |
... |
< |
Subset of xpose set
xpdb_set %>% select(starts_with("fix")) xpdb_set %>% select(mod1, fix1)xpdb_set %>% select(starts_with("fix")) xpdb_set %>% select(mod1, fix1)
xpose_set
Base model for xpose_set
set_base_model(xpdb_s, ...) get_base_model(xpdb_s) unset_base_model(xpdb_s)set_base_model(xpdb_s, ...) get_base_model(xpdb_s) unset_base_model(xpdb_s)
xpdb_s |
< |
... |
<< |
<xpose_set> object with a base model
w_base <- xpdb_set %>% set_base_model(mod2) w_base # base model listed in output get_base_model(w_base) # base model name unset_base_model(w_base) # base model no longer in outputw_base <- xpdb_set %>% set_base_model(mod2) w_base # base model listed in output get_base_model(w_base) # base model name unset_base_model(w_base) # base model no longer in output
For categorical DVs or similar endpoints (such as censoring
flag columns, like BLQ), this function allows probability
columns to be defined for each level.
set_dv_probs( xpdb, .problem = NULL, ..., .dv_var = NULL, .handle_missing = c("quiet", "warn", "error") )set_dv_probs( xpdb, .problem = NULL, ..., .dv_var = NULL, .handle_missing = c("quiet", "warn", "error") )
xpdb |
< |
.problem |
< |
... |
Formulas where LHS are levels or pseudo-functions (see Details), and RHS are columns with probabilities of those levels. |
.dv_var |
< |
.handle_missing |
< |
The same probability cannot be assigned to multiple values. Pseudo-functions can be used, or
new columns can be created to overcome this limitation. The available pseudo-functions should
be written like ge(value) (for >=), gt(value) (for >), etc. These comparison names
are those used in Perl, Fortran and many other languages. The function eq() should not be used,
but it will be ignored either way; equivalence is implied with the base syntax.
<xp_xtras> object with updated probabilities
pkpd_m3 %>% # Not necessary, but correct to set var type before using this set_var_types(.problem=1, catdv=BLQ, dvprobs=LIKE) %>% # Set var type. Warnings can be helpful unless an inverse likelihood column is available set_dv_probs(.problem=1, 1~LIKE, .dv_var = BLQ, .handle_missing = "warn") %>% list_vars() # Same as above with demo of inverse column pkpd_m3 %>% xpose::mutate(INVLIKE = 1-LIKE) %>% set_var_types(.problem=1, catdv=BLQ, dvprobs=c(LIKE,INVLIKE)) %>% # Note no warning set_dv_probs(.problem=1, 1~LIKE, 0~INVLIKE, .dv_var = BLQ, .handle_missing = "warn")%>% list_vars() # With categorical model vismo_pomod %>% # Update var types set_var_types(.problem=1, catdv=DV, dvprobs=matches("^P\\d+$")) %>% # Warning (as noted), does not recognize 3 is covered implicitly. That's ok! set_dv_probs(.problem=1, 0~P0,1~P1,ge(2)~P23, .handle_missing = "warn")%>% list_vars() # Same as above, but... vismo_pomod %>% set_var_types(.problem=1, catdv=DV, dvprobs=matches("^P\\d+$")) %>% # Default is to not bother users with a warning set_dv_probs(.problem=1, 0~P0,1~P1,ge(2)~P23)%>% list_vars()pkpd_m3 %>% # Not necessary, but correct to set var type before using this set_var_types(.problem=1, catdv=BLQ, dvprobs=LIKE) %>% # Set var type. Warnings can be helpful unless an inverse likelihood column is available set_dv_probs(.problem=1, 1~LIKE, .dv_var = BLQ, .handle_missing = "warn") %>% list_vars() # Same as above with demo of inverse column pkpd_m3 %>% xpose::mutate(INVLIKE = 1-LIKE) %>% set_var_types(.problem=1, catdv=BLQ, dvprobs=c(LIKE,INVLIKE)) %>% # Note no warning set_dv_probs(.problem=1, 1~LIKE, 0~INVLIKE, .dv_var = BLQ, .handle_missing = "warn")%>% list_vars() # With categorical model vismo_pomod %>% # Update var types set_var_types(.problem=1, catdv=DV, dvprobs=matches("^P\\d+$")) %>% # Warning (as noted), does not recognize 3 is covered implicitly. That's ok! set_dv_probs(.problem=1, 0~P0,1~P1,ge(2)~P23, .handle_missing = "warn")%>% list_vars() # Same as above, but... vismo_pomod %>% set_var_types(.problem=1, catdv=DV, dvprobs=matches("^P\\d+$")) %>% # Default is to not bother users with a warning set_dv_probs(.problem=1, 0~P0,1~P1,ge(2)~P23)%>% list_vars()
xpose optionSet an xpose option
set_option(xpdb, ...)set_option(xpdb, ...)
xpdb |
< |
... |
< |
xp_xtras object
xpdb_x <- set_option(xpdb_x, quiet = TRUE)xpdb_x <- set_option(xpdb_x, quiet = TRUE)
Set a summary property
set_prop(xpdb, ..., .problem = NULL, .subprob = NULL)set_prop(xpdb, ..., .problem = NULL, .subprob = NULL)
xpdb |
< |
... |
< |
.problem |
< |
.subprob |
< |
Although one might be tempted to set custom properties using this function,
with the intention to maintain cross-functionality with xpose, users cannot
set a non-existent property with this function. When used internally, workarounds
to this semi-limitation are used.
xp_xtras object
set_prop(xpose::xpdb_ex_pk, descr = "New model description") %>% xpose::get_summary()set_prop(xpose::xpdb_ex_pk, descr = "New model description") %>% xpose::get_summary()
For variable types such as catcov, it can be convenient to define
levels. This function provides a straightforward means to do so,
consistent with tidy functions like <case_when>.
Several convenience functions are provided for common levels in <levelers>.
set_var_levels( xpdb, .problem = NULL, ..., .missing = "Other", .handle_missing = c("quiet", "warn", "error") )set_var_levels( xpdb, .problem = NULL, ..., .missing = "Other", .handle_missing = c("quiet", "warn", "error") )
xpdb |
< |
.problem |
< |
... |
< |
.missing |
< |
.handle_missing |
< |
<xp_xtras> object with updated levels
set_var_levels(xpdb_x, SEX = lvl_sex(), MED1 = lvl_bin(), MED2 = c( 0 ~ "n", 1 ~ "y" ) )set_var_levels(xpdb_x, SEX = lvl_sex(), MED1 = lvl_bin(), MED2 = c( 0 ~ "n", 1 ~ "y" ) )
<set_var_types> wrapper that accepts tidyselect syntax.
Character vector-based selection still works.
set_var_types_x accepts xpose_data or xp_xtras objects.
set_var_types without _x is defined with S3 methods. To maintain xpose expectations,
the default method is <set_var_types>, but if an xp_xtras object
is used, the method uses set_var_types_x.
set_var_types(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)set_var_types(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)
xpdb |
An |
.problem |
The problem number to which the edits will be applied. |
... |
< |
auto_factor |
If |
quiet |
Logical, if |
An xpose_data object
data("xpdb_ex_pk", package = "xpose") # Change variable type xpdb_2 <- set_var_types_x( xpdb_ex_pk, .problem = 1, idv = TAD, catcov = starts_with("MED"), contcov = c(CLCR,AGE) )data("xpdb_ex_pk", package = "xpose") # Change variable type xpdb_2 <- set_var_types_x( xpdb_ex_pk, .problem = 1, idv = TAD, catcov = starts_with("MED"), contcov = c(CLCR,AGE) )
<set_var_types> wrapper that accepts tidyselect syntax.
Character vector-based selection still works.
set_var_types_x accepts xpose_data or xp_xtras objects.
set_var_types without _x is defined with S3 methods. To maintain xpose expectations,
the default method is <set_var_types>, but if an xp_xtras object
is used, the method uses set_var_types_x.
set_var_types_x(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)set_var_types_x(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)
xpdb |
An |
.problem |
The problem number to which the edits will be applied. |
... |
< |
auto_factor |
If |
quiet |
Logical, if |
An xpose_data object
data("xpdb_ex_pk", package = "xpose") # Change variable type xpdb_2 <- set_var_types_x( xpdb_ex_pk, .problem = 1, idv = TAD, catcov = starts_with("MED"), contcov = c(CLCR,AGE) )data("xpdb_ex_pk", package = "xpose") # Change variable type xpdb_2 <- set_var_types_x( xpdb_ex_pk, .problem = 1, idv = TAD, catcov = starts_with("MED"), contcov = c(CLCR,AGE) )
<set_var_types> wrapper that accepts tidyselect syntax.
Character vector-based selection still works.
set_var_types_x accepts xpose_data or xp_xtras objects.
set_var_types without _x is defined with S3 methods. To maintain xpose expectations,
the default method is <set_var_types>, but if an xp_xtras object
is used, the method uses set_var_types_x.
## Default S3 method: set_var_types(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)## Default S3 method: set_var_types(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)
xpdb |
An |
.problem |
The problem number to which the edits will be applied. |
... |
< |
auto_factor |
If |
quiet |
Logical, if |
An xpose_data object
data("xpdb_ex_pk", package = "xpose") # Change variable type xpdb_2 <- set_var_types_x( xpdb_ex_pk, .problem = 1, idv = TAD, catcov = starts_with("MED"), contcov = c(CLCR,AGE) )data("xpdb_ex_pk", package = "xpose") # Change variable type xpdb_2 <- set_var_types_x( xpdb_ex_pk, .problem = 1, idv = TAD, catcov = starts_with("MED"), contcov = c(CLCR,AGE) )
<set_var_types> wrapper that accepts tidyselect syntax.
Character vector-based selection still works.
set_var_types_x accepts xpose_data or xp_xtras objects.
set_var_types without _x is defined with S3 methods. To maintain xpose expectations,
the default method is <set_var_types>, but if an xp_xtras object
is used, the method uses set_var_types_x.
## S3 method for class 'xp_xtras' set_var_types(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)## S3 method for class 'xp_xtras' set_var_types(xpdb, .problem = NULL, ..., auto_factor = TRUE, quiet)
xpdb |
An |
.problem |
The problem number to which the edits will be applied. |
... |
< |
auto_factor |
If |
quiet |
Logical, if |
An xpose_data object
data("xpdb_ex_pk", package = "xpose") # Change variable type xpdb_2 <- set_var_types_x( xpdb_ex_pk, .problem = 1, idv = TAD, catcov = starts_with("MED"), contcov = c(CLCR,AGE) )data("xpdb_ex_pk", package = "xpose") # Change variable type xpdb_2 <- set_var_types_x( xpdb_ex_pk, .problem = 1, idv = TAD, catcov = starts_with("MED"), contcov = c(CLCR,AGE) )
This changes the point and text color
in the xp_theme of an xpose_data object.
shark_colors( xpdb, upcolor = xp_xtra_theme(base_on = xpdb$xp_theme)$sharkup_color, dncolor = xp_xtra_theme(base_on = xpdb$xp_theme)$sharkdn_color )shark_colors( xpdb, upcolor = xp_xtra_theme(base_on = xpdb$xp_theme)$sharkup_color, dncolor = xp_xtra_theme(base_on = xpdb$xp_theme)$sharkdn_color )
xpdb |
< |
upcolor |
Color for increasing dOFV |
dncolor |
Color for decreasing dOFV |
<xpose_data> object
# Where this would fit in a particular workflow xpose_set(pheno_base, pheno_final) %>% # forward functions affecting xpdb objects focus_xpdb(everything()) %>% # Add iOFVs focus_function(backfill_iofv) %>% # Change color of all xpdb xp_themes (though only the first one needs to change) focus_function( function(x) shark_colors( x, upcolor = "purple", dncolor = "green" )) %>% # See new plot shark_plot()# Where this would fit in a particular workflow xpose_set(pheno_base, pheno_final) %>% # forward functions affecting xpdb objects focus_xpdb(everything()) %>% # Add iOFVs focus_function(backfill_iofv) %>% # Change color of all xpdb xp_themes (though only the first one needs to change) focus_function( function(x) shark_colors( x, upcolor = "purple", dncolor = "green" )) %>% # See new plot shark_plot()
This is intended to match the overall behavior of
dOFV.vs.id() in xpose4, within the framework
of the xpose_set object.
dofv_vs_id is an alias of the function shark_plot,
for recognition.
shark_plot( xpdb_s, ..., .inorder = FALSE, type = "plt", alpha = 0.05, df = "guess", text_cutoff = 0.8, title = "Individual contributions to dOFV | @run", subtitle = "Based on @nind individuals, OFVs: @ofv", caption = "@dir", tag = NULL, ylab = "dOFV", xlab = "Number of individuals removed", opt, facets = NULL, .problem, .subprob, .method, quiet ) dofv_vs_id( xpdb_s, ..., .inorder = FALSE, type = "plt", alpha = 0.05, df = "guess", text_cutoff = 0.8, title = "Individual contributions to dOFV | @run", subtitle = "Based on @nind individuals, OFVs: @ofv", caption = "@dir", tag = NULL, ylab = "dOFV", xlab = "Number of individuals removed", opt, facets = NULL, .problem, .subprob, .method, quiet )shark_plot( xpdb_s, ..., .inorder = FALSE, type = "plt", alpha = 0.05, df = "guess", text_cutoff = 0.8, title = "Individual contributions to dOFV | @run", subtitle = "Based on @nind individuals, OFVs: @ofv", caption = "@dir", tag = NULL, ylab = "dOFV", xlab = "Number of individuals removed", opt, facets = NULL, .problem, .subprob, .method, quiet ) dofv_vs_id( xpdb_s, ..., .inorder = FALSE, type = "plt", alpha = 0.05, df = "guess", text_cutoff = 0.8, title = "Individual contributions to dOFV | @run", subtitle = "Based on @nind individuals, OFVs: @ofv", caption = "@dir", tag = NULL, ylab = "dOFV", xlab = "Number of individuals removed", opt, facets = NULL, .problem, .subprob, .method, quiet )
xpdb_s |
< |
... |
See < |
.inorder |
See < |
type |
See Details. |
alpha |
alpha for LRT |
df |
degrees of freedom for LRT. If |
text_cutoff |
If less than 1, the percentile of absolute individual dOFV values above which to show labels of IDs. If above 1, the absolute number of IDs to show. To show all, use an extreme positive number like 9999. |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
ylab |
y-axis label |
xlab |
x-axis label |
opt |
User-specified data options. Only some of these will be used. |
facets |
< |
.problem |
The problem to be used, by default returns the last one. |
.subprob |
The subproblem to be used, by default returns the last one. |
.method |
The estimation method to be used, by default returns the last one. |
quiet |
Silence extra debugging output |
For type-based customization of plots:
p points (using aesthetics for sharkup and sharkdn)
l lines for dOFV (both total dOFV and significance are plotted)
t text (using aesthetics for shkuptxt and shkdntxt)
In xpose4, users can control sig.drop, but this function uses
alpha and df to determine the critical delta by the likelihood
ratio test. It is acknowledged there are situations where this may
not be valid, but it is suggested that df or alpha be adjusted
to meet the desired sig.drop.
my_alpha <- 0.05 my_df <- 1.34 # fractional, perhaps to account for different IIVs my_sigdrop <- -stats::qchisq(1-my_alpha, my_df) my_sigdrop #> [1] -4.633671 # Then use alpha=my_alpha, df=my_df in `shark_plot` call.
<xpose_plot> object
pheno_set %>% # Make sure set has iofv var types defined focus_xpdb(everything()) %>% focus_function(backfill_iofv) %>% # Pick two models or consistent with two_set_dots() shark_plot(run6,run11) pheno_set %>% # As before focus_xpdb(everything()) %>% focus_function(backfill_iofv) %>% # Add indicator (or use established covariate) mutate(APGRtest = as.numeric(as.character(APGR))<5) %>% # Pick two models or consistent with two_set_dots() shark_plot(run6,run11, facets = "APGRtest")pheno_set %>% # Make sure set has iofv var types defined focus_xpdb(everything()) %>% focus_function(backfill_iofv) %>% # Pick two models or consistent with two_set_dots() shark_plot(run6,run11) pheno_set %>% # As before focus_xpdb(everything()) %>% focus_function(backfill_iofv) %>% # Add indicator (or use established covariate) mutate(APGRtest = as.numeric(as.character(APGR))<5) %>% # Pick two models or consistent with two_set_dots() shark_plot(run6,run11, facets = "APGRtest")
group_by_x() takes an existing table and converts it into a
grouped table where operations are performed "by group". ungroup() removes grouping.
summarize() reduces multiple values down to a single value.
Note: this function uses xpose.xtras::edit_xpose_data, but is otherwise
the same as <xpose::group_by>.
group_by_x(.data, ..., .problem, .source, .where) ungroup_x(.data, ..., .problem, .source, .where)group_by_x(.data, ..., .problem, .source, .where) ungroup_x(.data, ..., .problem, .source, .where)
.data |
An xpose database object. |
... |
Name-value pairs of expressions. Use |
.problem |
The problem from which the data will be modified |
.source |
The source of the data in the xpdb. Can either be 'data' or an output file extension e.g. 'phi'. |
.where |
A vector of element names to be edited in special (e.g.
|
Group data in an xpose data object
This is intended to be used as a convenience function in plotting where levels are set for some variable.
val2lvl(vals, lvl_tbl = NULL)val2lvl(vals, lvl_tbl = NULL)
vals |
vector of values associated with levels in |
lvl_tbl |
tibble of levels |
A vector of levels corresponding to the input vector.
xp_xtras example of the discrete-time Markov model of categorical vismodegib dataThe referenced work presents two alternative modeling approaches for muscle spasm response to vismodegib. This is a fit of the provided discrete-time Markov model to the 50 participant mock data.
vismo_dtmmvismo_dtmm
xp_xtrasAn xp_xtras object.
Derived from sup-0009 and sup-0010 from the reference.
Lu, T., Yang, Y., Jin, J.Y. and Kågedal, M. (2020), Analysis of Longitudinal-Ordered Categorical Data for Muscle Spasm Adverse Event of Vismodegib: Comparison Between Different Pharmacometric Models. CPT Pharmacometrics Syst. Pharmacol., 9: 96-105. https://doi.org/10.1002/psp4.12487
xp_xtras example of the proportional odds categorical vismodegib modelThe referenced work presents two alternative modeling approaches for muscle spasm response to vismodegib. This is a fit of the provided proportional odds model to the 50 participant mock data.
vismo_pomodvismo_pomod
xp_xtrasAn xp_xtras object.
Derived from sup-0009 and sup-0010 from the reference.
Lu, T., Yang, Y., Jin, J.Y. and Kågedal, M. (2020), Analysis of Longitudinal-Ordered Categorical Data for Muscle Spasm Adverse Event of Vismodegib: Comparison Between Different Pharmacometric Models. CPT Pharmacometrics Syst. Pharmacol., 9: 96-105. https://doi.org/10.1002/psp4.12487
The referenced work presents two alternative modeling approaches for muscle spasm response to vismodegib. There is a mock dataset for one person, and using the provided model a 50 participant mock dataset could be generated.
vismodegibvismodegib
tibbleAn tibble.
Generated using sup-0009 and sup-0010 from the reference.
Lu, T., Yang, Y., Jin, J.Y. and Kågedal, M. (2020), Analysis of Longitudinal-Ordered Categorical Data for Muscle Spasm Adverse Event of Vismodegib: Comparison Between Different Pharmacometric Models. CPT Pharmacometrics Syst. Pharmacol., 9: 96-105. https://doi.org/10.1002/psp4.12487
GGally functionsEnsure consistent style with GGally functions
wrap_xp_ggally(fn, xp_theme, ...)wrap_xp_ggally(fn, xp_theme, ...)
fn |
< |
xp_theme |
theme to use |
... |
< |
ggplot2 function
xp_var MethodTo add a small amount of functionality to <xp_var>,
this method was created.
xp_var(xpdb, .problem, col = NULL, type = NULL, silent = FALSE) ## Default S3 method: xp_var(xpdb, .problem, col = NULL, type = NULL, silent = FALSE) ## S3 method for class 'xp_xtras' xp_var(xpdb, .problem, col = NULL, type = NULL, silent = FALSE)xp_var(xpdb, .problem, col = NULL, type = NULL, silent = FALSE) ## Default S3 method: xp_var(xpdb, .problem, col = NULL, type = NULL, silent = FALSE) ## S3 method for class 'xp_xtras' xp_var(xpdb, .problem, col = NULL, type = NULL, silent = FALSE)
xpdb |
An xpose database object. |
.problem |
The $problem number to be used. |
col |
The column name to be searched in the index. Alternative to arg 'type'. |
type |
The type of column to searched in the index. Alternative to 'col'. |
silent |
Should the function be silent or return errors. |
A tibble of identified variables.
Adds aesthetics for plot components used in this package.
xp_xtra_theme(base_on = NULL)xp_xtra_theme(base_on = NULL)
base_on |
|
This package attempts to generate a consistent
theme even if users are working with a highly
customized xp_theme. There is are only a few
hard-coded aesthetics, and the rest are derived from
existing aesthetics in base_on, which defaults to
the default from xpose.
Only a few options are worth noting. In <xplot_pairs>
(and functions using it), the aesthetics for GGally-specific
elements like barDiag are defined as gga(element)_(aesthetic).
The labeller for pairs plots is also changed from the de facto default
label_both to label_value, but any labeller can be provided as
pairs_labeller.
An xpose theme object
Updated version of the xpose4 theme
xp4_xtra_theme()xp4_xtra_theme()
An xpose theme object with xpose4 color palette
xpose_set objectA set of identical xpdb objects to demo various features of xpose.xtras.
xpdb_setxpdb_set
xpose_setAn xpose_set object of length 4 with a single lineage.
Assembled from the xpdb_ex_pk object in the xpose package.
xp_xtras objectThe <xpdb_ex_pk> object converted to xp_xtras. For examples.
xpdb_xxpdb_x
xp_xtrasAn xp_xtras object with no extra data filled.
Assembled from the xpdb_ex_pk object in the xpose package.
Manually generate boxplots from an xpdb object.
xplot_boxplot( xpdb, mapping = NULL, type = "bo", xscale = "discrete", yscale = "continuous", orientation = "x", group = "ID", title = NULL, subtitle = NULL, caption = NULL, tag = NULL, plot_name = "boxplot", gg_theme, xp_theme, opt, quiet, jitter_seed, ... )xplot_boxplot( xpdb, mapping = NULL, type = "bo", xscale = "discrete", yscale = "continuous", orientation = "x", group = "ID", title = NULL, subtitle = NULL, caption = NULL, tag = NULL, plot_name = "boxplot", gg_theme, xp_theme, opt, quiet, jitter_seed, ... )
xpdb |
< |
mapping |
|
type |
See Details. |
xscale |
Defaults to |
yscale |
Defaults to |
orientation |
Defaults to |
group |
Grouping for connecting lines through jitter |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
plot_name |
Metadata name of plot |
gg_theme |
As in |
xp_theme |
As in |
opt |
Processing options for fetched data |
quiet |
Silence extra debugging output |
jitter_seed |
A numeric, optional seed to be used in jitters |
... |
Any additional aesthetics. |
For type-based customization of plots:
b box-whisker (using default quantiles)
p points (from geom_dotplot)
v violin (from geom_violin)
o outliers (show outliers)
l line through 0 (or as indicated in hline_yintercept or
yline_xintercept)
s smooth line (from geom_smooth)
j jitter points (from geom_jitter)
c connecting lines for jitter points (from geom_path)
The desired plot
Following the xpose design pattern to derive <ggpairs> plots.
Established xplot_ are used to generate parts of the grid.
xplot_pairs( xpdb, mapping = NULL, cont_opts = list(group = "ID", guide = FALSE, type = "ps"), dist_opts = list(guide = FALSE, type = "hr"), cat_opts = list(type = "bo", log = NULL), contcont_opts = list(other_fun = NULL, stars = FALSE, digits = reportable_digits(xpdb), title = "Pearson Corr"), catcont_opts = list(other_fun = NULL, stars = FALSE, digits = reportable_digits(xpdb), title = "Spearman rho"), catcat_opts = list(use_rho = TRUE), title = NULL, subtitle = NULL, caption = NULL, tag = NULL, plot_name = "pairs", gg_theme, xp_theme, opt, quiet, progress = rlang::is_interactive() && quiet, switch = NULL, ... )xplot_pairs( xpdb, mapping = NULL, cont_opts = list(group = "ID", guide = FALSE, type = "ps"), dist_opts = list(guide = FALSE, type = "hr"), cat_opts = list(type = "bo", log = NULL), contcont_opts = list(other_fun = NULL, stars = FALSE, digits = reportable_digits(xpdb), title = "Pearson Corr"), catcont_opts = list(other_fun = NULL, stars = FALSE, digits = reportable_digits(xpdb), title = "Spearman rho"), catcat_opts = list(use_rho = TRUE), title = NULL, subtitle = NULL, caption = NULL, tag = NULL, plot_name = "pairs", gg_theme, xp_theme, opt, quiet, progress = rlang::is_interactive() && quiet, switch = NULL, ... )
xpdb |
< |
mapping |
|
cont_opts |
List of options to pass to |
dist_opts |
List of options to pass to |
cat_opts |
List of options to pass to |
contcont_opts |
List of options to pass to |
catcont_opts |
List of options to pass to |
catcat_opts |
A list with |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
plot_name |
Metadata name of plot |
gg_theme |
As in |
xp_theme |
As in |
opt |
Processing options for fetched data |
quiet |
Silence extra debugging output |
progress |
Show a progress bar as the plot is generated? |
switch |
Passed to |
... |
Ignored |
There is only limited control over the underlying ggpairs() call given
the need to address abstractions in GGally and xpose. However, users
can modify key display features. For scatter, distribution and boxplots,
the type option is directly forwarded to the user. For upper elements of the matrix,
users can modify features of the text displayed or supply some other
function entirely (other_fun).
_opts lists are consumed with <modifyList> from the default,
so there is no need to declare preferences that align with the default if updating
a subset.
specified pair plot
xpdb objectsThis function generates a set of xpose data (xpdb) objects that
can be used to define relationships between models. The
xpose_set(..., .relationships = NULL, .as_ordered = FALSE)xpose_set(..., .relationships = NULL, .as_ordered = FALSE)
... |
< |
.relationships |
< |
.as_ordered |
< |
Beyond just a list of xpdb objects, an xpose_set adds hierarchical information.
When using .relationships, these should be expressed as tilde formulas, where the left-hand side is
children and the right and side is parents. In the simplest case, this would be child ~ parent, but a child can have multiple parents. This
syntax expects that the names for models is either declared as argument names in the call, or that the
variable names are directly used (i.e., not spliced or passed as an unnamed list).
A list of class xpose_set
data("xpdb_ex_pk", package = "xpose") # Arbitrary copy xpdb_ex_pk2 <- xpdb_ex_pk # Simplest call set1 <- xpose_set(xpdb_ex_pk, xpdb_ex_pk2) # With predefined relationships set2 <- xpose_set(xpdb_ex_pk, xpdb_ex_pk2, .relationships = list(xpdb_ex_pk2 ~ xpdb_ex_pk) ) # Alternative predefined relationships set2b <- xpose_set(xpdb_ex_pk, xpdb_ex_pk2, .as_ordered = TRUE ) # With custom labels set3 <- xpose_set(mod1 = xpdb_ex_pk, mod2 = xpdb_ex_pk2, .relationships = list(mod2 ~ mod1) ) # Alternative set3 using dyanmic dots mod_list <- list( mod1 = xpdb_ex_pk, mod2 = xpdb_ex_pk2 ) mod_rels <- list( mod2 ~ mod1 ) set3b = xpose_set(!!!mod_list, .relationships = mod_rels)data("xpdb_ex_pk", package = "xpose") # Arbitrary copy xpdb_ex_pk2 <- xpdb_ex_pk # Simplest call set1 <- xpose_set(xpdb_ex_pk, xpdb_ex_pk2) # With predefined relationships set2 <- xpose_set(xpdb_ex_pk, xpdb_ex_pk2, .relationships = list(xpdb_ex_pk2 ~ xpdb_ex_pk) ) # Alternative predefined relationships set2b <- xpose_set(xpdb_ex_pk, xpdb_ex_pk2, .as_ordered = TRUE ) # With custom labels set3 <- xpose_set(mod1 = xpdb_ex_pk, mod2 = xpdb_ex_pk2, .relationships = list(mod2 ~ mod1) ) # Alternative set3 using dyanmic dots mod_list <- list( mod1 = xpdb_ex_pk, mod2 = xpdb_ex_pk2 ) mod_rels <- list( mod2 ~ mod1 ) set3b = xpose_set(!!!mod_list, .relationships = mod_rels)
Determine lineage within a set
xset_lineage(xpdb_s, ..., .spinner = NULL)xset_lineage(xpdb_s, ..., .spinner = NULL)
xpdb_s |
< |
... |
< |
.spinner |
Set to |
This function uses a not-especially-optimized tree-searching algorithm
to determine the longest lineage starting from whatever is treated as
the base model. It is based loosely on <pluck_depth>,
but the values at each depth are maintained.
As such, for larger sets this function and, more importantly,
functions that use it may take some time.
<character> vector of c('base', 'base child', 'base grandchild', ...) or list thereof, depending on dots arguments.
xset_lineage(xpdb_set) set_base_model(xpdb_set, fix1) %>% xset_lineage() xset_lineage(xpdb_set, fix1)xset_lineage(xpdb_set) set_base_model(xpdb_set, fix1) %>% xset_lineage() xset_lineage(xpdb_set, fix1)
Generic function primarily used with wrappers targeting types of values changed between two models.
xset_waterfall( xpdb_s, ..., .inorder = FALSE, type = "bh", .cols = NULL, max_nind = 0.7, scale_diff = TRUE, show_n = TRUE, title = NULL, subtitle = NULL, caption = NULL, tag = NULL, plot_name = "waterfall", opt, facets = NULL, facet_scales = "free_x", .problem, .subprob, .method, quiet )xset_waterfall( xpdb_s, ..., .inorder = FALSE, type = "bh", .cols = NULL, max_nind = 0.7, scale_diff = TRUE, show_n = TRUE, title = NULL, subtitle = NULL, caption = NULL, tag = NULL, plot_name = "waterfall", opt, facets = NULL, facet_scales = "free_x", .problem, .subprob, .method, quiet )
xpdb_s |
< |
... |
See < |
.inorder |
See < |
type |
See Details. |
.cols |
< |
max_nind |
If less than 1, the percentile of absolute change values above which to plot. If above 1, the absolute number of subjects is included. To show all, use an extreme positive number like 9999. |
scale_diff |
< |
show_n |
< |
title |
Plot title |
subtitle |
Plot subtitle |
caption |
Plot caption |
tag |
Plot tag |
plot_name |
Metadata name of plot |
opt |
User-specified data options. Only some of these will be used. |
facets |
< |
facet_scales |
< |
.problem |
The problem to be used, by default returns the last one. |
.subprob |
The subproblem to be used, by default returns the last one. |
.method |
The estimation method to be used, by default returns the last one. |
quiet |
Silence extra debugging output |
For type-based customization of plots:
b bar plot (from geom_bar)
h hline at 0 (from geom_hline)
t text of change value (from geom_text)
The desired plot