| Title: | Normalised Prediction Distribution Errors for Nonlinear Mixed-Effect Models |
| Version: | 3.5 |
| Date: | 2024-02-06 |
| Maintainer: | Emmanuelle Comets <emmanuelle.comets@inserm.fr> |
| Description: | Provides routines to compute normalised prediction distribution errors, a metric designed to evaluate non-linear mixed effect models such as those used in pharmacokinetics and pharmacodynamics. |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| Encoding: | UTF-8 |
| LazyLoad: | yes |
| LazyData: | yes |
| Imports: | methods, scales, ggplot2, mclust, grid, gridExtra, rlang |
| RoxygenNote: | 7.3.1 |
| Collate: | 'NpdeSimData.R' 'NpdeData.R' 'aaa_generics.R' 'NpdeData-methods.R' 'NpdeRes.R' 'NpdeRes-methods.R' 'NpdeObject.R' 'NpdeObject-methods.R' 'compute_distribution.R' 'compute_npde.R' 'compute_pd.R' 'compute_ploq.R' 'mainNpde.R' 'npde.R' 'npdeControl.R' 'plotNpde-auxDistPlot.R' 'plotNpde-auxScatter.R' 'plotNpde-auxScatterPlot.R' 'plotNpde-binningPI.R' 'plotNpde-covplot.R' 'plotNpde-distributionPlot.R' 'plotNpde-methods.R' 'plotNpde-plotFunctions.R' 'plotNpde-scatterplot.R' |
| NeedsCompilation: | no |
| Packaged: | 2024-02-07 08:27:15 UTC; eco |
| Author: | Emmanuelle Comets 
[aut, cre],
Karl Brendel [ctb],
Thi Huyen Tram Nguyen [ctb],
Marc Cerou [ctb],
Romain Leroux [ctb],
France Mentre [ctb] |
| Repository: | CRAN |
| Date/Publication: | 2024-02-07 09:50:02 UTC |
Normalised prediction distribution errors for nonlinear mixed-effect models
Description
Routines to compute normalised prediction distribution errors, a metric designed to evaluate non-linear mixed effect models such as those used in pharmacokinetics and pharmacodynamics
Author(s)
Emmanuelle Comets, Karl Brendel, Thi Huyen Tram Nguyen, France Mentre
Maintainer: Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
PDF documentation for npde 3.0: https://github.com/ecomets/npde30/blob/main/userguide_npde_3.0.pdf
Examples
data(theopp)
data(simtheopp)
# Calling autonpde with dataframes
x<-autonpde(theopp,simtheopp,ix="Time",iy="Conc",iid="ID",boolsave=FALSE)
print(x)
Class "NpdeData" representing the structure of the longitudinal data
Description
A longitudinal data structure
Objects from the Class
NpdeData objects are typically created by a call to npdeData contain the following slots:
- name.group
character string giving the name of the grouping term (ID)
- name.predictor
character string giving the name of the predictor (X)
- name.response
character string giving the name of the response (Y)
- name.cens
character string giving the name of the censoring indicator in the original dataset (renamed to cens)
- name.mdv
character string giving the name of the missing data indicator in the original dataset (renamed to mdv)
- name.covariates
vector of character string giving the name(s) of the covariates
- name.ipred
character string giving the name of the individual predictions
- units
(optional) a list with the units for X, Y, and covariates
- data
a dataframe containing the data
- N
number of subjects
- ntot.obs
total number of non-missing observations
- nind.obs
vector of size N giving the number of non-missing observations for each subject
- ind
index of non-missing observations
- icens
index of censored observations (non-missing)
- not.miss
a vector of boolean indicating for each observation whether it is missing (FALSE) or available (TRUE)
- loq
the censoring value
Methods
- show(npde.data):
Prints a short summary of object npde.data
- qqplot.npde(npde.data):
QQ-plot for NpdeData object (TODO: change for NpdeObject in final package)
Examples
methods(class="NpdeData")
showClass("NpdeData")
Class "NpdeObject"
Description
An object of class NpdeObject
Objects from the Class
NpdeObject objects are typically created by calls to npde or autonpde. They contain the following slots:
- data
an object of class NpdeData, containing the observed data
- sim.data
an object of class NpdeSimData, containing the simulated data
- results
an object of class NpdeRes, containing the results
- options
a list of options
- prefs
a list of graphical preferences for the plots
Methods
- print(x):
Prints a summary of object
- show(x):
Prints a short summary of object
- showall(x):
Prints a detailed summary of object
- plot(x):
Diagnostic and other plots. More details can be found in
plot.NpdeObject- summary(x):
Returns a summary of object x in list format
- gof.test(x, parametric=TRUE, ...):
Returns goodness-of-fit tests
- set.plotoptions(x):
Sets options for graphs (internal method used in plots)
See Also
npde, autonpde, NpdeData, NpdeSimData, NpdeRes, gof.test
Examples
methods(class="NpdeObject")
showClass("NpdeObject")
Class "NpdeRes"
Description
The results component of a NpdeObject object
Objects from the Class
NpdeRes objects are created during a call to npde or autonpde as the "results" slot in a NpdeObject object. An NpdeRes object contains the following slots:
- res
a dataframe containing the results. Columns include id (group), xobs (observed X), yobs (observed Y), cens (indicator for censored data), as well as the actual results: ypred (model population predictions), pd (prediction discrepancies), npde (normalised prediction distribution errors), ycomp (completed data), ydobs (decorrelated observed data).
- N
number of subjects
- ntot.obs
total number of non-missing observations
- ploq
a vector giving the probability that a given observation is LOQ, according to the model
- icens
index of (non-missing) censored observations
- not.miss
a vector of boolean indicating for each observation whether it is missing (FALSE) or available (TRUE)
- pd.sim
pd computed for a number of simulated datasets (optional, used to obtain prediction intervals on the distribution of pd)
- npde.sim
npde computed for a number of simulated datasets (optional, used to obtain prediction intervals on the distribution of npde)
Methods
- print(npde.res):
Prints a summary of object npde.res
- show(npde.res):
Prints a short summary of object npde.res
- showall(npde.res):
Prints a detailed summary of object npde.res
- plot(npde.res):
Plots the data in npde.res. More details can be found in
plot.NpdeRes- summary(npde.res):
Returns a summary of object npde.res in list format
- gof.test(x, parametric=TRUE, ...):
Returns goodness-of-fit tests
See Also
npde, autonpde, plot.NpdeRes, NpdeObject
Examples
methods(class="NpdeRes")
showClass("NpdeRes")
Class "NpdeSimData" representing the structure of the longitudinal data
Description
A longitudinal data structure, with simulated data
Objects from the Class
NpdeSimData objects are created by associating an NpdeData object with matching simulated data, and they contain the following slots.
- nrep
number of replications)
- datsim
a dataframe containing the simulated data, with columns: idsim (subject id), irsim (replication index), xsim (simulated x), ysim (simulated response). After a call to
npdeorautonpde, an additional column ydsim (decorrelated replicated data) will be added.
Methods
- print(npde.simdata):
Prints a summary of object npde.simdata
- show(npde.simdata):
Prints a short summary of object npde.simdata
- showall(npde.simdata):
Prints a detailed summary of object npde.simdata
See Also
Examples
showClass("NpdeSimData")
Get/set methods for NpdeData object
Description
Access slots of a NpdeData using the object["slot"] format
Usage
## S4 method for signature 'NpdeSimData'
x[i, j, drop]
## S4 method for signature 'NpdeData'
x[i, j, drop]
## S4 replacement method for signature 'NpdeData'
x[i, j] <- value
## S4 method for signature 'NpdeRes'
x[i, j, drop]
## S4 method for signature 'NpdeObject'
x[i, j, drop]
Arguments
x |
object from which to extract element(s) or in which to replace element(s) |
i, j |
indices specifying elements to extract or replace. Indices are numeric or character vectors or empty (missing) or NULL |
drop |
For matrices and arrays. If TRUE the result is coerced to the lowest possible dimension (see the examples). This only works for extracting elements, not for the replacement. See drop for further details |
value |
typically an array-like R object of a similar class as x |
Compute normalised prediction distribution errors
Description
These functions compute normalised prediction distribution errors (npde) and
prediction discrepancies (pd). npde asks the user the name
and structure of the files containing the data, using pdemenu, while
autonpde takes these variables and others as arguments.
Usage
autonpde(namobs, namsim, iid, ix, iy, imdv = 0, icens = 0,
icov = 0, iipred = 0, boolsave = TRUE, namsav = "output", type.graph = "eps",
verbose = FALSE, calc.npde=TRUE, calc.npd=TRUE, decorr.method = "cholesky",
cens.method = "cdf", units = list(x="",y=""), detect=FALSE, ties=TRUE, header=TRUE)
npde()
npde()
Arguments
namobs |
name of the file containing the observed data, or a dataframe
containing the observed data (in both cases, the column containing the
various data required for the computation of the pde can be set using the
arguments |
namsim |
name of the file containing the simulated data, or a dataframe containing the simulated data (the program will assume that subject ID are in column 1 and simulated Y in column 3, see User Guide) |
iid |
name/number of the column in the observed data containing the patient ID; if missing, the program will attempt to detect a column named id |
ix |
name/number of the column in the observed data containing the independent variable (X); ; if missing, the program will attempt to detect a column named X |
iy |
name/number of the column in the observed data containing the dependent variable (Y); if missing, the program will attempt to detect a column with the response |
imdv |
name/number of the column containing information about missing data (MDV), defaults to 0 (column not present) |
icens |
name/number of the column containing information about censored data (cens), defaults to 0 (column not present) |
icov |
name/number of the column(s) containing covariate information defaults to 0 (no covariates) |
iipred |
name/number of the column(s) with individual predictions (ipred), defaults to 0 (individual predictions not available) |
boolsave |
a boolean (TRUE if graphs and results are to be saved to a file, FALSE otherwise), defaults to TRUE |
namsav |
name of the files to which results are to be saved (defaults to "output", which will produce a file called output.eps (if the default format of postscript is kept, see type.graph) for the graphs and a file called output.npde for the numerical results (see value) |
type.graph |
type of graph (one of "eps","jpeg","png","pdf"), defaults to postscript ("eps") |
verbose |
a boolean (TRUE if messages are to be printed as each subject is processed, FALSE otherwise), defaults to FALSE |
calc.npde |
a boolean (TRUE if npde are to be computed, FALSE otherwise), defaults to TRUE |
calc.npd |
a boolean (TRUE if npd are to be computed, FALSE otherwise), defaults to TRUE |
decorr.method |
a character string indicating the method used to decorrelate
observed and simulated data in the computation of npde (see |
cens.method |
a character string indicating the method used to handle
censored data (see |
units |
a list with components x, y and cov (optional), specifying the units respectively for the predictor (x), the response (y), and the covariates (a vector of length equal to the number of covariates). Units will default to (-) if not given. |
detect |
a boolean controlling whether automatic recognition of columns in the dataset is on, defaults to FALSE |
ties |
a boolean (if FALSE, the distributions of pd and npde are smoothed by jittering the values so that there are no ties), defaults to TRUE |
header |
a boolean (TRUE if input files have headers, FALSE otherwise), defaults to TRUE |
Details
Both functions compute the normalised prediction distribution errors (and/or
prediction discrepancies) in the same way. npde is an interactive
function whereas autonpde takes all required input as arguments.
Diagnostic graphs are produced for npd, and npde are used in the tests as their distribution takes into account the correlation between repeated observations.
When the computation of npde fails because of numerical problems, error messages are printed out, then pd are computed instead and graphs of pd are plotted so that the user may evaluate why the computation failed.
The function also prints out the characteristics of the distribution of the npde (mean, variance, skewness and kurtosis) as well as the results of the statistical tests applied to npde. In addition, if boolsave is TRUE, two files are created:
- results file
the numerical results are saved in a file with extension .npde (the name of which is given by the user). The file contains the components id, xobs, ypred, npde, pd stored in columns
- graph file
the graphs are saved to a file with the same name as the results file, and with extension depending on the format.
Value
An object of class NpdeObject
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
PDF documentation for npde 3.0: https://github.com/ecomets/npde30/blob/main/userguide_npde_3.0.pdf
See Also
Examples
data(theopp)
data(simtheopp)
# Calling autonpde with dataframes
x<-autonpde(theopp,simtheopp,1,3,4,boolsave=FALSE)
x
head(x["results"]["res"])
plot(x)
Compute P(y_ij<LOQ) for all observations
Description
For each observation in the dataset, computes the probability to be below LOQ using the simulations under the model. This is generally performed automatically.
Usage
compute.ploq(npdeObject)
Arguments
npdeObject |
Value
an object of class NpdeObject with a component ploq in the ["results"] slot
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
Internal functions used to compute normalised prediction distribution errors (npde)
Description
Functions used by npde and autonpde to compute prediction
discrepancies (not intended for the end-user).
Usage
computenpde(npdeObject,...)
Arguments
npdeObject |
an object of class NpdeObject |
... |
additional options to modify |
Details
These functions are normally not called by the end-user.
Value
an object of class NpdeObject; the results slot will now include prediction discrepancies (npde) as well as decorrelated observed data, while the sim.data slot will now include decorrelated simulated data
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
Internal functions used to compute prediction discrepancies
Description
Functions used by npde and autonpde to compute prediction
discrepancies (not intended for the end-user).
Usage
computepd(npdeObject,...)
Arguments
npdeObject |
an object of class NpdeObject |
... |
additional options to modify |
Details
These functions are normally not called by the end-user.
Value
an object of class NpdeObject; the results slot will now include prediction discrepancies (pd) as well as model predictions (ypred) obtained as the mean of the simulated data for each observation
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
Default plots for a NpdeObject object
Description
Default plots for a NpdeObject object
Usage
default.npde.plots(npdeObject, ...)
Arguments
npdeObject |
|
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Value
a ggplot object
Compute distribution of pd/npde using simulations
Description
This function is used to build the distribution of pd/npde using the simulations under the model. The default is to build only the distribution of pd, and to sample from N(0,1) when building the distribution of npde under the null hypothesis.
Usage
dist.pred.sim(npdeObject,nsamp, ...)
Arguments
npdeObject |
|
nsamp |
number of datasets (defaults to 100 or to the number of replications if it is smaller) |
... |
additional arguments. Currently only the value of calc.npd and calc.npde may be passed on, and will override their corresponding value in the "options" slot of npdeObject |
Value
an object of class NpdeObject; the ["results"] slot will contain pd and/or npde for a sample of the simulated datasets (depending on whether calc.npd/calc.npde are set), stored in pd.sim and/or npde.sim
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
Examples
data(theopp)
data(simtheopp)
x<-autonpde(theopp,simtheopp,1,3,4,boolsave=FALSE)
# Use random samples from N(0,1) to obtain a prediction interval on the empirical cdf of the npde
plot(x,plot.type="ecdf",bands=TRUE,approx.pi=TRUE)
# defaults to computing the pd and npde for 100 simulated datasets
# (in the theophylline example, this uses all the simulated datasets)
x<-dist.pred.sim(x)
# Use the npde from the simulated datasets to obtain a prediction interval on the empirical cdf
plot(x,plot.type="ecdf",bands=TRUE,approx.pi=FALSE)
Goodness-of-fit tests for npde
Description
Performs test on the selected variable (which=one of npde, pd or npd) or on a numeric vector
Usage
gof.test(object, parametric = TRUE, ...)
printgoftest(object, ...)
Arguments
object |
an object (currently has methods for types numeric, NpdeRes and NpdeObject) |
parametric |
a boolean. If TRUE (default), parametric tests are performed |
... |
additional arguments passed on to the function; special arguments are |
Details
If object is an NpdeObject and an argument covsplit=TRUE is given in ..., in addition to the global descriptive statistics and tests, tests will be performed for each covariate in which.cov. This argument can be set in ...; barring an explicit specification, the component which.cov of the prefs slot for a NpdeObject object will be used. The default value is which.cov="all", which produces tests for each covariate in the dataset. Two additional dataframes will then be present:
- cov.stat
descriptive statistics and test p-values split by covariate and by categories
- cov.p.value
p-values split by covariate; for each covariate, two tests are performed: the first test is a correlation test for continuous covariates and a Chi-square test for categorical covariates; the second test is defined using the p-values of the global tests split by each category, and appling a Bonferroni correction to obtain an overall p-value (see PDF documentation for details)
The p.value elements is a named vector with four components:
- p.mean
p-value for the mean test (Wilcoxon test if parametric=FALSE, Student test if parametric=TRUE)
- p.var
p-value for the variance test (parametric=FALSE, Fisher test if parametric=TRUE)
- p.dist
p-value for the distribution test (Shapiro-test for normality (npd, npde)/Kolmogorove-Smirnov test for uniformity)
- p.global
p-value for the global test (combination of the mean, variance and distribution tests with a Bonferroni correction)
The p-values are adjusted using a Bonferroni correction: the raw p-values of the 3 individual tests are multiplied by 3, and the p-value for the global test is equal to the minimum of the adjusted p-values.
Value
A list with the following elements:
- mean
mean
- se.mean
standard error of the mean
- var
variance
- se.var
standard error on variance
- kurtosis
kurtosis (see
kurtosis)- skewness
skewness (see
skewness)- p.value
p-values for several tests (see below)
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
K. Brendel, E. Comets, C. Laffont, and F. Mentre. Evaluation of different tests based on observations for external model evaluation of population analyses. Journal of Pharmacokinetics and Pharmacodynamics, 37:49–65, 2010.
See Also
Examples
data(theopp)
data(simtheopp)
#' # Calling autonpde with dataframes
x<-autonpde(theopp,simtheopp,1,3,4,boolsave=FALSE)
gof.test(x)
Kurtosis
Description
Computes the kurtosis.
Usage
kurtosis(x)
Arguments
x |
a numeric vector containing the values whose kurtosis is to be computed. NA values are removed in the computation. |
Details
If N = \mathrm{length}(x), then the kurtosis of x
is defined as:
N sum_i (x_i-\mathrm{mean}(x))^4 (sum_i
(x_i-\mathrm{mean}(x))^2)^(-2) -
3
Value
The kurtosis of x.
References
G. Snedecor, W. Cochran. Statistical Methods, Wiley-Blackwell, 1989
Examples
x <- rnorm(100)
kurtosis(x)
Internal functions used to produce prediction intervals
Description
Functions used by plot functions to define the boundaries of the bins on the X-axis
Usage
npde.binning(xvec, plot.opt, verbose = FALSE)
Arguments
xvec |
a vector of values for the X-axis of the plot |
plot.opt |
graphical options |
verbose |
boolean (defaults to FALSE). If TRUE, a table showing how the binning was performed |
Details
These functions are normally not called by the end-user but are now exported for use in the saemix package.
Value
a list with 3 elements, xgrp (the number of the bin associated with each element of xvec), xcent (a named vector containing the mean of the elements of xvec contained in each bin; the name of the bin is the interval), and xgroup (a vector with the group associated to each element of xvec after binning) If verbose is TRUE, a table showing the bins is shown, giving the interval of xvec associated with each bin, the mean value of xvec in each bin, and the number of observations
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
Method used to handle censored data
Description
Specifies the method used to handle censored data (data below the limit of quantification LOQ
Details
Several methods are available to handle censored data.
- omit
pd and npde for censored data will be set to NA
- cdf
for an observation ycens_ij under the LOQ, a pd_ij will be imputed in the uniform distribution [0-pLOQ_ij] where pLOQ_ij is the probability that y_ij is below LOQ, according to the model; the predictive distribution will then be used to obtain a corresponding y*_ij. This is also performed for all simulated data, and the npde are then computed on the completed dataset containing the observed y_ij for the uncensored data and the y*_ij imputed for the censored data. This method is the default.
- ipred
an observation ycens_ij is replaced by the individual prediction according to the model (ipred, which must be present in the dataset). Simulated data are left untouched.
- ppred
an observation ycens_ij is replaced by the population prediction according to the model. Simulated data are left untouched.
- loq
an observation ycens_ij is replaced by the value of the LOQ. Simulated data are left untouched.
Value
This is not a function and does not have a return value, this is a statistical method.
More details can be found in the PDF documentation.
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
Examples
## Not run:
# You need to have gridExtra installed to successfully run this example
if(requireNamespace("gridExtra", quietly=TRUE)) {
data(warfarin)
data(simwarfarinCov)
wcov<-autonpde(namobs=warfarin,namsim=simwarfarinCov, iid=1,ix=2,iy=4,icov=c(3,6:8),
namsav="warfCov", units=list(x="hr",y="mg/L", covariates=c("mg","kg","-","yr")))
# Diagnostic plots for warfarin with a covariate model
plot(wcov)
# Covariate plots
xwt.scatt<-plot(wcov, plot.type="x.scatter", covsplit=TRUE, which.cov="wt")
xwt.qqplot<-plot(wcov, plot.type="qqplot", covsplit=TRUE, which.cov="wt")
xwt.box<-plot(wcov, plot.type="covariates", which.cov="wt")
xsex.scatt<-plot(wcov, plot.type="x.scatter", covsplit=TRUE, which.cov="sex")
xsex.qqplot<-plot(wcov, plot.type="qqplot", covsplit=TRUE, which.cov="sex")
xsex.box<-plot(wcov, plot.type="covariates", which.cov="sex")
# Transforming the reference profile for npd, compared to a VPC plot
plot.tnpd<-plot(wcov, plot.type="x.scatter", ref.prof=list(id=2),
main="tnpd with reference profile ID=2")
plot.vpc<-plot(wcov, plot.type="vpc", main="VPC")
gridExtra::grid.arrange(grobs=list(plot.tnpd, plot.vpc), nrow=1, ncol=2)
}
## End(Not run)
Decorrelation methods in npde
Description
Specifies the method used to decorrelate observed and simulated data
Arguments
x |
a square matrix
@return This is not a function and does not have a return value, this is a statistical method. |
Details
More details can be found in the PDF documentation.
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
Save the graphs for a NpdeObject object to a file
Description
Save the graphs to a file on disk
Usage
npde.graphs(object, ...)
Arguments
object |
a NpdeObject object |
... |
optional arguments to replace options in object |
Details
The following options can be changed by passing the appropriate arguments: namsav (string giving the root name of the files, an extension depending on the type of graph will be added), namgr (string giving the full name of the file), type.graph (one of "eps", "pdf", "jpeg", "png")
Value
No return value, called for side effects
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F.Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
Main npde function
Description
Main npde function, used to compute pd and npde
Usage
npde.main(object)
Arguments
object |
A NpdeObject object |
Value
A NpdeObject object updated with the results
Covariate diagnostic plots
Description
Boxplot of the selected variable versus categories of covariates
Usage
npde.plot.covariate(npdeObject, which.y="npd", ...)
Arguments
npdeObject |
|
which.y |
a string specifying the variable on the Y-axis (one of "yobs", "npde", "pd", "npd") |
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Details
For a categorical covariate, boxplots are produced for each category. Continous covariates are split into quantile (by default, first quartile (<Q1), interquartile range (Q1-Q3) and upper quartile (>Q3), but the number of categories can be set by using the ncat argument).
For each category, the median according to simulations under the model is shown (it can be suppressed by using the argument bands=FALSE)..
Value
a ggplot object or a list of ggplot objects (grobs)
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, F. Mentre F. Evaluation of different tests based on observations for external model evaluation of population analyses. Journal of Pharmacokinetics and Pharmacodynamics, 37:49-65, 2010.
See Also
npde, autonpde, set.plotoptions, npdeControl
Plot a NpdeData object
Description
Produces a spaghetti plot of the data
Usage
npde.plot.data(npdeObject, ...)
Arguments
npdeObject |
|
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Value
a ggplot object or a list of ggplot objects (grobs)
Diagnostic plots
Description
The default diagnostic plots produced after a call to npde or autonpde include a histogram of the distribution, a QQ-plot compared to the theoretical distribution, and scatterplots versus the independent variable and versus the population predictions from the model
Usage
npde.plot.default(npdeObject, ...)
Arguments
npdeObject |
|
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Details
By default, npd are used for the diagnostic plots. If an unknown argument to which (eg which="XXX") is given, this is changed to npd (with a warning message if verbose=TRUE or the verbose option in the option slot of the npdeObject is TRUE).
Value
a ggplot object or a list of ggplot objects (grobs)
Distribution plots of pd/npde
Description
Produces a plot of the cdistribution of a metric compared to their theoretical distribution. Three types of distribution plots are available: a histogram, a QQ-plot, or the empirical cdf.
Usage
npde.plot.dist(npdeObject, which="npd", dist.type="qqplot", ...)
Arguments
npdeObject |
|
which |
a string determining which metric to plot (one of "npde", "pd" or "npd"), defaults to "npd" |
dist.type |
string, one of "ecdf" (empirical cumulative density function), "hist" (histogram) or "qqplot" (QQ-plot of the empirical distribution versus the theoretical quantiles) to determine which type of plot (default is "qqplot") |
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Value
a ggplot object or a list of ggplot objects (grobs)
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
npde, autonpde, set.plotoptions
Plot of the probability that the observations are below the LOQ
Description
Plots the probability that the observations are below the LOQ along with the model predicted interval
Usage
npde.plot.loq(npdeObject,xaxis="x",nsim=200,...)
Arguments
npdeObject |
|
xaxis |
a string character, one of "x" (to plot P(Y<LOQ) versus the value of the independent predictor) or "ypred" (versus the value of the population predictions). Defaults to "x" |
nsim |
number of simulations to be used for the computation of the prediction interval |
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Value
a ggplot object or a list of ggplot objects (grobs)
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
npde, autonpde, set.plotoptions
Plots for pd and npde
Description
Plots for pd and npde
Usage
npde.plot.pd(npdeObject, ...)
npde.plot.npde(npdeObject, ...)
npde.plot.npd(npdeObject, ...)
Arguments
npdeObject |
|
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Value
a ggplot object or a list of ggplot objects (grobs)
Scatterplots and VPC
Description
Produces a scatterplot. Different types of scatterplots can be produced, with associated prediction bands (see details).
Usage
npde.plot.scatterplot(npdeObject, which.x="x", which.y="npd", ref.prof=NULL, ...)
Arguments
npdeObject |
|
which.x |
a string specifying the variable on the X-axis (one of "x", "pred", "cov") |
which.y |
a string specifying the variable on the Y-axis (one of "yobs", "npde", "pd", "npd"), defaults to "npd" |
ref.prof |
either a character string (one of "covariate" or "all"), or a named list specifying the characteristics of the reference profile (see details) |
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Details
VPC: obtained using which.x="x", which.y="yobs"
Scatterplots of npde/pd/npd can be obtained versus "x" (independent variable) or "pred" (population predictions from the model)
Scatterplots of npde/pd/npd/observations can be obtained versus covariates by setting the which.x argument to "cov" and selecting the appropriate which.y. The function will use the covariates in the which.cov element of the prefs slot. This can be overriden to cycle over all the covariates in the dataset by supplying the argument which.cov="all" in the call to the function.
Reference profile: a reference profile can be added to scatterplots of npd and npde versus the independent variable (see Comets et al. 2013)
If ref.prof="all" (and covsplit is FALSE), the reference plot will be computed over all subjects using the mean and SD of all simulated data in each bin (see documentation).
If ref.prof="covariate" and an additional argument covsplit is given (covsplit=TRUE), the reference plot will be adjusted for each covariate category over all the covariates in the which.cov element of the prefs slot (see npdeControl for details on the prefs slot of the npdeObject).
If ref.prof is given as a named list (eg list(ID=c(1,5)) or list(sex=0, dose=c(50,100)), where names should refer to columns in the data file (eg ID should be a column in the data)), the reference profile will be obtained by combining (in the first example above, the reference profile will be obtained using the simulated data for subjects 1 and 5, while in the second example it will be computed using the subjects with sex=0 given doses 50 or 100).
Value
a ggplot object or a list of ggplot objects (grobs)
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
E. Comets, T.H.T. Nguyen, and F. Mentré F. Additional features and graphs in the new npde library for R. 22th meeting of the Population Approach Group in Europe, Glasgow, United Kingdom, 2013.
See Also
npde, autonpde, set.plotoptions, npdeControl
Select plot for a NpdeObject object
Description
Select plot for a NpdeObject object
Usage
npde.plot.select(npdeObject,data=FALSE,ecdf=FALSE,qqplot=FALSE, histogram=FALSE,
x.scatter=FALSE,pred.scatter=FALSE,x.box=FALSE,pred.box=FALSE, cov.scatter=FALSE,
cov.x.scatter=FALSE, cov.pred.scatter=FALSE,cov.x.box=FALSE,cov.pred.box=FALSE,
cov.ecdf=FALSE, cov.hist=FALSE, cov.qqplot=FALSE, vpc=FALSE,...)
Arguments
npdeObject |
|
data |
boolean, whether to produce a plot of the data |
ecdf |
boolean, whether to produce a distribution plot of the empirical distribution function |
qqplot |
boolean, whether to produce a QQ-plot of the empirical distribution function |
histogram |
boolean, whether to produce a histogram of the metric |
x.scatter |
boolean, whether to produce a scatterplot of the metric as a function of X |
pred.scatter |
boolean, whether to produce a scatterplot of the metric as a function of predictions |
x.box |
boolean, whether to produce whisker plots of the metric as a function of X |
pred.box |
boolean, whether to produce whisker plots of the metric as a function of predictions |
cov.scatter |
boolean, whether to produce a scatterplot of the metric as a function of covariate(s) |
cov.x.scatter |
boolean, whether to produce a scatterplot of the metric as a function of X, split by covariate(s) |
cov.pred.scatter |
boolean, whether to produce a scatterplot of the metric as a function of predictions, split by covariate(s) |
cov.x.box |
boolean, whether to produce whisker plots of the metric as a function of X, split by covariate(s) |
cov.pred.box |
boolean, whether to produce whisker plots of the metric as a function of predictions, split by covariate(s) |
cov.ecdf |
boolean, whether to produce a distribution plot of the empirical distribution function, split by covariate(s) |
cov.hist |
boolean, whether to produce a distribution plot of the empirical distribution function, split by covariate(s) |
cov.qqplot |
boolean, whether to produce a distribution plot of the empirical distribution function, split by covariate(s) |
vpc |
boolean, whether to produce a VPC |
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Value
a ggplot object or a list of ggplot objects (grobs)
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
npde, autonpde, set.plotoptions
Plots split by covariate for a NpdeObject object
Description
Plots split by covariate for a NpdeObject object (equivalent to using covsplit=TRUE with the appropriate plot.type)
Usage
npde.plot.splitcov(npdeObject, which.plot="x", ...)
Arguments
npdeObject |
|
which.plot |
one of "x" (scatterplots of the metric versus X), "pred" (scatterplots of the metric versus predictions), "ecdf" (empirical distribution function), "hist" (histogram), "qqplot" |
... |
additional arguments to be passed on to the function, to control which metric (npde, pd, npd) is used or to override graphical parameters (see the PDF document for details, as well as |
Value
a ggplot object or a list of ggplot objects (grobs)
Save the results contained in a NpdeObject object to a file
Description
Save the results to a table on disk
Usage
npde.save(object, ...)
Arguments
object |
a NpdeObject object |
... |
optional arguments to replace options in object |
Details
The following options can be changed by passing the appropriate arguments: namsav (string giving the root name of the files, an extension .npde will be added), nameres (string giving the full name of the file)
Value
No return value, called for side effects
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F.Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
Set options for an NpdeObject
Description
Set, replace and check options for an NpdeObject
Usage
npdeControl(boolsave = TRUE, namsav = "output", type.graph = "eps",
verbose = FALSE, calc.npde = TRUE, calc.npd = TRUE, decorr.method = "cholesky",
cens.method = "omit", ties = TRUE, sample = FALSE)
check.control.options(opt)
replace.control.options(opt,...)
replace.control.options(opt, ...)
check.control.options(opt)
Arguments
boolsave |
whether to save the results (a file containing the numerical results and a file with the graphs) |
namsav |
the root name of the files to save to (the file with the results will be named ROOTNAME.npde and the graphs will be saved to ROOTNAME.format where format is given by the type.graph argument) |
type.graph |
type of graph to save to (one of "eps", "pdf", "jpeg", "png") |
verbose |
a boolean; if TRUE, a message is printed as the computation of the npde begins for each new subject |
calc.npde |
a boolean; TRUE to compute npde |
calc.npd |
a boolean; TRUE to compute npd |
decorr.method |
the method used to decorrelate simulated and observed data (see |
cens.method |
the method used to handle censored data (see |
ties |
if FALSE, a smoothing will be applied to prediction discrepancies to avoid ties |
sample |
if TRUE, the test on the pd will be performed after randomly sampling only pd per subject |
opt |
a list of control options to be checked |
... |
named parameters to be changed. The names will be compared to the names of the control variables and changed, with warnings issued for names that do not match. |
Value
A list of settings for the computation of pd/npde
Creates a NpdeData object
Description
This function is used to create a NpdeData object, representing a longitudinal data structure, and fill it with data from a dataframe or a file on disk
Usage
npdeData(name.data,header=TRUE,sep="",na.strings=c(".","NA"),name.group,
name.predictor, name.response, name.covariates,name.cens,name.miss,name.ipred,
units=list(x="",y="",covariates=c()), detect=TRUE,verbose=FALSE)
Arguments
name.data |
name of the file containing the observed data, or a dataframe containing the observed data |
header |
boolean indicating whether the file has a header (a header is mandatory if detect is TRUE) |
sep |
field separator (for files on disk) |
na.strings |
strings to be considered as indicating NA |
name.group |
name/number of the column in the observed data containing the patient ID (if missing and detect is TRUE, columns named id, subject or sujet (regardless of case) will be assumed to contain this information) |
name.predictor |
name/number of the column in the observed data containing the independent variable X (if missing and detect is TRUE, columns named xobs, time, dose, x, temps, tim (regardless of case) will be assumed to contain this information) |
name.response |
name/number of the column in the observed data containing the dependent variable Y (if missing and detect is TRUE, columns named yobs, response, resp, conc, concentration (regardless of case) will be assumed to contain this information) |
name.covariates |
name/number of the column(s) containing covariate information (optional) |
name.cens |
name/number of the column containing information about censored data (cens) (if missing and detect is TRUE, column with a name containing cens (regardless of case) will be assumed to contain this information) |
name.miss |
name/number of the column containing information about missing data (MDV) (if missing and detect is TRUE, column called mdv or miss (regardless of case) will be assumed to contain this information) |
name.ipred |
name/number of the column(s) with individual predictions (ipred) (if missing and detect is TRUE, column with a name containing ipred (regardless of case) will be assumed to contain this information) |
units |
a list with components x, y and cov (optional), specifying the units respectively for the predictor (x), the response (y), and the covariates (a vector of length equal to the number of covariates). Units will default to (-) if not given. |
detect |
a boolean controlling whether automatic recognition of columns in the dataset is on, defaults to TRUE |
verbose |
whether to print warning messages, defaults to FALSE (set to TRUE to check how data is being handled) |
Value
an object of class NpdeData
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentré. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
Examples
data(theopp)
x<-npdeData(theopp) # Automatic detection
print(x)
x<-npdeData(theopp,name.group="ID",name.predictor="Time",name.response="Conc",
name.covariates=c("Wt"),units=list(x="hr",y="mg/L",covariates="kg")) # Explicit
print(x)
Creates a NpdeSimData object
Description
This function is used to create a NpdeSimData object containing the simulated data corresponding to an NpdeData object
Usage
npdeSimData(npde.data, name.simdata, header=TRUE, sep="", na.strings=c("NA","."),
detect=FALSE, verbose=FALSE)
Arguments
npde.data |
a NpdeData object |
name.simdata |
name of the file containing the simulated data, or a dataframe containing it |
header |
boolean indicating whether the file has a header (a header is mandatory if detect is TRUE) |
sep |
field separator (for files on disk) |
na.strings |
strings to be considered as indicating NA |
detect |
a boolean controlling whether automatic recognition of columns in the dataset is on, defaults to FALSE if FALSE, the first 3 columns of the simulated data file will will be used as simulated id, predictor and response respectively if TRUE, the function will look for columns named respectively idsim, xsim and ysim (it will fail with an error message if these columns are not present in the simulated data) |
verbose |
whether to print warning messages, defaults to FALSE (set to TRUE to check how data is being handled) |
Value
an object of class NpdeSimData
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
See Also
Interactive menu to set the options for the npde() function
Description
Interactive menu to set the options for the npde() function
Usage
pdemenu()
Value
A list with the information needed to compute the pd/npde
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F. Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
Plots a NpdeData object
Description
Plots the data in a NpdeData object
Usage
## S3 method for class 'NpdeData'
plot(x, y, ...)
Arguments
x |
a NpdeData object |
y |
unused, here for compatibility with the base plot function |
... |
additional graphical parameters to be passed on to the plot |
Details
The default plot is a spaghetti plot of all the data, with a line joining the observations for each subject. If censored data is present, it is shown with a different symbol and colour.
Value
currently does not return anything, use plot(x, plot.type="data") on the npdeObject x (TODO; a ggplot object)
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F.Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
Examples
data(theopp)
x<-npdeData(theopp,name.group="ID",name.predictor="Time",name.response="Conc",
name.covariates=c("Wt"),units=list(x="hr",y="mg/L",covariates="kg"))
plot(x)
Plots a NpdeObject object
Description
Plots the data and diagnostic plots in a NpdeObject object
Usage
## S3 method for class 'NpdeObject'
plot(x, y, ...)
Arguments
x |
a NpdeObject object |
y |
unused, here for compatibility with the base plot function |
... |
additional graphical parameters, which when given will supersede graphical preferences stored in the object |
Details
The default plots are represented as a 2x2 array with distribution plots on the top row (histogram and QQ-plot), and scatterplots of npde versus independent variable and population predictions on the bottom row. The graph is plotted in a graphic device window, unless the result is stored in an object (eg myplot<-plot(x)) which can then be printed (eg using print(myplot)).
@references K. Brendel, E. Comets, C. Laffont, C. Laveille, and F.Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
Value
a ggplot object or a list of ggplot objects (grobs)
See Also
Examples
data(theopp)
data(simtheopp)
x<-autonpde(theopp,simtheopp,iid="ID",ix="Time", iy="Conc", boolsave=FALSE)
plot(x)
Plots a NpdeRes object
Description
Plots distribution and scatterplots for the npde in a NpdeRes object. Users are advised to use the plot() function on the NpdeObject object resulting from a call to npde() or autonpde() instead of trying to plot only the results element of this object.
Usage
## S3 method for class 'NpdeRes'
plot(x, y, ...)
Arguments
x |
a NpdeRes object |
Details
Four graphs are produced:
- a quantile-quantile plot
plot of the npde versus the corresponding quantiles of a normal distribution, with the line y=x overlayed.
- a histogram of the npde
the shape of the normal distribution is also shown
- two scatterplots of the npde
a plot of the npde versus the independent variable X and a plot of the npde versus the empirical mean of the predicted distribution; for these last two graphs, we plot the lines corresponding to y=0 and to the 5% and 95% critical value of the normal distribution delimiting a 90% prediction interval for the npde
Value
a ggplot object or a list of ggplot objects (grobs)
References
K. Brendel, E. Comets, C. Laffont, C. Laveille, and F.Mentre. Metrics for external model evaluation with an application to the population pharmacokinetics of gliclazide. Pharmaceutical Research, 23:2036–49, 2006.
See Also
Examples
data(theopp)
Prints objects from the npde package
Description
prints objects of classes NpdeData, NpdeSimData, NpdeRes and NpdeObject
Usage
## S3 method for class 'NpdeData'
print(x, nlines = 10, ...)
## S3 method for class 'NpdeRes'
print(x, nlines = 10, ...)
## S3 method for class 'NpdeObject'
print(x, nlines = 10, ...)
Arguments
x |
an object of class NpdeData, NpdeSimData, NpdeRes or NpdeObject |
nlines |
number of lines from the dataset to print |
... |
Additional arguments (ignored) |
Value
None
Read data into structures (internal)
Description
Creates an NpdeData object containing the observed data, either from disk or from a dataframe
Usage
read(object, dat, detect=TRUE, verbose=FALSE, ...)
## S4 method for signature 'NpdeData'
read(object, dat, detect = TRUE, verbose = FALSE, ...)
## S4 method for signature 'NpdeSimData'
read(object, dat, detect = FALSE, verbose = FALSE, ...)
Arguments
object |
an object |
dat |
a dataframe containing the data to be analysed |
detect |
a boolean; if TRUE, automatic recognition of names will be attempted to detect necessary items for a NpdeData, these include longitudinal data structure, missing data and censoring information for a NpdeSimData, the required columns should be called idsim, xsim, ysim, representing respectively simulated id, simulated predictor and simulated response |
verbose |
a boolean; messages are printed if verbose is TRUE (defaults to FALSE) |
... |
additional arguments for compatibility with generic |
Value
an object of class "NpdeData" or "NpdeSimData"
Replace graphical options
Description
This function is used to replace graph options (available in the prefs slot of the NpdeObject object) for plotting NpdeObject objects
Usage
replace.plotoptions(plot.opt,...)
Arguments
plot.opt |
a list of graphical preferences |
... |
names and values of the options to be replaced |
Details
See documentation for a list of available options. During replacement, invalid (including misspelled) options will raise warnings.
Value
an updated list of options for graphs
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
See Also
Set graphical preferences
Description
This function is used to set options for graphs
Usage
set.plotoptions(object)
## Default S3 method:
set.plotoptions(object)
## S3 method for class 'NpdeData'
set.plotoptions(object)
## S3 method for class 'NpdeObject'
set.plotoptions(object)
Arguments
object |
an object of class NpdeData or NpdeObject |
Details
See documentation for a list of available options.
Value
a list of options for graphs
Author(s)
Emmanuelle Comets <emmanuelle.comets@bichat.inserm.fr>
See Also
Displays npde objects
Description
Prints the structure of objects from the package
Usage
## S4 method for signature 'NpdeData'
show(object)
## S4 method for signature 'NpdeSimData'
show(object)
## S4 method for signature 'NpdeRes'
show(object)
## S4 method for signature 'NpdeObject'
show(object)
Arguments
object |
an object from the npde package (NpdeData, NpdeRes, NpdeObject) |
Contents of an object
Description
Prints the contents of an object
Usage
showall(object)
## S3 method for class 'NpdeRes'
showall(object)
## S3 method for class 'NpdeObject'
showall(object)
Arguments
object |
a NpdeData object |
Value
No return value, shows the object
Simulated data for the computation of normalised prediction distribution errors in the theophylline dataset
Description
The simtheopp dataset contains 100 simulations using the design of
dataset theopp. These simulations are used to compute npde.
The control file used to perform the simulations can be found in the
subdirectory 'doc' within the library npde.
Usage
simtheopp
Format
A data frame with 132000 rows and 3 variables This data frame contains the following columns:
- ID
an ordered factor with levels
1, ...,12identifying the subject on whom the observation was made. The ordering is first by simulation then by increasing time.- xsim
time since drug administration when the sample was drawn (hr).
- ysim
simulated theophylline concentration (mg/L).
Details
See theopp for a description of the original dataset.
The simulated data was obtained using the software NONMEM. A one-compartment model was fit to the data. An exponential interindividual variability was assumed for the three parameters (absorption rate constant ka, volume of distribution V and clearance CL) and a combined additive and proportional residual error model was usd. The estimated parameters were then used to simulate 100 datasets with the same structure as the original dataset. Thus, for each observation in the original dataset, the simulated dataset contains 100 simulations under the model used for the estimation.
This dataset is provided so that users can figure out what type of data is needed for the computation of prediction distribution errors. More information can be found in the User Guide distributed along with this package, which contains a run-through of the theophylline example.
Source
Boeckmann, A. J., Sheiner, L. B. and Beal, S. L. (1994), NONMEM Users Guide: Part V, NONMEM Project Group, University of California, San Francisco.
References
PDF documentation for npde 3.0: https://github.com/ecomets/npde30/blob/main/userguide_npde_3.0.pdf
See Also
Examples
data(simtheopp)
# Plotting the simulated data for subject 1 in the first simulation
plot(ysim[2:12]~xsim[2:12],data=simtheopp,xlab="Time after dose (hr)",
ylab="Theophylline concentration (mg/L)",type="l",
main="Example of simulated data for subject 1")
# Plotting a 90% prediction interval for the observations in theopp
# using the simulated data in simtheopp
# note : differences in doses between subjects are not taken into account
data(theopp)
xpl<-c(0,0.25,0.5,1,2,3.5,5,7,9,12,24)
xpl1<-list(c(0,0.1),c(0.2,0.4),c(0.5,0.65),c(0.9,1.2),c(1.9,2.2),c(3.4,4),
c(4.9,5.2),c(6.9,7.2),c(8.8,9.4),c(11.5,12.2),c(23.7,24.7))
ypl<-cbind(xpl=xpl,binf=xpl,median=xpl,bsup=xpl)
for(i in 1:(length(xpl))) {
vec<-simtheopp$ysim[simtheopp$xsim>=xpl1[[i]][1] &simtheopp$xsim<=xpl1[[i]][2]]
ypl[i,2:4]<-quantile(vec,c(0.05,0.5,0.95))
}
plot(Conc~Time,data=theopp,xlab="Time after dose (hr)",
ylab="Theophylline concentration (mg/L)")
lines(ypl[,1],ypl[,3],lwd=2)
lines(ypl[,1],ypl[,2],lty=2)
lines(ypl[,1],ypl[,4],lty=2)
Skewness
Description
Computes the skewness.
Usage
skewness(x)
Arguments
x |
a numeric vector containing the values whose skewness is to be computed. NA values are removed in the computation. |
Details
If N = \mathrm{length}(x), then the skewness of x
is defined as
N^{-1} \mathrm{sd}(x)^{-3} \sum_i (x_i -
\mathrm{mean}(x))^3.
Value
The skewness of x.
References
G. Snedecor, W. Cochran. Statistical Methods, Wiley-Blackwell, 1989
Examples
x <- rnorm(100)
skewness(x)
Subsetting a NpdeData object
Description
Return subset of data from a NpdeData object
Usage
## S3 method for class 'NpdeData'
subset(x, subset, ...)
## S3 method for class 'NpdeObject'
subset(x, subset, ...)
Arguments
x |
A NpdeData object |
subset |
logical expression indicating elements or rows to keep: missing values are taken as false. |
... |
Additional arguments (ignored) |
Value
a NpdeData object with a subset of the original data
Summary of a NpdeData object
Description
Extracts elements from a NpdeData object
Usage
## S3 method for class 'NpdeData'
summary(object, print = TRUE, ...)
## S3 method for class 'NpdeRes'
summary(object, print = TRUE, ...)
## S3 method for class 'NpdeObject'
summary(object, ...)
Arguments
object |
A NpdeData object |
print |
whether to print to data to stdev |
... |
Additional arguments (ignored) |
Value
A list with elements N (nb of subjects), data (dataframe containing the data), ntot.obs (total nb of observations), nind.obs (nb of observations per subject)
Pharmacokinetics of theophylline
Description
The theopp data frame has 132 rows and 5 columns of data from an
experiment on the pharmacokinetics of theophylline.
Usage
theopp
Format
This data frame contains the following columns:
- ID
an ordered factor with levels
1, ...,12identifying the subject on whom the observation was made. The ordering is by Time at which the observation was made.- Dose
dose of theophylline administered orally to the subject (mg/kg).
- Time
-
time since drug administration when the sample was drawn (hr).
- Conc
theophylline concentration in the sample (mg/L).
- Wt
-
weight of the subject (kg).
Details
Boeckmann, Sheiner and Beal (1994) report data from a study by Dr. Robert Upton of the kinetics of the anti-asthmatic drug theophylline. Twelve subjects were given oral doses of theophylline then serum concentrations were measured at 11 time points over the next 25 hours.
These data are analyzed in Davidian and Giltinan (1995) and Pinheiro and Bates (2000) using a two-compartment open pharmacokinetic model.
These data are also available in the library datasets under the name
Theoph in a slightly modified format and including the data at time
0. Here, we use the file in the format provided in the NONMEM
installation path (see the User Guide for that software for details).
Source
Boeckmann, A. J., Sheiner, L. B. and Beal, S. L. (1994), NONMEM Users Guide: Part V, NONMEM Project Group, University of California, San Francisco.
Davidian, M. and Giltinan, D. M. (1995) Nonlinear Models for Repeated Measurement Data, Chapman & Hall (section 5.5, p. 145 and section 6.6, p. 176)
Pinheiro, J. C. and Bates, D. M. (2000) Mixed-effects Models in S and S-PLUS, Springer (Appendix A.29)
References
PDF documentation for npde 3.0: https://github.com/ecomets/npde30/blob/main/userguide_npde_3.0.pdf
Examples
data(theopp)
#Plotting the theophylline data
plot(Conc~Time,data=theopp,xlab="Time after dose (hr)",
ylab="Theophylline concentration (mg/L)")
Simulated HIV viral loads in HIV patients
Description
This is simulated data, based on real data obtained in a phase II clinical trial supported by the French Agency for AIDS Research, the COPHAR 3-ANRS 134 trial (Goujard et al., 2010). The original study included 35 patients, who received a once daily dose containing atazanavir (300 mg), ritonavir (100 mg), tenofovir disoproxil (245 mg) and emtricitabine (200 mg) during 24 weeks. Viral loads were measured 6 times over a treatment period of 24 weeks (day 0, 28, 56, 84, 112, 168).
Usage
virload
Format
This data frame contains the following columns:
- ID
an ordered factor with levels
1, ...,50identifying the subject on whom the observation was made. The ordering is by Time at which the observation was made.- Time
time since the beginning of the study (days)
- Log_VL
logarithm (base 10) of the viral load (copies/L)
- cens
indicator variable (cens=1 for censored data, cens=0 for observed data)
- ipred
individual predictions
Details
The datasets were generated in a simulation study designed to evaluate the new method proposed to handle BQL data (Nguyen et al., 2011). Data was simulated using a simple bi-exponential HIV dynamic model describing the two-phase decline of viral load during anti-retroviral treatment.
The virload data frame has 300 rows and 4 columns of data. The dataset was then censored at two different LOQ levels (LOQ=20 or 50~copies/mL) to generate two datasets containing different proportions of BQL data, creating the data frames virload20 andvirload50 respectively
The file simvirload contains 500 simulations under the same model. A full version of the simulated data with 1000 simulations can be downloaded from the github for npde3.0: https://github.com/ecomets/npde30/blob/main/keep/data/simvirload.tab
Source
Goujard, C., Barrail-Train, A., Duval, X., Nembot, G., Panhard, X., Savic, R., Descamps, D., Vrijens, B., Taburet, A., Mentre, F., and the ANRS 134 study group (2010). Virological response to atazanavir, ritonavir and tenofovir/emtricitabine: relation to individual pharmacokinetic parameters and adherence measured by medication events monitoring system (MEMS) in naive HIV-infected patients (ANRS134 trial). International AIDS Society 2010, Abstr WEPE0094.
References
PDF documentation for npde 3.0: https://github.com/ecomets/npde30/blob/main/userguide_npde_3.0.pdf
Examples
data(virload)
str(virload)
data(virload50)
# Plotting the data
plot(Log_VL~Time,data=virload,xlab="Time (d)",ylab="Viral loads, base 10 log-scale (cp/mL)")
plot(Log_VL~Time,data=virload50,xlab="Time (d)",ylab="Viral loads, base 10 log-scale (cp/mL)")
Pharmacokinetics of warfarin
Description
The warfarin data frame has 251 rows and 8 columns of data containing
data on the pharmacokinetics of warfarin, an anticoagulant drug used in the
prevention of thrombosis and thromboembolism.
Usage
warfarin
Format
This data frame contains the following columns:
- id
an integer identifying the subject on whom the observation was made
- time
time since drug administration when the sample was drawn (hr)
- amt
total dose received by the subject (mg)
- dv
warfarin concentration in the sample (mg/L)
- dvid
observation type (1 for all observations)
- wt
weight of the subject (kg)
- sex
subject gender (0=female, 1=male)
- age
age of the subject (yr)
Details
The dataset is the PK part of a larger dataset including both warfarin concentrations and prothrombin complex activity (PCA), which measures the decreased coagulation activity resulting from the inhibition of vitamin K recycling, the mechanism of action of warfarin. It contains the concentrations measured in 32 healthy subjects after a single oral dose of warfarin sodium (1.5 mg/kg of body weight). The subjects in the study were sampled at different times over a period of up to 120 hours.
The data is distributed with the Monolix software as a demo for PK/PD modelling. The data has been slightly reformated for R, removing the line at time=0 and filling the amt column with the dose for each subject, following the output of simulx which was used to simulate data from two alternative models to fit this dataset.
Two datasets containing simulated data are associated with the warfarin data. For
each dataset, 1000 simulations of the original data were performed for the computation of npde.
The package contains only the simulated data simwarfarinCov because of size constraints. simwarfarinBase can be downloaded from
the github for npde3.0: https://github.com/ecomets/npde30/blob/main/keep/data/simwarfarinBase.tab
- simwarfarinBase
the data in this dataset was simulated according to a base model without covariates: the PK model was a two-compartment model, with first-order absorption and a time-delay. Interindividual variability was modelled as log-normal distributions for parameters Tlag, ka, Cl and V1, and the error model was a combined error model. The parameters were estimated by Monolix.
- simwarfarinCov
the data in this dataset was simulated according to a model including several covariates: an age (centered on 30 yr) effect on Cl, a weight (centered on 70 kg) effect on Cl and V1, and a gender effect on V1. The covariate model was built in Monolix.
Source
O’Reilly (1968). Studies on coumarin anticoagulant drugs. Initiation of warfarin therapy without a loading dose. Circulation 1968, 38:169-177.
References
PDF documentation for npde 3.0: https://github.com/ecomets/npde30/blob/main/userguide_npde_3.0.pdf
Examples
data(warfarin)
#Plotting the warfarin PK data
plot(dv~time,data=warfarin,xlab="Time after dose (hr)",
ylab="Warfarin concentration (mg/L)")