From 7777ff3b019e54364947ff393e2dab782d7cfe3c Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Fri, 10 Apr 2020 08:26:44 +0200 Subject: Improve nlme function docs --- .travis.yml | 2 +- R/nlme.R | 67 ++++++++++++----------- docs/404.html | 2 +- docs/articles/index.html | 2 +- docs/authors.html | 2 +- docs/index.html | 2 +- docs/news/index.html | 2 +- docs/reference/endpoints.html | 2 +- docs/reference/index.html | 4 +- docs/reference/mkinds.html | 2 +- docs/reference/mmkin.html | 14 +++-- docs/reference/nlme.html | 114 ++++++++++++++++++++++++++++++++++----- docs/reference/plot.mmkin.html | 2 +- docs/reference/print.mkinds.html | 2 +- man/nlme.Rd | 18 +++---- 15 files changed, 162 insertions(+), 75 deletions(-) diff --git a/.travis.yml b/.travis.yml index 172d0236..0d180f7e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,7 +7,7 @@ addons: apt: packages: - gcc -github_packages: +r_github_packages: - r-lib/covr script: - | diff --git a/R/nlme.R b/R/nlme.R index b17fe15a..79e4e9c1 100644 --- a/R/nlme.R +++ b/R/nlme.R @@ -1,14 +1,12 @@ #' Estimation of parameter distributions from mmkin row objects #' -#' This function sets up and attempts to fit a mixed effects model to +#' These functions facilitate setting up a nonlinear mixed effects model for #' an mmkin row object. 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. #' #' @param object An mmkin row object containing several fits of the same model to different datasets #' @import nlme -#' @importFrom purrr map_dfr -#' @return A named vector containing mean values of the fitted degradation model parameters #' @rdname nlme #' @examples #' sampling_times = c(0, 1, 3, 7, 14, 28, 60, 90, 120) @@ -45,7 +43,7 @@ #' summary(m_nlme) #' #' \dontrun{ -#' Test on some real data +#' # Test on some real data #' ds_2 <- lapply(experimental_data_for_UBA_2019[6:10], #' function(x) x$data[c("name", "time", "value")]) #' m_sfo_sfo <- mkinmod(parent = mkinsub("SFO", "A1"), @@ -113,36 +111,7 @@ #' #' anova(f_nlme_fomc_sfo, f_nlme_sfo_sfo) #' } -#' @export -mean_degparms <- function(object) { - if (nrow(object) > 1) stop("Only row objects allowed") - p_mat_start_trans <- sapply(object, parms, transformed = TRUE) - mean_degparm_names <- setdiff(rownames(p_mat_start_trans), names(object[[1]]$errparms)) - res <- apply(p_mat_start_trans[mean_degparm_names, ], 1, mean) - return(res) -} - -#' @rdname nlme -#' @importFrom purrr map_dfr -#' @return A groupedData data object -#' @export -nlme_data <- function(object) { - if (nrow(object) > 1) stop("Only row objects allowed") - ds_names <- colnames(object) - - ds_list <- lapply(object, function(x) x$data[c("time", "variable", "observed")]) - names(ds_list) <- ds_names - ds_nlme <- purrr::map_dfr(ds_list, function(x) x, .id = "ds") - ds_nlme$variable <- as.character(ds_nlme$variable) - ds_nlme_renamed <- data.frame(ds = ds_nlme$ds, name = ds_nlme$variable, - time = ds_nlme$time, value = ds_nlme$observed, - stringsAsFactors = FALSE) - ds_nlme_grouped <- groupedData(value ~ time | ds, ds_nlme_renamed) - return(ds_nlme_grouped) -} - -#' @rdname nlme -#' @return A function that can be used with nlme +#' @return A function that can be used with \code{link{nlme}} #' @export nlme_function <- function(object) { if (nrow(object) > 1) stop("Only row objects allowed") @@ -211,3 +180,33 @@ nlme_function <- function(object) { model_function <- as.function(c(model_function_alist, model_function_body)) return(model_function) } + +#' @rdname nlme +#' @return A named vector containing mean values of the fitted degradation model parameters +#' @export +mean_degparms <- function(object) { + if (nrow(object) > 1) stop("Only row objects allowed") + degparm_mat_trans <- sapply(object, parms, transformed = TRUE) + mean_degparm_names <- setdiff(rownames(degparm_mat_trans), names(object[[1]]$errparms)) + res <- apply(degparm_mat_trans[mean_degparm_names, ], 1, mean) + return(res) +} + +#' @rdname nlme +#' @importFrom purrr map_dfr +#' @return A \code{\link{groupedData}} object +#' @export +nlme_data <- function(object) { + if (nrow(object) > 1) stop("Only row objects allowed") + ds_names <- colnames(object) + + ds_list <- lapply(object, function(x) x$data[c("time", "variable", "observed")]) + names(ds_list) <- ds_names + ds_nlme <- purrr::map_dfr(ds_list, function(x) x, .id = "ds") + ds_nlme$variable <- as.character(ds_nlme$variable) + ds_nlme_renamed <- data.frame(ds = ds_nlme$ds, name = ds_nlme$variable, + time = ds_nlme$time, value = ds_nlme$observed, + stringsAsFactors = FALSE) + ds_nlme_grouped <- groupedData(value ~ time | ds, ds_nlme_renamed) + return(ds_nlme_grouped) +} diff --git a/docs/404.html b/docs/404.html index 3658a137..dc3c3c18 100644 --- a/docs/404.html +++ b/docs/404.html @@ -67,7 +67,7 @@ mkin - 0.9.49.9 + 0.9.49.10 diff --git a/docs/articles/index.html b/docs/articles/index.html index 3e181a2c..4a5087df 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -67,7 +67,7 @@ mkin - 0.9.49.9 + 0.9.49.10 diff --git a/docs/authors.html b/docs/authors.html index 2bb2557a..20c040f9 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -67,7 +67,7 @@ mkin - 0.9.49.9 + 0.9.49.10 diff --git a/docs/index.html b/docs/index.html index fe334eb8..7cf11e5c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -37,7 +37,7 @@ mkin - 0.9.49.9 + 0.9.49.10 diff --git a/docs/news/index.html b/docs/news/index.html index cb5e6df3..c8d7ce3d 100644 --- a/docs/news/index.html +++ b/docs/news/index.html @@ -67,7 +67,7 @@ mkin - 0.9.49.9 + 0.9.49.10 diff --git a/docs/reference/endpoints.html b/docs/reference/endpoints.html index f201294d..68af5fcf 100644 --- a/docs/reference/endpoints.html +++ b/docs/reference/endpoints.html @@ -75,7 +75,7 @@ advantage that the SFORB model can also be used for metabolites." /> mkin - 0.9.49.9 + 0.9.49.10 diff --git a/docs/reference/index.html b/docs/reference/index.html index a3547e29..31f7678c 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -67,7 +67,7 @@ mkin - 0.9.49.9 + 0.9.49.10 @@ -273,7 +273,7 @@ of an mmkin object

