|
|
<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>Fit nonlinear mixed-effects models built from one or more kinetic
degradation models and one or more error models — mhmkin • mkin</title><!-- jquery --><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script><!-- Bootstrap --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha256-bZLfwXAP04zRMK2BjiO8iu9pf4FbLqX6zitd+tIvLhE=" crossorigin="anonymous"><script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha256-nuL8/2cJ5NDSSwnKD8VqreErSWHtnEP9E7AySL+1ev4=" crossorigin="anonymous"></script><!-- bootstrap-toc --><link rel="stylesheet" href="../bootstrap-toc.css"><script src="../bootstrap-toc.js"></script><!-- Font Awesome icons --><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.6/clipboard.min.js" integrity="sha256-inc5kl9MA1hkeYUt+EC3BhlIgyp/2jDIyBLS6k3UxPI=" crossorigin="anonymous"></script><!-- headroom.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet"><script src="../pkgdown.js"></script><meta property="og:title" content="Fit nonlinear mixed-effects models built from one or more kinetic
degradation models and one or more error models — mhmkin"><meta property="og:description" content="The name of the methods expresses that (multiple) hierarchichal
(also known as multilevel) multicompartment kinetic models are
fitted. Our kinetic models are nonlinear, so we can use various nonlinear
mixed-effects model fitting functions."><meta name="robots" content="noindex"><!-- mathjax --><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]--></head><body data-spy="scroll" data-target="#toc">
<div class="container template-reference-topic">
<header><div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span class="navbar-brand">
<a class="navbar-link" href="../index.html">mkin</a>
<span class="version label label-info" data-toggle="tooltip" data-placement="bottom" title="In-development version">1.2.5</span>
</span>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav"><li>
<a href="../reference/index.html">Reference</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Articles
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu"><li>
<a href="../articles/mkin.html">Introduction to mkin</a>
</li>
<li class="divider">
<li class="dropdown-header">Example evaluations with (generalised) nonlinear least squares</li>
<li>
<a href="../articles/FOCUS_D.html">Example evaluation of FOCUS Example Dataset D</a>
</li>
<li>
<a href="../articles/FOCUS_L.html">Example evaluation of FOCUS Laboratory Data L1 to L3</a>
</li>
<li>
<a href="../articles/web_only/FOCUS_Z.html">Example evaluation of FOCUS Example Dataset Z</a>
</li>
<li class="divider">
<li class="dropdown-header">Example evaluations with hierarchical models (nonlinear mixed-effects models)</li>
<li>
<a href="../articles/prebuilt/2022_dmta_parent.html">Testing hierarchical parent degradation kinetics with residue data on dimethenamid and dimethenamid-P</a>
</li>
<li>
<a href="../articles/prebuilt/2022_dmta_pathway.html">Testing hierarchical pathway kinetics with residue data on dimethenamid and dimethenamid-P</a>
</li>
<li>
<a href="../articles/prebuilt/2022_cyan_pathway.html">Testing hierarchical pathway kinetics with residue data on cyantraniliprole</a>
</li>
<li>
<a href="../articles/web_only/dimethenamid_2018.html">Comparison of saemix and nlme evaluations of dimethenamid data from 2018</a>
</li>
<li>
<a href="../articles/web_only/multistart.html">Short demo of the multistart method</a>
</li>
<li class="divider">
<li class="dropdown-header">Performance</li>
<li>
<a href="../articles/web_only/compiled_models.html">Performance benefit by using compiled model definitions in mkin</a>
</li>
<li>
<a href="../articles/web_only/benchmarks.html">Benchmark timings for mkin</a>
</li>
<li>
<a href="../articles/web_only/saem_benchmarks.html">Benchmark timings for saem.mmkin</a>
</li>
<li class="divider">
<li class="dropdown-header">Miscellaneous</li>
<li>
<a href="../articles/twa.html">Calculation of time weighted average concentrations with mkin</a>
</li>
<li>
<a href="../articles/web_only/NAFTA_examples.html">Example evaluation of NAFTA SOP Attachment examples</a>
</li>
</ul></li>
<li>
<a href="../news/index.html">News</a>
</li>
</ul><ul class="nav navbar-nav navbar-right"><li>
<a href="https://github.com/jranke/mkin/" class="external-link">
<span class="fab fa-github fa-lg"></span>
</a>
</li>
</ul></div><!--/.nav-collapse -->
</div><!--/.container -->
</div><!--/.navbar -->
</header><div class="row">
<div class="col-md-9 contents">
<div class="page-header">
<h1>Fit nonlinear mixed-effects models built from one or more kinetic
degradation models and one or more error models</h1>
<small class="dont-index">Source: <a href="https://github.com/jranke/mkin/blob/HEAD/R/mhmkin.R" class="external-link"><code>R/mhmkin.R</code></a></small>
<div class="hidden name"><code>mhmkin.Rd</code></div>
</div>
<div class="ref-description">
<p>The name of the methods expresses that (<strong>m</strong>ultiple) <strong>h</strong>ierarchichal
(also known as multilevel) <strong>m</strong>ulticompartment <strong>kin</strong>etic models are
fitted. Our kinetic models are nonlinear, so we can use various nonlinear
mixed-effects model fitting functions.</p>
</div>
<div id="ref-usage">
<div class="sourceCode"><pre><code>mhmkin(objects, ...)
# S3 method for mmkin
mhmkin(objects, ...)
# S3 method for list
mhmkin(
objects,
backend = "saemix",
algorithm = "saem",
no_random_effect = NULL,
...,
cores = if (Sys.info()["sysname"] == "Windows") 1 else parallel::detectCores(),
cluster = NULL
)
# S3 method for mhmkin
[(x, i, j, ..., drop = FALSE)
# S3 method for mhmkin
print(x, ...)</code></pre></div>
</div>
<div id="arguments">
<h2>Arguments</h2>
<dl><dt>objects</dt>
<dd><p>A list of <a href="mmkin.html">mmkin</a> objects containing fits of the same
degradation models to the same data, but using different error models.
Alternatively, a single <a href="mmkin.html">mmkin</a> object containing fits of several
degradation models to the same data</p></dd>
<dt>...</dt>
<dd><p>Further arguments that will be passed to the nonlinear mixed-effects
model fitting function.</p></dd>
<dt>backend</dt>
<dd><p>The backend to be used for fitting. Currently, only saemix is
supported</p></dd>
<dt>algorithm</dt>
<dd><p>The algorithm to be used for fitting (currently not used)</p></dd>
<dt>no_random_effect</dt>
<dd><p>Default is NULL and will be passed to <a href="saem.html">saem</a>. If a
character vector is supplied, it will be passed to all calls to <a href="saem.html">saem</a>,
which will exclude random effects for all matching parameters. Alternatively,
a list of character vectors or an object of class <a href="illparms.html">illparms.mhmkin</a> can be
specified. They have to have the same dimensions that the return object of
the current call will have, i.e. the number of rows must match the number
of degradation models in the mmkin object(s), and the number of columns must
match the number of error models used in the mmkin object(s).</p></dd>
<dt>cores</dt>
<dd><p>The number of cores to be used for multicore processing. This
is only used when the <code>cluster</code> argument is <code>NULL</code>. On Windows
machines, cores > 1 is not supported, you need to use the <code>cluster</code>
argument to use multiple logical processors. Per default, all cores detected
by <code><a href="https://rdrr.io/r/parallel/detectCores.html" class="external-link">parallel::detectCores()</a></code> are used, except on Windows where the default
is 1.</p></dd>
<dt>cluster</dt>
<dd><p>A cluster as returned by makeCluster to be used for
parallel execution.</p></dd>
<dt>x</dt>
<dd><p>An mhmkin object.</p></dd>
<dt>i</dt>
<dd><p>Row index selecting the fits for specific models</p></dd>
<dt>j</dt>
<dd><p>Column index selecting the fits to specific datasets</p></dd>
<dt>drop</dt>
<dd><p>If FALSE, the method always returns an mhmkin object, otherwise
either a list of fit objects or a single fit object.</p></dd>
</dl></div>
<div id="value">
<h2>Value</h2>
<p>A two-dimensional <a href="https://rdrr.io/r/base/array.html" class="external-link">array</a> of fit objects and/or try-errors that can
be indexed using the degradation model names for the first index (row index)
and the error model names for the second index (column index), with class
attribute 'mhmkin'.</p>
<p>An object inheriting from <code>mhmkin</code>.</p>
</div>
<div id="see-also">
<h2>See also</h2>
<div class="dont-index"><p><code>[.mhmkin</code> for subsetting mhmkin objects</p></div>
</div>
<div id="author">
<h2>Author</h2>
<p>Johannes Ranke</p>
</div>
<div id="ref-examples">
<h2>Examples</h2>
<div class="sourceCode"><pre class="sourceCode r"><code><span class="r-in"><span><span class="co"># \dontrun{</span></span></span>
<span class="r-in"><span><span class="co"># We start with separate evaluations of all the first six datasets with two</span></span></span>
<span class="r-in"><span><span class="co"># degradation models and two error models</span></span></span>
<span class="r-in"><span><span class="va">f_sep_const</span> <span class="op"><-</span> <span class="fu"><a href="mmkin.html">mmkin</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="st">"SFO"</span>, <span class="st">"FOMC"</span><span class="op">)</span>, <span class="va">ds_fomc</span><span class="op">[</span><span class="fl">1</span><span class="op">:</span><span class="fl">6</span><span class="op">]</span>, cores <span class="op">=</span> <span class="fl">2</span>, quiet <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">f_sep_tc</span> <span class="op"><-</span> <span class="fu"><a href="https://rdrr.io/r/stats/update.html" class="external-link">update</a></span><span class="op">(</span><span class="va">f_sep_const</span>, error_model <span class="op">=</span> <span class="st">"tc"</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="co"># The mhmkin function sets up hierarchical degradation models aka</span></span></span>
<span class="r-in"><span><span class="co"># nonlinear mixed-effects models for all four combinations, specifying</span></span></span>
<span class="r-in"><span><span class="co"># uncorrelated random effects for all degradation parameters</span></span></span>
<span class="r-in"><span><span class="va">f_saem_1</span> <span class="op"><-</span> <span class="fu">mhmkin</span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/list.html" class="external-link">list</a></span><span class="op">(</span><span class="va">f_sep_const</span>, <span class="va">f_sep_tc</span><span class="op">)</span>, cores <span class="op">=</span> <span class="fl">2</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu"><a href="status.html">status</a></span><span class="op">(</span><span class="va">f_saem_1</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#></span> error</span>
<span class="r-out co"><span class="r-pr">#></span> degradation const tc</span>
<span class="r-out co"><span class="r-pr">#></span> SFO OK OK</span>
<span class="r-out co"><span class="r-pr">#></span> FOMC OK OK</span>
<span class="r-out co"><span class="r-pr">#></span> </span>
<span class="r-out co"><span class="r-pr">#></span> OK: Fit terminated successfully</span>
<span class="r-in"><span><span class="co"># The 'illparms' function shows that in all hierarchical fits, at least</span></span></span>
<span class="r-in"><span><span class="co"># one random effect is ill-defined (the confidence interval for the</span></span></span>
<span class="r-in"><span><span class="co"># random effect expressed as standard deviation includes zero)</span></span></span>
<span class="r-in"><span><span class="fu"><a href="illparms.html">illparms</a></span><span class="op">(</span><span class="va">f_saem_1</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#></span> error</span>
<span class="r-out co"><span class="r-pr">#></span> degradation const tc </span>
<span class="r-out co"><span class="r-pr">#></span> SFO sd(parent_0) sd(parent_0) </span>
<span class="r-out co"><span class="r-pr">#></span> FOMC sd(log_beta) sd(parent_0), sd(log_beta)</span>
<span class="r-in"><span><span class="co"># Therefore we repeat the fits, excluding the ill-defined random effects</span></span></span>
<span class="r-in"><span><span class="va">f_saem_2</span> <span class="op"><-</span> <span class="fu"><a href="https://rdrr.io/r/stats/update.html" class="external-link">update</a></span><span class="op">(</span><span class="va">f_saem_1</span>, no_random_effect <span class="op">=</span> <span class="fu"><a href="illparms.html">illparms</a></span><span class="op">(</span><span class="va">f_saem_1</span><span class="op">)</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu"><a href="status.html">status</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#></span> error</span>
<span class="r-out co"><span class="r-pr">#></span> degradation const tc</span>
<span class="r-out co"><span class="r-pr">#></span> SFO OK OK</span>
<span class="r-out co"><span class="r-pr">#></span> FOMC OK OK</span>
<span class="r-out co"><span class="r-pr">#></span> </span>
<span class="r-out co"><span class="r-pr">#></span> OK: Fit terminated successfully</span>
<span class="r-in"><span><span class="fu"><a href="illparms.html">illparms</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#></span> error</span>
<span class="r-out co"><span class="r-pr">#></span> degradation const tc</span>
<span class="r-out co"><span class="r-pr">#></span> SFO </span>
<span class="r-out co"><span class="r-pr">#></span> FOMC </span>
<span class="r-in"><span><span class="co"># Model comparisons show that FOMC with two-component error is preferable,</span></span></span>
<span class="r-in"><span><span class="co"># and confirms our reduction of the default parameter model</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/stats/anova.html" class="external-link">anova</a></span><span class="op">(</span><span class="va">f_saem_1</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#></span> Data: 95 observations of 1 variable(s) grouped in 6 datasets</span>
<span class="r-out co"><span class="r-pr">#></span> </span>
<span class="r-out co"><span class="r-pr">#></span> npar AIC BIC Lik</span>
<span class="r-out co"><span class="r-pr">#></span> SFO const 5 574.40 573.35 -282.20</span>
<span class="r-out co"><span class="r-pr">#></span> SFO tc 6 543.72 542.47 -265.86</span>
<span class="r-out co"><span class="r-pr">#></span> FOMC const 7 489.67 488.22 -237.84</span>
<span class="r-out co"><span class="r-pr">#></span> FOMC tc 8 406.11 404.44 -195.05</span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/stats/anova.html" class="external-link">anova</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#></span> Data: 95 observations of 1 variable(s) grouped in 6 datasets</span>
<span class="r-out co"><span class="r-pr">#></span> </span>
<span class="r-out co"><span class="r-pr">#></span> npar AIC BIC Lik</span>
<span class="r-out co"><span class="r-pr">#></span> SFO const 4 572.22 571.39 -282.11</span>
<span class="r-out co"><span class="r-pr">#></span> SFO tc 5 541.63 540.59 -265.81</span>
<span class="r-out co"><span class="r-pr">#></span> FOMC const 6 487.38 486.13 -237.69</span>
<span class="r-out co"><span class="r-pr">#></span> FOMC tc 6 402.12 400.88 -195.06</span>
<span class="r-in"><span><span class="co"># The convergence plot for the selected model looks fine</span></span></span>
<span class="r-in"><span><span class="fu">saemix</span><span class="fu">::</span><span class="fu"><a href="https://rdrr.io/r/base/plot.html" class="external-link">plot</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">[[</span><span class="st">"FOMC"</span>, <span class="st">"tc"</span><span class="op">]</span><span class="op">]</span><span class="op">$</span><span class="va">so</span>, plot.type <span class="op">=</span> <span class="st">"convergence"</span><span class="op">)</span></span></span>
<span class="r-plt img"><img src="mhmkin-1.png" alt="" width="700" height="433"></span>
<span class="r-in"><span><span class="co"># The plot of predictions versus data shows that we have a pretty data-rich</span></span></span>
<span class="r-in"><span><span class="co"># situation with homogeneous distribution of residuals, because we used the</span></span></span>
<span class="r-in"><span><span class="co"># same degradation model, error model and parameter distribution model that</span></span></span>
<span class="r-in"><span><span class="co"># was used in the data generation.</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/graphics/plot.default.html" class="external-link">plot</a></span><span class="op">(</span><span class="va">f_saem_2</span><span class="op">[[</span><span class="st">"FOMC"</span>, <span class="st">"tc"</span><span class="op">]</span><span class="op">]</span><span class="op">)</span></span></span>
<span class="r-plt img"><img src="mhmkin-2.png" alt="" width="700" height="433"></span>
<span class="r-in"><span><span class="co"># We can specify the same parameter model reductions manually</span></span></span>
<span class="r-in"><span><span class="va">no_ranef</span> <span class="op"><-</span> <span class="fu"><a href="https://rdrr.io/r/base/list.html" class="external-link">list</a></span><span class="op">(</span><span class="st">"parent_0"</span>, <span class="st">"log_beta"</span>, <span class="st">"parent_0"</span>, <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="st">"parent_0"</span>, <span class="st">"log_beta"</span><span class="op">)</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/base/dim.html" class="external-link">dim</a></span><span class="op">(</span><span class="va">no_ranef</span><span class="op">)</span> <span class="op"><-</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="fl">2</span>, <span class="fl">2</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="va">f_saem_2m</span> <span class="op"><-</span> <span class="fu"><a href="https://rdrr.io/r/stats/update.html" class="external-link">update</a></span><span class="op">(</span><span class="va">f_saem_1</span>, no_random_effect <span class="op">=</span> <span class="va">no_ranef</span><span class="op">)</span></span></span>
<span class="r-in"><span><span class="fu"><a href="https://rdrr.io/r/stats/anova.html" class="external-link">anova</a></span><span class="op">(</span><span class="va">f_saem_2m</span><span class="op">)</span></span></span>
<span class="r-out co"><span class="r-pr">#></span> Data: 95 observations of 1 variable(s) grouped in 6 datasets</span>
<span class="r-out co"><span class="r-pr">#></span> </span>
<span class="r-out co"><span class="r-pr">#></span> npar AIC BIC Lik</span>
<span class="r-out co"><span class="r-pr">#></span> SFO const 4 572.22 571.39 -282.11</span>
<span class="r-out co"><span class="r-pr">#></span> SFO tc 5 541.63 540.59 -265.81</span>
<span class="r-out co"><span class="r-pr">#></span> FOMC const 6 487.38 486.13 -237.69</span>
<span class="r-out co"><span class="r-pr">#></span> FOMC tc 6 402.12 400.88 -195.06</span>
<span class="r-in"><span><span class="co"># }</span></span></span>
</code></pre></div>
</div>
</div>
<div class="col-md-3 hidden-xs hidden-sm" id="pkgdown-sidebar">
<nav id="toc" data-toggle="toc" class="sticky-top"><h2 data-toc-skip>Contents</h2>
</nav></div>
</div>
<footer><div class="copyright">
<p></p><p>Developed by Johannes Ranke.</p>
</div>
<div class="pkgdown">
<p></p><p>Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.0.7.</p>
</div>
</footer></div>
</body></html>
|
