Package 'Certara.Xpose.NLME'

ETAs vs covariate Plot

Description

Plot ETAs against a continuous or categorical covariate.

Usage

eta_vs_cov(
  xpdb,
  covariate,
  mapping = NULL,
  drop_fixed = FALSE,
  group = "ID",
  type = "bpls",
  title = "ETAs vs @x | @run",
  subtitle = "Based on @nind individuals",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  onlyfirst = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

xpdb	An xpose database object.
covariate	Character; String of covariate name
mapping	List of aesthetics mappings to be used for the xpose plot (e.g. point_color).
drop_fixed	Logical; Logic specifying whether ETAs having same value for the given covariate value should be removed from plotting
group	Grouping variable to be used for lines. ID by default
type	Character; String setting the type of plot to be used. Must be 'b' for categorical covariates, one or a combination of 'p','l','s' for continuous covariates.
title	Character; Plot title. Use NULL to remove.
subtitle	Character; Plot subtitle. Use NULL to remove.
caption	Character; Page caption. Use NULL to remove.
tag	Character; Plot identification tag. Use NULL to remove.
log	Character; String assigning logarithmic scale to axes, can be either ”, 'x', y' or 'xy'.
guide	Logical; Should the guide (e.g. reference distribution) be displayed.
onlyfirst	Logical; Should the data be filtered to retain first value for each group/facet.
facets	Either a character string to use facet_wrap_paginate or a formula to use facet_grid_paginate.
.problem	The $problem number to be used. By default returns the last estimation problem.
quiet	Logical, if FALSE messages are printed to the console.
...	Any additional aesthetics to be passed on xplot_scatter or xplot_box.

Value

An object of class xpose_plot, ggplot, and gg. This object represents a customized plot created using ggplot2. The xpose_plot class provides additional metadata and integration with xpose workflows, allowing for advanced customization and compatibility with other xpose functions. Users can interact with the plot object as they would with any ggplot2 object, including modifying aesthetics, adding layers, or saving the plot.

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. boxplot_fill = 'blue', etc.

• box plot: options to geom_boxplot

• point plot: options to geom_point

• line plot: options to geom_line

• smooth plot: options to geom_smooth

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

See Also

xplot_scatter xplot_box

Examples

eta_vs_cov(xpose::xpdb_ex_pk,
  covariate = "WT",
  type = "ps",
  smooth_color = "red",
  point_color = "green",
  point_shape = "square",
  point_alpha = .5,
  point_size = 3
)

eta_vs_cov(xpose::xpdb_ex_pk,
  covariate = "AGE",
  type = "ps",
  facets = DOSE ~ variable,
  guide = TRUE,
  guide_color = "red",
  guide_slope = 0,
  guide_intercept = 0
)

---

Access NLME model overall fit results

Description

Access model fit diagnostics from an xpdb object generated by xposeNlme.

Usage

get_overallNlme(xpdb, .problem = 1, .subprob = 0, .method = NULL)

Arguments

xpdb	An xpose data base object from which the model output file data will be extracted. Only objects generated by xposeNlme are supported.
.problem	The problem to be used.
.subprob	The subproblem to be used.
.method	The estimation method to be used.

Value

A tibble for single problem/subproblem.

See Also

xposeNlme

Examples

# Store the parameter table
prmOverall <- get_overallNlme(xpdb_ex_Nlme)

---

Access NLME model parameter estimates

Description

Access model parameter estimates from an xpdb object generated by xposeNlme.

Usage

get_prmNlme(
  xpdb,
  .problem = 1,
  .subprob = 0,
  .method = NULL,
  digits = 6,
  show_all = FALSE,
  level = 0.95
)

Arguments

xpdb	An xpose data base object from which the model output file data will be extracted. Only objects generated by xposeNlme are supported.
.problem	The problem to be used.
.subprob	The subproblem to be used.
.method	The estimation method to be used.
digits	Integer specifying the number of significant digits to be displayed.
show_all	Logical specifying whether the 0 off-diagonal omega elements should be removed from the output or not.
level	Numeric specifying confidence level to compute confidence intervals, which are calculated based on Student’s t distribution.

Value

A tibble for single problem/subproblem.

See Also

xposeNlme

Examples

# Store the parameter table
prm <- get_prmNlme(xpdb_ex_Nlme)

# Set the desired number of significant digits to display results

# Note: To have results displayed in the number of significant digits
#  specified in the digits argument, one needs to make sure that
#  the value of pillar.sigfig option (default value is 3) is greater
#  than or equal to this specified value.

options(pillar.sigfig = 6)
get_prmNlme(xpdb_ex_Nlme, digits = 4)

---

Create covariates scatterplot

Description

Use to create covariates scatterplot.

Usage

nlme.cov.splom(
  xpdb,
  covColNames,
  ggupper = list(continuous = "cor", combo = "box_no_facet", discrete = "count", na =
    "na"),
  gglower = list(continuous = GGally::wrap("smooth", alpha = 0.3, size = 0.1), combo =
    "facethist", discrete = "facetbar", na = "na"),
  ggdiag = list(continuous = "densityDiag", discrete = "barDiag", na = "naDiag"),
  ...
)

Arguments

xpdb	An xpose database object.
covColNames	Character vector of covariates to build the matrix
ggupper	See ggpairs() upper argument.
gglower	See ggpairs() lower argument.
ggdiag	See ggpairs() diag argument.
...	Parameters to be passed to ggpairs().

Value

ggmatrix object.

Examples

nlme.cov.splom(xpdb = xpdb_ex_Nlme,
covColNames = c("sex", "wt", "age")
)

---

Plot parameter estimates against covariates

Description

Use to create a stack of plots of parameter estimates plotted against covariates.

Usage

nlme.par.vs.cov(xpdb, covColNames, nrow = 1, ncol = 1, ...)

Arguments

xpdb	An xpose database object.
covColNames	Character vector of covariates to build the matrix.
nrow	Number of rows.
ncol	Number of columns; if ncol=1, each gtable object is treated separately.
...	Parameters to be passed to ggarrange().

Value

List of gtable

Examples

nlme.par.vs.cov(
  xpdb = xpdb_ex_Nlme,
  covColNames = c("sex", "wt", "age")
)

---

Plot random parameter estimates against covariates

Description

Use to create a stack of plots of random parameter estimates plotted against covariates.

Usage

nlme.ranpar.vs.cov(xpdb, covColNames, nrow = 1, ncol = 1, ...)

Arguments

xpdb	An xpose database object.
covColNames	Character vector of covariates to build the matrix.
nrow	Number of rows.
ncol	Number of columns; if ncol=1, each gtable object is treated separately.
...	Parameters to be passed to ggarrange()

Value

List of gtable

Examples

nlme.ranpar.vs.cov(xpdb = xpose::xpdb_ex_pk,
covColNames = c("SEX", "CLCR", "AGE")
)

---

Build multiple plots for selected variable vs covariates

Description

The type of plot depends on the type of covariate: boxplot for categorical, geom_point and geom_smooth for continuous.

Usage

nlme.var.vs.cov(xpdb, covColNames, nrow = 1, ncol = 1, yVar = "WRES", ...)

Arguments

xpdb	An xpose database object.
covColNames	Character vector of covariates to build the matrix.
nrow	Number of rows.
ncol	Number of columns; if ncol=1, each gtable object is treated separately.
yVar	Variable from xpdb data to build a plot.
...	Parameters to be passed to ggarrange()

Value

List of gtable

Examples

nlme.var.vs.cov(
  xpdb = xpdb_ex_Nlme,
  covColNames = c("sex", "wt", "age"),
  yVar = "WRES",
  nrow = 2,
  ncol = 2
  )

---

Parameter vs covariate Plot

Description

Plot Parameters against a continuous or categorical covariate.

Usage

prm_vs_cov(
  xpdb,
  covariate,
  mapping = NULL,
  drop_fixed = FALSE,
  group = "ID",
  type = "bpls",
  title = "Parameters vs @x | @run",
  subtitle = "Based on @nind individuals",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = FALSE,
  onlyfirst = FALSE,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

xpdb	An xpose database object.
covariate	Character; String of covariate name
mapping	List of aesthetics mappings to be used for the xpose plot (e.g. point_color).
drop_fixed	Logical; logic specifying whether structural parameters having same value for the given covariate value should be removed from plotting
group	Grouping variable to be used for lines. ID by default
type	Character; String setting the type of plot to be used. Must be 'b' for categorical covariates, one or a combination of 'p','l','s' for continuous covariates.
title	Character; Plot title. Use NULL to remove.
subtitle	Character; Plot subtitle. Use NULL to remove.
caption	Character; Page caption. Use NULL to remove.
tag	Character; Plot identification tag. Use NULL to remove.
log	Character; String assigning logarithmic scale to axes, can be either ”, 'x', y' or 'xy'.
guide	Logical; Enable guide display (e.g. unity line).
onlyfirst	Logical; Should the data be filtered to retain first value for each group/facet.
facets	Either a character string to use facet_wrap_paginate or a formula to use facet_grid_paginate.
.problem	The $problem number to be used. By default returns the last estimation problem.
quiet	Logical, if FALSE messages are printed to the console.
...	Any additional aesthetics to be passed on xplot_scatter or xplot_box.

Value

An object of class xpose_plot, ggplot, and gg. This object represents a customized plot created using ggplot2. The xpose_plot class provides additional metadata and integration with xpose workflows, allowing for advanced customization and compatibility with other xpose functions. Users can interact with the plot object as they would with any ggplot2 object, including modifying aesthetics, adding layers, or saving the plot.

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. boxplot_fill = 'blue', etc.

• box plot: options to geom_boxplot

• point plot: options to geom_point

• line plot: options to geom_line

• smooth plot: options to geom_smooth

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

See Also

xplot_scatter xplot_box

Examples

prm_vs_cov(xpose::xpdb_ex_pk,
  covariate = "AGE", type = "ps",
  log = "y",
  yscale_breaks = scales::trans_breaks("log10", function(x) 10^x),
  yscale_labels = scales::trans_format("log10", scales::math_format(10^.x)),
  caption = NULL
)

prm_vs_cov(xpose::xpdb_ex_pk,
  covariate = "SEX",
  type = "b",
  boxplot_fill = "blue",
  boxplot_color = "black",
  boxplot_outlier.color = "red"
)

---

Residuals vs covariate plot

Description

Plot Residuals against a continuous or categorical covariate.

Usage

res_vs_cov(
  xpdb,
  mapping = NULL,
  covariate,
  res = "CWRES",
  group = "ID",
  type = "bpls",
  title = "Residuals vs @x | @run",
  subtitle = "Based on @nind individuals",
  caption = "@dir",
  tag = NULL,
  log = NULL,
  guide = TRUE,
  facets,
  .problem,
  quiet,
  ...
)

Arguments

xpdb	An xpose database object.
mapping	List of aesthetics mappings to be used for the xpose plot (e.g. point_color).
covariate	Character; String of covariate name
res	Character; String of residual name; CWRES by default.
group	Grouping variable to be used for lines. ID by default
type	Character; String setting the type of plot to be used. Must be 'b' for categorical covariates, one or a combination of 'p','l','s' for continuous covariates.
title	Character; Plot title. Use NULL to remove.
subtitle	Character; Plot subtitle. Use NULL to remove.
caption	Character; Page caption. Use NULL to remove.
tag	Character; Plot identification tag. Use NULL to remove.
log	Character; String assigning logarithmic scale to axes, can be either ”, 'x', y' or 'xy'.
guide	Logical; Should the guide (e.g. reference distribution) be displayed.
facets	Either a character string to use facet_wrap_paginate or a formula to use facet_grid_paginate.
.problem	The $problem number to be used. By default returns the last estimation problem.
quiet	Logical, if FALSE messages are printed to the console.
...	Any additional aesthetics to be passed on xplot_scatter or xplot_box.

Value

An object of class xpose_plot, ggplot, and gg. This object represents a customized plot created using ggplot2. The xpose_plot class provides additional metadata and integration with xpose workflows, allowing for advanced customization and compatibility with other xpose functions. Users can interact with the plot object as they would with any ggplot2 object, including modifying aesthetics, adding layers, or saving the plot.

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. boxplot_fill = 'blue', etc.

• box plot: options to geom_boxplot

• point plot: options to geom_point

• line plot: options to geom_line

• smooth plot: options to geom_smooth

• xscale: options to scale_x_continuous or scale_x_log10

• yscale: options to scale_y_continuous or scale_y_log10

See Also

xplot_scatter xplot_box

Examples

res_vs_cov(xpose::xpdb_ex_pk,
  covariate = "SEX",
  type = "b",
  res = "WRES"
)

res_vs_cov(xpose::xpdb_ex_pk,
  covariate = "AGE",
  type = "ps",
  res = c("CWRES", "WRES", "IRES", "IWRES")
)

---

XposeNlme examples

Description

One compartment NLME model with 3 covariates xpose_data example built from simulated values.

Format

An xpose::xpose_data object

Examples

print(xpdb_ex_Nlme)

---

Default xpose box plot function

Description

Manually generate categorical covariate box plots against eta.

Usage

xplot_box(
  xpdb,
  mapping = NULL,
  type = "b",
  guide = FALSE,
  yscale = "continuous",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  plot_name = "box_plot",
  gg_theme,
  xp_theme,
  opt,
  quiet,
  ...
)

Arguments

xpdb	An xpose database object.
mapping	List of aesthetics mappings to be used for the xpose plot (e.g. point_color).
type	String setting the type of plot to be used. Only 'b' applicable.
guide	Enable guide display (e.g. unity line).
yscale	Scale type for y axis (e.g. 'continuous', 'discrete', 'log10').
title	Plot title. Use NULL to remove.
subtitle	Plot subtitle. Use NULL to remove.
caption	Page caption. Use NULL to remove.
tag	Plot identification tag. Use NULL to remove.
plot_name	Name to be used by xpose::xpose_save() when saving the plot.
gg_theme	A complete ggplot2 theme object (e.g. ggplot2::theme_classic), a function returning a complete ggplot2 theme, or a change to the current gg_theme.
xp_theme	A complete xpose theme object (e.g. theme_xp_default) or a list of modifications to the current xp_theme (e.g. list(point_color = 'red', line_linetype = 'dashed')).
opt	A list of options in order to create appropriate data input for ggplot2. For more information see data_opt.
quiet	Logical, if FALSE messages are printed to the console.
...	Any additional aesthetics to be passed on xplot_scatter.

Value

An object of class xpose_plot, ggplot, and gg. This object represents a customized plot created using ggplot2. The xpose_plot class provides additional metadata and integration with xpose workflows, allowing for advanced customization and compatibility with other xpose functions. Users can interact with the plot object as they would with any ggplot2 object, including modifying aesthetics, adding layers, or saving the plot.

Faceting

Every xpose plot function has built-in faceting functionalities. Faceting arguments are passed to the functions facet_wrap_paginate when the facets argument is a character string (e.g. facets = c('SEX', 'MED1')) or facet_grid_paginate when facets is a formula (e.g. facets = SEX~MED1). All xpose plot functions accept all the arguments for the facet_wrap_paginate and facet_grid_paginate functions e.g. dv_vs_ipred(xpdb_ex_pk, facets = SEX~MED1, ncol = 3, nrow = 3, page = 1, margins = TRUE, labeller = 'label_both').

Faceting options can either be defined in plot functions (e.g. dv_vs_ipred(xpdb_ex_pk, facets = 'SEX')) or assigned globally to an xpdb object via the xp_theme (e.g. xpdb <- update_themes(xpdb_ex_pk, xp_theme = list(facets = 'SEX'))). In the latter example all plots generate from this xpdb will automatically be stratified by 'SEX'.

By default, some plot functions use a custom stratifying variable named 'variable', e.g. eta_distrib(). When using the facets argument, 'variable' needs to be added manually e.g. facets = c('SEX', 'variable') or facets = c('SEX', 'variable'), but is optional, when using the facets argument in xp_theme variable is automatically added whenever needed.

Layers mapping

Plots can be customized by mapping arguments to specific layers. The naming convention is layer_option where layer is one of the names defined in the list below and option is any option supported by this layer e.g. boxplot_fill = 'blue', etc.

• box plot: options to geom_boxplot

• yscale: options to scale_y_continuous or scale_y_log10

See Also

xplot_scatter xplot_qq

Examples

# Categorical Covariate MED1 vs ETA1
xplot_box(xpose::xpdb_ex_pk, ggplot2::aes(x = MED1, y = ETA1))

# Categorical Covariate SEX vs CL
xplot_box(xpose::xpdb_ex_pk, ggplot2::aes(x = SEX, y = CL))

---

Creates xpose database from Certara.RsNLME output files

Description

Imports results of an NLME run into xpose database Use to import NLME model output files into xpdb object that is compatible with existing model diagnostic function in Xpose package.

Usage

xposeNlme(
  dir = "",
  modelName = "",
  dmpFile = "dmp.txt",
  dmp.txt = NULL,
  dataFile = "data1.txt",
  logFile = "nlme7engine.log",
  ConvergenceData = NULL,
  progresstxt = "progress.txt"
)

Arguments

dir	Path to NLME Run directory. Current working directory is used if dir not given.
modelName	name of the model to be written in xpdb$summary$value with run label
dmpFile	NLME generated output file.
dmp.txt	NLME generated output from dmpFile (substitutes dmpFile if presented).
dataFile	Input file for NLME Run.
logFile	engine log file
ConvergenceData	optional data frame with Nlme convergence info.
progresstxt	optional NLME-generated file 'progress.txt' with convergence info. ConvergenceData has more priority if both are given.

Details

Not all functionality from the xpose package is supported.

Value

xpdb object

Examples

# files in arguments supposed to be in the current working directory:
xp <- xposeNlme(
  dir = getwd(),
  modelName = "PMLModel",
  dmpFile = "dmp.txt",
  dataFile = "data1.txt",
  logFile = "nlme7engine.log",
  progresstxt = "progress.txt"
)

# using dmp.txt structure and Convergence Data loaded previously:
xp <- xposeNlme(
  dir = "~/Model1/",
  modelName = "Model1",
  dmp.txt = dmp.txt,
  dataFile = "Data.csv",
  logFile = "nlme7engine.log",
  ConvergenceData = ConvergenceData
)

# explore unique covariate plots specific to Certara.Xpose.NLME:
nlme.cov.splom(xp, covColNames = c("AGE", "WT"))
nlme.par.vs.cov(xp, covColNames = c("AGE", "WT"))

res_vs_cov(xp, covariate = "AGE", res = "IWRES")

# or use existing plotting functions from the xpose package
library(xpose)
dv_vs_pred(xp)
res_vs_idv(xp)

---

Creates xpose database from Certara.RsNLME objects

Description

Imports results of an NLME run into xpose database Use to import NLME model object and NLME object output into xpdb object that is compatible with existing model diagnostic function in Xpose package.

Usage

xposeNlmeModel(model, fitmodelOutput)

Arguments

model	NlmePmlModel model class object generated by Certara.RsNLME package
fitmodelOutput	the output object of Certara.RsNLME::fitmodel() run.

Details

Not all functionality from the xpose package is supported.

Value

xpdb object

Examples

library(Certara.RsNLME)
library(Certara.Xpose.NLME)

model <- pkmodel(
  parameterization = "Clearance",
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc"
)

fit <- fitmodel(model)

xp <- xposeNlmeModel(
  model = model,
  fitmodelOutput = fit
)

---