Support covariates in endpoints()

6 files changed, 43 insertions, 15 deletions

diff --git a/man/endpoints.Rd b/man/endpoints.Rd
index e3663aec..0df3616c 100644
--- a/man/endpoints.Rd
+++ b/man/endpoints.Rd
@@ -5,13 +5,20 @@
 \title{Function to calculate endpoints for further use from kinetic models fitted
 with mkinfit}
 \usage{
-endpoints(fit)
+endpoints(fit, covariates = NULL, covariate_quantile = 0.5)
 }
 \arguments{
 \item{fit}{An object of class \link{mkinfit}, \link{nlme.mmkin} or \link{saem.mmkin}, or
 another object that has list components mkinmod containing an \link{mkinmod}
 degradation model, and two numeric vectors, bparms.optim and bparms.fixed,
 that contain parameter values for that model.}
+
+\item{covariates}{Numeric vector with covariate values for all variables in
+any covariate models in the object. If given, it overrides 'covariate_quantile'.}
+
+\item{covariate_quantile}{This argument only has an effect if the fitted
+object has covariate models. If so, the default is to show endpoints
+for the median of the covariate values (50th percentile).}
 }
 \value{
 A list with a matrix of dissipation times named distimes, and, if
diff --git a/man/mkinfit.Rd b/man/mkinfit.Rd
index b5b24449..f96b4d22 100644
--- a/man/mkinfit.Rd
+++ b/man/mkinfit.Rd
@@ -23,8 +23,8 @@ mkinfit(
   atol = 1e-08,
   rtol = 1e-10,
   error_model = c("const", "obs", "tc"),
-  error_model_algorithm = c("auto", "d_3", "direct", "twostep", "threestep",
-    "fourstep", "IRLS", "OLS"),
+  error_model_algorithm = c("auto", "d_3", "direct", "twostep", "threestep", "fourstep",
+    "IRLS", "OLS"),
   reweight.tol = 1e-08,
   reweight.max.iter = 10,
   trace_parms = FALSE,
diff --git a/man/parms.Rd b/man/parms.Rd
index 5c0e8895..b1551374 100644
--- a/man/parms.Rd
+++ b/man/parms.Rd
@@ -1,10 +1,11 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/parms.R
+% Please edit documentation in R/parms.R, R/saem.R
 \name{parms}
 \alias{parms}
 \alias{parms.mkinfit}
 \alias{parms.mmkin}
 \alias{parms.multistart}
+\alias{parms.saem.mmkin}
 \title{Extract model parameters}
 \usage{
 parms(object, ...)
@@ -14,6 +15,8 @@ parms(object, ...)
 \method{parms}{mmkin}(object, transformed = FALSE, errparms = TRUE, ...)
 
 \method{parms}{multistart}(object, exclude_failed = TRUE, ...)
+
+\method{parms}{saem.mmkin}(object, ci = FALSE, covariates = NULL, ...)
 }
 \arguments{
 \item{object}{A fitted model object.}
@@ -28,6 +31,14 @@ in addition to the degradation parameters?}
 
 \item{exclude_failed}{For \link{multistart} objects, should rows for failed fits
 be removed from the returned parameter matrix?}
+
+\item{ci}{Should a matrix with estimates and confidence interval boundaries
+be returned? If FALSE (default), a vector of estimates is returned if no
+covariates are given, otherwise a matrix of estimates is returned, with
+each column corresponding to a row of the data frame holding the covariates}
+
+\item{covariates}{A data frame holding covariate values for which to
+return parameter values. Only has an effect if 'ci' is FALSE.}
 }
 \value{
 Depending on the object, a numeric vector of fitted model parameters,
diff --git a/man/plot.mixed.mmkin.Rd b/man/plot.mixed.mmkin.Rd
index 9c4474ff..1e264db3 100644
--- a/man/plot.mixed.mmkin.Rd
+++ b/man/plot.mixed.mmkin.Rd
@@ -9,10 +9,12 @@
   i = 1:ncol(x$mmkin),
   obs_vars = names(x$mkinmod$map),
   standardized = TRUE,
+  covariates = NULL,
+  covariate_quantiles = c(0.5, 0.05, 0.95),
   xlab = "Time",
   xlim = range(x$data$time),
   resplot = c("predicted", "time"),
-  pop_curve = "auto",
+  pop_curves = "auto",
   pred_over = NULL,
   test_log_parms = FALSE,
   conf.level = 0.6,
@@ -43,6 +45,16 @@ variables in the model.}
 \item{standardized}{Should the residuals be standardized? Only takes effect if
 \code{resplot = "time"}.}
 
+\item{covariates}{Data frame with covariate values for all variables in
+any covariate models in the object. If given, it overrides 'covariate_quantiles'.
+Each line in the data frame will result in a line drawn for the population.
+Rownames are used in the legend to label the lines.}
+
+\item{covariate_quantiles}{This argument only has an effect if the fitted
+object has covariate models. If so, the default is to show three population
+curves, for the 5th percentile, the 50th percentile and the 95th percentile
+of the covariate values used for fitting the model.}
+
 \item{xlab}{Label for the x axis.}
 
 \item{xlim}{Plot range in x direction.}
@@ -50,9 +62,10 @@ variables in the model.}
 \item{resplot}{Should the residuals plotted against time or against
 predicted values?}
 