-

mean_degparms() nlme_data() nlme_function()

+

nlme_function() mean_degparms() nlme_data()

Estimation of parameter distributions from mmkin row objects

diff --git a/docs/reference/mkinds.html b/docs/reference/mkinds.html index ef6fb35c..946d40a6 100644 --- a/docs/reference/mkinds.html +++ b/docs/reference/mkinds.html @@ -72,7 +72,7 @@ provided by this package come as mkinds objects nevertheless." /> mkin - 0.9.49.9 + 0.9.49.10 diff --git a/docs/reference/mmkin.html b/docs/reference/mmkin.html index 8e1ea54f..c1f62be7 100644 --- a/docs/reference/mmkin.html +++ b/docs/reference/mmkin.html @@ -72,7 +72,7 @@ datasets specified in its first two arguments." /> mkin - 0.9.49.9 + 0.9.49.10 @@ -183,8 +183,9 @@ for parallel execution.

Value

-

A matrix of mkinfit objects that can be indexed using - the model and dataset names as row and column indices.

+

A two-dimensional array of mkinfit + objects that can be indexed using the model names for the first index (row index) + and the dataset names for the second index (column index).

See also

[.mmkin for subsetting, plot.mmkin for @@ -207,15 +208,12 @@ for parallel execution.

time_1 <- system.time(fits.4 <- mmkin(models, datasets, cores = 1, quiet = TRUE)) time_default
#> User System verstrichen -#> 18.739 0.379 6.198
time_1
#> User System verstrichen -#> 19.910 0.000 19.925
+#> 16.471 0.352 5.654
time_1
#> User System verstrichen +#> 19.578 0.000 19.590
endpoints(fits.0[["SFO_lin", 2]])
#> $ff #> parent_M1 parent_sink M1_M2 M1_sink #> 0.7340480 0.2659520 0.7505686 0.2494314 #> -#> $SFORB -#> logical(0) -#> #> $distimes #> DT50 DT90 #> parent 0.8777689 2.915885 diff --git a/docs/reference/nlme.html b/docs/reference/nlme.html index b939d1c3..696916a0 100644 --- a/docs/reference/nlme.html +++ b/docs/reference/nlme.html @@ -6,7 +6,7 @@ -Estimation of parameter distributions from mmkin row objects — mean_degparms • mkin +Estimation of parameter distributions from mmkin row objects — nlme_function • mkin @@ -35,8 +35,8 @@ - - + @@ -72,7 +72,7 @@ datasets." /> mkin - 0.9.49.9 + 0.9.49.10
@@ -136,17 +136,17 @@ datasets." />
-

This function sets up and attempts to fit a mixed effects model to +

These functions facilitate setting up a nonlinear mixed effects model for an mmkin row object. 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.

- 
mean_degparms(object)
+    
nlme_function(object)
 
-nlme_data(object)
+mean_degparms(object)
 
-nlme_function(object)

+nlme_data(object)

Arguments

@@ -159,12 +159,102 @@ datasets.

Value

-

A named vector containing mean values of the fitted degradation model parameters

-

A groupedData data object

-

A function that can be used with nlme

+

A function that can be used with link{nlme}

+

A named vector containing mean values of the fitted degradation model parameters

+

A groupedData object

Examples

- 

+    
sampling_times = c(0, 1, 3, 7, 14, 28, 60, 90, 120)
+m_SFO <- mkinmod(parent = mkinsub("SFO"))
+d_SFO_1 <- mkinpredict(m_SFO,
+  c(k_parent_sink = 0.1),
+  c(parent = 98), sampling_times)
+d_SFO_1_long <- mkin_wide_to_long(d_SFO_1, time = "time")
+d_SFO_2 <- mkinpredict(m_SFO,
+  c(k_parent_sink = 0.05),
+  c(parent = 102), sampling_times)
+d_SFO_2_long <- mkin_wide_to_long(d_SFO_2, time = "time")
+d_SFO_3 <- mkinpredict(m_SFO,
+  c(k_parent_sink = 0.02),
+  c(parent = 103), sampling_times)
+d_SFO_3_long <- mkin_wide_to_long(d_SFO_3, time = "time")
+
+d1 <- add_err(d_SFO_1, function(value) 3, n = 1)
+d2 <- add_err(d_SFO_2, function(value) 2, n = 1)
+d3 <- add_err(d_SFO_3, function(value) 4, n = 1)
+ds <- c(d1 = d1, d2 = d2, d3 = d3)
+
+f <- mmkin("SFO", ds, cores = 1, quiet = TRUE)
+mean_dp <- mean_degparms(f)
+grouped_data <- nlme_data(f)
+nlme_f <- nlme_function(f)
+
+library(nlme)
+m_nlme <- nlme(value ~ nlme_f(name, time, parent_0, log_k_parent_sink),
+  data = grouped_data,
+  fixed = parent_0 + log_k_parent_sink ~ 1,
+  random = pdDiag(parent_0 + log_k_parent_sink ~ 1),
+  start = mean_dp)
#> Error in nlme_f(name, time, parent_0, log_k_parent_sink): konnte Funktion "nlme_f" nicht finden
summary(m_nlme)
#> Error in summary(m_nlme): Objekt 'm_nlme' nicht gefunden

+# \dontrun{
+  # Test on some real data
+  ds_2 <- lapply(experimental_data_for_UBA_2019[6:10],
+   function(x) x$data[c("name", "time", "value")])
+  m_sfo_sfo <- mkinmod(parent = mkinsub("SFO", "A1"),
+    A1 = mkinsub("SFO"), use_of_ff = "min")
#> Successfully compiled differential equation model from auto-generated C code.
  m_sfo_sfo_ff <- mkinmod(parent = mkinsub("SFO", "A1"),
+    A1 = mkinsub("SFO"), use_of_ff = "max")
#> Successfully compiled differential equation model from auto-generated C code.
  m_fomc_sfo <- mkinmod(parent = mkinsub("FOMC", "A1"),
+    A1 = mkinsub("SFO"))
#> Successfully compiled differential equation model from auto-generated C code.
  m_dfop_sfo <- mkinmod(parent = mkinsub("DFOP", "A1"),
+    A1 = mkinsub("SFO"))
#> Successfully compiled differential equation model from auto-generated C code.
  m_sforb_sfo <- mkinmod(parent = mkinsub("SFORB", "A1"),
+    A1 = mkinsub("SFO"))
#> Successfully compiled differential equation model from auto-generated C code.

+  f_2 <- mmkin(list("SFO-SFO" = m_sfo_sfo,
+   "SFO-SFO-ff" = m_sfo_sfo_ff,
+   "FOMC-SFO" = m_fomc_sfo,
+   "DFOP-SFO" = m_dfop_sfo,
+   "SFORB-SFO" = m_sforb_sfo),
+    ds_2)
+
+  grouped_data_2 <- nlme_data(f_2["SFO-SFO", ])
+
+  mean_dp_sfo_sfo <- mean_degparms(f_2["SFO-SFO", ])
+  mean_dp_sfo_sfo_ff <- mean_degparms(f_2["SFO-SFO-ff", ])
+  mean_dp_fomc_sfo <- mean_degparms(f_2["FOMC-SFO", ])
+  mean_dp_dfop_sfo <- mean_degparms(f_2["DFOP-SFO", ])
+  mean_dp_sforb_sfo <- mean_degparms(f_2["SFORB-SFO", ])
+
+  nlme_f_sfo_sfo <- nlme_function(f_2["SFO-SFO", ])
+  nlme_f_sfo_sfo_ff <- nlme_function(f_2["SFO-SFO-ff", ])
+  nlme_f_fomc_sfo <- nlme_function(f_2["FOMC-SFO", ])
+
+  # Allowing for correlations between random effects leads to non-convergence
+  f_nlme_sfo_sfo <- nlme(value ~ nlme_f_sfo_sfo(name, time,
+       parent_0, log_k_parent_sink, log_k_parent_A1, log_k_A1_sink),
+     data = grouped_data_2,
+     fixed = parent_0 + log_k_parent_sink + log_k_parent_A1 + log_k_A1_sink ~ 1,
+     random = pdDiag(parent_0 + log_k_parent_sink + log_k_parent_A1 + log_k_A1_sink ~ 1),
+     start = mean_dp_sfo_sfo)
#> Error in nlme_f_sfo_sfo(name, time, parent_0, log_k_parent_sink, log_k_parent_A1,     log_k_A1_sink): konnte Funktion "nlme_f_sfo_sfo" nicht finden

+  # The same model fitted with transformed formation fractions does not converge
+  f_nlme_sfo_sfo_ff <- nlme(value ~ nlme_f_sfo_sfo_ff(name, time,
+       parent_0, log_k_parent, log_k_A1, f_parent_ilr_1),
+     data = grouped_data_2,
+     fixed = parent_0 + log_k_parent + log_k_A1 + f_parent_ilr_1 ~ 1,
+     random = pdDiag(parent_0 + log_k_parent + log_k_A1 + f_parent_ilr_1 ~ 1),
+     start = mean_dp_sfo_sfo_ff)
#> Error in nlme_f_sfo_sfo_ff(name, time, parent_0, log_k_parent, log_k_A1,     f_parent_ilr_1): konnte Funktion "nlme_f_sfo_sfo_ff" nicht finden

+  # It does converge with this version of reduced random effects
+  f_nlme_sfo_sfo_ff <- nlme(value ~ nlme_f_sfo_sfo_ff(name, time,
+       parent_0, log_k_parent, log_k_A1, f_parent_ilr_1),
+     data = grouped_data_2,
+     fixed = parent_0 + log_k_parent + log_k_A1 + f_parent_ilr_1 ~ 1,
+     random = pdDiag(parent_0 + log_k_parent ~ 1),
+     start = mean_dp_sfo_sfo_ff)
#> Error in nlme_f_sfo_sfo_ff(name, time, parent_0, log_k_parent, log_k_A1,     f_parent_ilr_1): konnte Funktion "nlme_f_sfo_sfo_ff" nicht finden

+  f_nlme_fomc_sfo <- nlme(value ~ nlme_f_fomc_sfo(name, time,
+       parent_0, log_alpha, log_beta, log_k_A1, f_parent_ilr_1),
+     data = grouped_data_2,
+     fixed = parent_0 + log_alpha + log_beta + log_k_A1 + f_parent_ilr_1 ~ 1,
+     random = pdDiag(parent_0 + log_alpha + log_beta + log_k_A1 + f_parent_ilr_1 ~ 1),
+     start = mean_dp_fomc_sfo)
#> Error in nlme_f_fomc_sfo(name, time, parent_0, log_alpha, log_beta, log_k_A1,     f_parent_ilr_1): konnte Funktion "nlme_f_fomc_sfo" nicht finden

+  # DFOP-SFO and SFORB-SFO did not converge with full random effects
+
+  anova(f_nlme_fomc_sfo, f_nlme_sfo_sfo)
#> Error in anova(f_nlme_fomc_sfo, f_nlme_sfo_sfo): Objekt 'f_nlme_fomc_sfo' nicht gefunden
# }
+

 
diff --git a/docs/reference/print.mkinds.html b/docs/reference/print.mkinds.html
index de1a2410..824d961b 100644
--- a/docs/reference/print.mkinds.html
+++ b/docs/reference/print.mkinds.html
@@ -69,7 +69,7 @@
       
         mkin
-        0.9.49.9
+        0.9.49.10
       
 
diff --git a/man/nlme.Rd b/man/nlme.Rd
index e74ba16d..7527f09d 100644
--- a/man/nlme.Rd
+++ b/man/nlme.Rd
@@ -1,29 +1,29 @@
 % Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/nlme.R
-\name{mean_degparms}
+\name{nlme_function}
+\alias{nlme_function}
 \alias{mean_degparms}
 \alias{nlme_data}
-\alias{nlme_function}
 \title{Estimation of parameter distributions from mmkin row objects}
 \usage{
+nlme_function(object)
+
 mean_degparms(object)
 
 nlme_data(object)
-
-nlme_function(object)
 }
 \arguments{
 \item{object}{An mmkin row object containing several fits of the same model to different datasets}
 }
 \value{
-A named vector containing mean values of the fitted degradation model parameters
+A function that can be used with \code{link{nlme}}
 
-A groupedData data object
+A named vector containing mean values of the fitted degradation model parameters
 
-A function that can be used with nlme
+A \code{\link{groupedData}} object
 }
 \description{
-This function sets up and attempts to fit a mixed effects model to
+These functions facilitate setting up a nonlinear mixed effects model for
 an mmkin row object. 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.
@@ -63,7 +63,7 @@ m_nlme <- nlme(value ~ nlme_f(name, time, parent_0, log_k_parent_sink),
 summary(m_nlme)
 
 \dontrun{
-  Test on some real data
+  # Test on some real data
   ds_2 <- lapply(experimental_data_for_UBA_2019[6:10],
    function(x) x$data[c("name", "time", "value")])
   m_sfo_sfo <- mkinmod(parent = mkinsub("SFO", "A1"),
-- 
cgit v1.2.1