Merge branch 'nlmixr'

1 files changed, 222 insertions, 0 deletions

diff --git a/man/nlmixr.mmkin.Rd b/man/nlmixr.mmkin.Rd
new file mode 100644
index 00000000..f9349727
--- /dev/null
+++ b/man/nlmixr.mmkin.Rd
@@ -0,0 +1,222 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/nlmixr.R
+\name{nlmixr.mmkin}
+\alias{nlmixr.mmkin}
+\alias{print.nlmixr.mmkin}
+\alias{nlmixr_model}
+\alias{nlmixr_data}
+\title{Fit nonlinear mixed models using nlmixr}
+\usage{
+\method{nlmixr}{mmkin}(
+  object,
+  data = NULL,
+  est = NULL,
+  control = list(),
+  table = tableControl(),
+  error_model = object[[1]]$err_mod,
+  test_log_parms = TRUE,
+  conf.level = 0.6,
+  degparms_start = "auto",
+  eta_start = "auto",
+  ...,
+  save = NULL,
+  envir = parent.frame()
+)
+
+\method{print}{nlmixr.mmkin}(x, digits = max(3, getOption("digits") - 3), ...)
+
+nlmixr_model(
+  object,
+  est = c("saem", "focei"),
+  degparms_start = "auto",
+  eta_start = "auto",
+  test_log_parms = TRUE,
+  conf.level = 0.6,
+  error_model = object[[1]]$err_mod,
+  add_attributes = FALSE
+)
+
+nlmixr_data(object, ...)
+}
+\arguments{
+\item{object}{An \link{mmkin} row object containing several fits of the same
+\link{mkinmod} model to different datasets}
+
+\item{data}{Not used, as the data are extracted from the mmkin row object}
+
+\item{est}{Estimation method passed to \link[nlmixr:nlmixr]{nlmixr::nlmixr}}
+
+\item{control}{Passed to \link[nlmixr:nlmixr]{nlmixr::nlmixr}}
+
+\item{table}{Passed to \link[nlmixr:nlmixr]{nlmixr::nlmixr}}
+
+\item{error_model}{Optional argument to override the error model which is
+being set based on the error model used in the mmkin row object.}
+
+\item{test_log_parms}{If TRUE, an attempt is made to use more robust starting
+values for population parameters fitted as log parameters in mkin (like
+rate constants) by only considering rate constants that pass the t-test
+when calculating mean degradation parameters using \link{mean_degparms}.}
+
+\item{conf.level}{Possibility to adjust the required confidence level
+for parameter that are tested if requested by 'test_log_parms'.}
+
+\item{degparms_start}{Parameter values given as a named numeric vector will
+be used to override the starting values obtained from the 'mmkin' object.}
+
+\item{eta_start}{Standard deviations on the transformed scale given as a
+named numeric vector will be used to override the starting values obtained
+from the 'mmkin' object.}
+
+\item{\dots}{Passed to \link{nlmixr_model}}
+
+\item{save}{Passed to \link[nlmixr:nlmixr]{nlmixr::nlmixr}}
+
+\item{envir}{Passed to \link[nlmixr:nlmixr]{nlmixr::nlmixr}}
+
+\item{x}{An nlmixr.mmkin object to print}
+
+\item{digits}{Number of digits to use for printing}
+
+\item{add_attributes}{Should the starting values used for degradation model
+parameters and their distribution and for the error model parameters
+be returned as attributes?}
+}
+\value{
+An S3 object of class 'nlmixr.mmkin', containing the fitted
+\link[nlmixr:nlmixr]{nlmixr::nlmixr} object as a list component named 'nm'. The
+object also inherits from 'mixed.mmkin'.
+
+An function defining a model suitable for fitting with \link[nlmixr:nlmixr]{nlmixr::nlmixr}.
+
+An dataframe suitable for use with \link[nlmixr:nlmixr]{nlmixr::nlmixr}
+}
+\description{
+This function uses \code{\link[nlmixr:nlmixr]{nlmixr::nlmixr()}} as a backend for fitting nonlinear mixed
+effects models created from \link{mmkin} row objects using the Stochastic Approximation
+Expectation Maximisation algorithm (SAEM) or First Order Conditional
+Estimation with Interaction (FOCEI).
+}
+\details{
+An mmkin row object is essentially a list of mkinfit objects that have been
+obtained by fitting the same model to a list of datasets using \link{mkinfit}.
+}
+\examples{
+\dontrun{
+ds <- lapply(experimental_data_for_UBA_2019[6:10],
+ function(x) subset(x$data[c("name", "time", "value")]))
+names(ds) <- paste("Dataset", 6:10)
+
+f_mmkin_parent <- mmkin(c("SFO", "FOMC", "DFOP", "HS"), ds, quiet = TRUE, cores = 1)
+f_mmkin_parent_tc <- mmkin(c("SFO", "FOMC", "DFOP"), ds, error_model = "tc",
+  cores = 1, quiet = TRUE)
+
+library(nlmixr)
+f_nlmixr_sfo_saem <- nlmixr(f_mmkin_parent["SFO", ], est = "saem",
+  control = saemControl(print = 0))
+f_nlmixr_sfo_focei <- nlmixr(f_mmkin_parent["SFO", ], est = "focei",
+  control = foceiControl(print = 0))
+
+f_nlmixr_fomc_saem <- nlmixr(f_mmkin_parent["FOMC", ], est = "saem",
+  control = saemControl(print = 0))
+f_nlmixr_fomc_focei <- nlmixr(f_mmkin_parent["FOMC", ], est = "focei",
+  control = foceiControl(print = 0))
+
+f_nlmixr_dfop_saem <- nlmixr(f_mmkin_parent["DFOP", ], est = "saem",
+  control = saemControl(print = 0))
+f_nlmixr_dfop_focei <- nlmixr(f_mmkin_parent["DFOP", ], est = "focei",
+  control = foceiControl(print = 0))
+
+f_nlmixr_hs_saem <- nlmixr(f_mmkin_parent["HS", ], est = "saem",
+  control = saemControl(print = 0))
+f_nlmixr_hs_focei <- nlmixr(f_mmkin_parent["HS", ], est = "focei",
+  control = foceiControl(print = 0))
+
+f_nlmixr_fomc_saem_tc <- nlmixr(f_mmkin_parent_tc["FOMC", ], est = "saem",
+  control = saemControl(print = 0))
+f_nlmixr_fomc_focei_tc <- nlmixr(f_mmkin_parent_tc["FOMC", ], est = "focei",
+  control = foceiControl(print = 0))
+
+AIC(
+  f_nlmixr_sfo_saem$nm, f_nlmixr_sfo_focei$nm,
+  f_nlmixr_fomc_saem$nm, f_nlmixr_fomc_focei$nm,
+  f_nlmixr_dfop_saem$nm, f_nlmixr_dfop_focei$nm,
+  f_nlmixr_hs_saem$nm, f_nlmixr_hs_focei$nm,
+  f_nlmixr_fomc_saem_tc$nm, f_nlmixr_fomc_focei_tc$nm)
+
+AIC(nlme(f_mmkin_parent["FOMC", ]))
+AIC(nlme(f_mmkin_parent["HS", ]))
+
+# The FOCEI fit of FOMC with constant variance or the tc error model is best
+plot(f_nlmixr_fomc_saem_tc)
+
+sfo_sfo <- mkinmod(parent = mkinsub("SFO", "A1"),
+  A1 = mkinsub("SFO"), quiet = TRUE)
+fomc_sfo <- mkinmod(parent = mkinsub("FOMC", "A1"),
+  A1 = mkinsub("SFO"), quiet = TRUE)
+dfop_sfo <- mkinmod(parent = mkinsub("DFOP", "A1"),
+  A1 = mkinsub("SFO"), quiet = TRUE)
+
+f_mmkin_const <- mmkin(list(
+    "SFO-SFO" = sfo_sfo, "FOMC-SFO" = fomc_sfo, "DFOP-SFO" = dfop_sfo),
+  ds, quiet = TRUE, error_model = "const")
+f_mmkin_obs <- mmkin(list(
+    "SFO-SFO" = sfo_sfo, "FOMC-SFO" = fomc_sfo, "DFOP-SFO" = dfop_sfo),
+  ds, quiet = TRUE, error_model = "obs")
+f_mmkin_tc <- mmkin(list(
+    "SFO-SFO" = sfo_sfo, "FOMC-SFO" = fomc_sfo, "DFOP-SFO" = dfop_sfo),
+  ds, quiet = TRUE, error_model = "tc")
+
+nlmixr_model(f_mmkin_const["SFO-SFO", ])
+
+# A single constant variance is currently only possible with est = 'focei' in nlmixr
+f_nlmixr_sfo_sfo_focei_const <- nlmixr(f_mmkin_const["SFO-SFO", ], est = "focei")
+f_nlmixr_fomc_sfo_focei_const <- nlmixr(f_mmkin_const["FOMC-SFO", ], est = "focei")
+f_nlmixr_dfop_sfo_focei_const <- nlmixr(f_mmkin_const["DFOP-SFO", ], est = "focei")
+
+# Variance by variable is supported by 'saem' and 'focei'
+f_nlmixr_fomc_sfo_saem_obs <- nlmixr(f_mmkin_obs["FOMC-SFO", ], est = "saem")
+f_nlmixr_fomc_sfo_focei_obs <- nlmixr(f_mmkin_obs["FOMC-SFO", ], est = "focei")
+f_nlmixr_dfop_sfo_saem_obs <- nlmixr(f_mmkin_obs["DFOP-SFO", ], est = "saem")
+f_nlmixr_dfop_sfo_focei_obs <- nlmixr(f_mmkin_obs["DFOP-SFO", ], est = "focei")
+
+# Identical two-component error for all variables is only possible with
+# est = 'focei' in nlmixr
+f_nlmixr_fomc_sfo_focei_tc <- nlmixr(f_mmkin_tc["FOMC-SFO", ], est = "focei")
+f_nlmixr_dfop_sfo_focei_tc <- nlmixr(f_mmkin_tc["DFOP-SFO", ], est = "focei")
+
+# Two-component error by variable is possible with both estimation methods
+# Variance by variable is supported by 'saem' and 'focei'
+f_nlmixr_fomc_sfo_saem_obs_tc <- nlmixr(f_mmkin_tc["FOMC-SFO", ], est = "saem",
+  error_model = "obs_tc")
+f_nlmixr_fomc_sfo_focei_obs_tc <- nlmixr(f_mmkin_tc["FOMC-SFO", ], est = "focei",
+  error_model = "obs_tc")
+f_nlmixr_dfop_sfo_saem_obs_tc <- nlmixr(f_mmkin_tc["DFOP-SFO", ], est = "saem",
+  error_model = "obs_tc")
+f_nlmixr_dfop_sfo_focei_obs_tc <- nlmixr(f_mmkin_tc["DFOP-SFO", ], est = "focei",
+  error_model = "obs_tc")
+
+AIC(
+  f_nlmixr_sfo_sfo_focei_const$nm,
+  f_nlmixr_fomc_sfo_focei_const$nm,
+  f_nlmixr_dfop_sfo_focei_const$nm,
+  f_nlmixr_fomc_sfo_saem_obs$nm,
+  f_nlmixr_fomc_sfo_focei_obs$nm,
+  f_nlmixr_dfop_sfo_saem_obs$nm,
+  f_nlmixr_dfop_sfo_focei_obs$nm,
+  f_nlmixr_fomc_sfo_focei_tc$nm,
+  f_nlmixr_dfop_sfo_focei_tc$nm,
+  f_nlmixr_fomc_sfo_saem_obs_tc$nm,
+  f_nlmixr_fomc_sfo_focei_obs_tc$nm,
+  f_nlmixr_dfop_sfo_saem_obs_tc$nm,
+  f_nlmixr_dfop_sfo_focei_obs_tc$nm
+)
+# Currently, FOMC-SFO with two-component error by variable fitted by focei gives the
+# lowest AIC
+plot(f_nlmixr_fomc_sfo_focei_obs_tc)
+summary(f_nlmixr_fomc_sfo_focei_obs_tc)
+}
+}
+\seealso{
+\link{summary.nlmixr.mmkin} \link{plot.mixed.mmkin}
+}