-\item{pop_curve}{Per default, a population curve is drawn in case
+\item{pop_curves}{Per default, one population curve is drawn in case
 population parameters are fitted by the model, e.g. for saem objects.
-In case there is a covariate model, no population curve is currently shown.}
+In case there is a covariate model, the behaviour depends on the value
+of 'covariates'}
 
 \item{pred_over}{Named list of alternative predictions as obtained
 from \link{mkinpredict} with a compatible \link{mkinmod}.}
@@ -96,6 +109,9 @@ The function is called for its side effect.
 \description{
 Plot predictions from a fitted nonlinear mixed model obtained via an mmkin row object
 }
+\note{
+Covariate models are currently only supported for saem.mmkin objects.
+}
 \examples{
 ds <- lapply(experimental_data_for_UBA_2019[6:10],
  function(x) x$data[c("name", "time", "value")])
diff --git a/man/saem.Rd b/man/saem.Rd
index 89647ff4..fd19fe59 100644
--- a/man/saem.Rd
+++ b/man/saem.Rd
@@ -6,7 +6,6 @@
 \alias{print.saem.mmkin}
 \alias{saemix_model}
 \alias{saemix_data}
-\alias{parms.saem.mmkin}
 \title{Fit nonlinear mixed models with SAEM}
 \usage{
 saem(object, ...)
@@ -54,8 +53,6 @@ saemix_model(
 )
 
 saemix_data(object, covariates = NULL, verbose = FALSE, ...)
-
-\method{parms}{saem.mmkin}(object, ci = FALSE, ...)
 }
 \arguments{
 \item{object}{An \link{mmkin} row object containing several fits of the same
@@ -124,9 +121,6 @@ and the end of the optimisation process?}
 \item{x}{An saem.mmkin object to print}
 
 \item{digits}{Number of digits to use for printing}
-
-\item{ci}{Should a matrix with estimates and confidence interval boundaries
-be returned? If FALSE (default), a vector of estimates is returned.}
 }
 \value{
 An S3 object of class 'saem.mmkin', containing the fitted
diff --git a/man/set_nd_nq.Rd b/man/set_nd_nq.Rd
index 796c27a2..87a3fae1 100644
--- a/man/set_nd_nq.Rd
+++ b/man/set_nd_nq.Rd
@@ -54,9 +54,9 @@ it automates the proposal of Boesten et al (2015).
 }
 \section{Functions}{
 \itemize{
-\item \code{set_nd_nq_focus}: Set non-detects in residue time series according to FOCUS rules
-}}
+\item \code{set_nd_nq_focus()}: Set non-detects in residue time series according to FOCUS rules
 
+}}
 \examples{
 # FOCUS (2014) p. 75/76 and 131/132
 parent_1 <- c(.12, .09, .05, .03, "nd", "nd", "nd", "nd", "nd", "nd")