aboutsummaryrefslogtreecommitdiff
path: root/docs/reference/drfit.html
blob: 2de949f72a097d396d5a91a1c00f3944eb879e9f (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
<!-- Generated by pkgdown: do not edit by hand -->
<!DOCTYPE html>
<html>
  <head>
  <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 dose-response models — drfit • drfit</title>

<!-- jquery -->
<script src="https://code.jquery.com/jquery-3.1.0.min.js" integrity="sha384-nrOSfDHtoPMzJHjVTdCopGqIqeYETSXhZDFyniQ8ZHcVy08QesyHcnOUpMpqnmWq" crossorigin="anonymous"></script>
<!-- Bootstrap -->

<link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script>

<!-- Font Awesome icons -->
<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-T8Gy5hrqNKT+hzMclPo118YTQO6cYprQmhrYwIiQ/3axmI1hQomh7Ud2hPOy8SP1" crossorigin="anonymous">


<!-- pkgdown -->
<link href="../pkgdown.css" rel="stylesheet">
<script src="../jquery.sticky-kit.min.js"></script>
<script src="../pkgdown.js"></script>

<!-- mathjax -->
<script src='https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'></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>
    <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">
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a class="navbar-brand" href="../index.html">drfit</a>
    </div>
    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav">
        <li>
  <a href="../reference/index.html">Reference</a>
</li>
      </ul>
      
      <ul class="nav navbar-nav navbar-right">
        
      </ul>
    </div><!--/.nav-collapse -->
  </div><!--/.container -->
</div><!--/.navbar -->

      
      </header>

      <div class="row">
  <div class="col-md-9 contents">
    <div class="page-header">
    <h1>Fit dose-response models</h1>
    </div>

    
    <p>Fit dose-response relationships to dose-response data and calculate
  biometric results for (eco)toxicity evaluation</p>
    

    <pre><span class='fu'>drfit</span>(<span class='no'>data</span>, <span class='kw'>startlogED50</span> <span class='kw'>=</span> <span class='fl'>NA</span>, <span class='kw'>chooseone</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>, <span class='kw'>probit</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>, <span class='kw'>logit</span> <span class='kw'>=</span> <span class='fl'>FALSE</span>,
  <span class='kw'>weibull</span> <span class='kw'>=</span> <span class='fl'>FALSE</span>, <span class='kw'>linlogit</span> <span class='kw'>=</span> <span class='fl'>FALSE</span>, <span class='kw'>level</span> <span class='kw'>=</span> <span class='fl'>0.95</span>, <span class='kw'>linlogitWrong</span> <span class='kw'>=</span> <span class='fl'>NA</span>,
  <span class='kw'>allWrong</span> <span class='kw'>=</span> <span class='fl'>NA</span>, <span class='kw'>ps0</span> <span class='kw'>=</span> <span class='fl'>1</span>, <span class='kw'>ls0</span> <span class='kw'>=</span> <span class='fl'>0.5</span>, <span class='kw'>ws0</span> <span class='kw'>=</span> <span class='fl'>0.5</span>, <span class='kw'>b0</span> <span class='kw'>=</span> <span class='fl'>2</span>, <span class='kw'>f0</span> <span class='kw'>=</span> <span class='fl'>0</span>,
  <span class='kw'>showED50</span> <span class='kw'>=</span> <span class='fl'>FALSE</span>,
  <span class='kw'>EDx</span> <span class='kw'>=</span> <span class='kw'>NULL</span>, <span class='kw'>EDx.tolerance</span> <span class='kw'>=</span> <span class='fl'>1e-4</span>)</pre>
    
    <h2 class="hasAnchor" id="arguments"><a class="anchor" href="#arguments"></a> Arguments</h2>
    <table class="ref-arguments">
    <colgroup><col class="name" /><col class="desc" /></colgroup>
    <tr>
      <th>data</th>
      <td><p>A data frame containing dose-response data. The data frame has to contain
    at least a factor called &#8220;substance&#8221;, a numeric vector &#8220;dose&#8221;
    with the dose values, a vector called &#8220;unit&#8221; containing the unit
    used for the dose and a numeric vector &#8220;response&#8221; with the response
    values of the test system normalized between 0 and 1. Such a data frame can
    be easily obtained if a compliant RODBC data source is available for use in
    conjunction with the function <code><a href='drdata.html'>drdata</a></code>.</p>
<p>If there is a column called &#8220;ok&#8221; and it is set to &#8220;no fit&#8221; in
    a specific line, then the corresponding data point will be excluded from
    the fitting procedure, although it will be plotted.</p></td>
    </tr>
    <tr>
      <th>startlogED50</th>
      <td><p>Especially for the linlogit model, a suitable log10 of the ED50 has to be
    given by the user, since it is not correctly estimated for data showing
    hormesis with the default estimation method.</p></td>
    </tr>
    <tr>
      <th>probit</th>
      <td><p>A boolean defining if cumulative density curves of normal distributions
    <code>pnorm</code> are fitted against the decadic logarithm of the dose.
    Default ist TRUE.</p></td>
    </tr>
    <tr>
      <th>logit</th>
      <td><p>A boolean defining if cumulative density curves of logistic distributions
    <code>plogis</code> are fitted to the decadic logarithm of the dose.
    Default is FALSE.</p></td>
    </tr>
    <tr>
      <th>weibull</th>
      <td><p>A boolean defining if the cumulative density curves of weibull distributions
    (<code>pweibull</code> with additionall location parameter and scale=1)
    are fitted to the decadic logarithm of the dose. Default is FALSE.
    Note that the weibull distribution is fitted here to the log transformed doses
    which appears to be an uncommon approach.</p></td>
    </tr>
    <tr>
      <th>linlogit</th>
      <td><p>A boolean defining if the linear-logistic function
    <code><a href='linlogitf.html'>linlogitf</a></code> as defined by van Ewijk and Hoekstra 1993 is
    fitted to the data. Default is FALSE.</p></td>
    </tr>
    <tr>
      <th>level</th>
      <td><p>The level for the confidence interval listed for the log ED50.</p></td>
    </tr>
    <tr>
      <th>linlogitWrong</th>
      <td><p>An optional vector containing the names of the substances for which the
    linlogit function produces a wrong fit.</p></td>
    </tr>
    <tr>
      <th>allWrong</th>
      <td><p>An optional vector containing the names of the substances for which all
    functions produce a wrong fit.</p></td>
    </tr>
    <tr>
      <th>chooseone</th>
      <td><p>If TRUE (default), the models are tried in the order linlogit, probit,
    logit, weibull, and the first model that produces a valid fit is used.
    If FALSE, all models that are set to TRUE and that can be fitted will be
    reported.</p></td>
    </tr>
    <tr>
      <th>ps0</th>
      <td><p>If the probit model is fitted, <code>ps0</code> gives the possibility to adjust
    the starting value for the scale parameter of <code>pnorm</code>.</p></td>
    </tr>
    <tr>
      <th>ls0</th>
      <td><p>If the logit model is fitted, <code>ls0</code> gives the possibility to adjust
    the starting value for the scale parameter of <code>plogis</code>.</p></td>
    </tr>
    <tr>
      <th>ws0</th>
      <td><p>If the weibull model is fitted, <code>ws0</code> gives the possibility to adjust
    the starting value for the shape parameter of <code>pweibull</code>.</p></td>
    </tr>
    <tr>
      <th>b0,f0</th>
      <td><p>If the linearlogistic model is fitted, <code>b0</code> and <code>f0</code> give the
    possibility to adjust the starting values for the parameters b and f.</p></td>
    </tr>
    <tr>
      <th>showED50</th>
      <td><p>If set to TRUE, the ED50 and its confidence interval on the original dose
    scale (not log scale) is included in the output.</p></td>
    </tr>
    <tr>
      <th>EDx</th>
      <td><p>A vector of inhibition values x in percent for which the corresponding doses
    EDx should be reported.</p></td>
    </tr>
    <tr>
      <th>EDx.tolerance</th>
      <td><p>Tolerance of the effect level, expressed on the response scale from 0 to 1.</p></td>
    </tr>
    </table>
    
    <h2 class="hasAnchor" id="value"><a class="anchor" href="#value"></a>Value</h2>

    <p>A dataframe with the attribute <code>models</code> holding a list of the fitted
  dose-response models of class <code>nls</code>. The dataframe has at least
  one line for each substance.</p>
<p>For the &#8220;linlogit&#8221;, &#8220;logit&#8221; and &#8220;probit&#8221; models, the
  parameter <code>a</code> that is reported coincides with the logED50, i.e the
  logED50 is one of the model parameters that is being fitted. Therefore,
  a confidence interval for the confidence level <code>level</code> is calculated
  using the <code>confint.nls</code> function and listed.</p>
<p>The following variables are in the dataframe:</p>
<dt>Substance</dt><dd><p>The name of the substance</p></dd>
  <dt>ndl</dt><dd><p>The number of dose levels in the raw data</p></dd>
  <dt>n</dt><dd><p>The total number of data points in the raw data used for the fit</p></dd>
  <dt>lld</dt><dd><p>The decadic logarithm of the lowest dose</p></dd>
  <dt>lhd</dt><dd><p>The total number of data points in the raw data used for the fit</p></dd>
  <dt>mtype</dt><dd><p>If the data did not show a mean response &lt; 0.5 at the highest dose level,
    the modeltype is set to &#8220;inactive&#8221;. If the mean response at the
    lowest dose is smaller than 0.5, the modeltype is set to &#8220;active&#8221;.
    In both cases, no fitting procedure is carried out. If the fitted ED50
    is higher than the highest dose, &#8220;no fit&#8221; is given here.</p></dd>
  <dt>logED50</dt><dd><p>The decadic logarithm of the ED50</p></dd>
  <dt>low %</dt><dd><p>The lower bound of the confidence interval of log ED50.
    The name of the column depends on the requested confidence <code>level</code>.</p></dd>
  <dt>high %</dt><dd><p>The higher bound of the confidence interval of log ED50.
    The name of the column depends on the requested confidence <code>level</code>.</p></dd>
  <dt>unit</dt><dd><p>The unit used for the dose levels in the dose-response data</p></dd>
  <dt>sigma</dt><dd><p>The square root of the estimated variance of the random error as returned
    by <code>summary.nls</code>.</p></dd>
  <dt>a</dt><dd><p>For the &#8220;linlogit&#8221;, &#8220;logit&#8221; and &#8220;probit&#8221; models, the
    parameter <code>a</code> coincides with the logED50.  In the case of the
    &#8220;weibull&#8221; model, <code>a</code> is a location parameter.</p></dd>
  <dt>b</dt><dd><p>Parameter <code>b</code> in the case of the &#8220;linlogit&#8221; fit is the variable
    b from the <code>linlogitf</code> function. In the case of &#8220;probit&#8221;
    fit it is the standard deviation of the fitted normal distribution, in the
    case of the &#8220;logit&#8221; fit it is the <code>scale</code> parameter in the
    <code>plogis</code> function, and in the &#8220;weibull&#8221; fit it is the
    <code>shape</code> parameter of the fitted <code>pweibull</code> function.</p></dd>
  <dt>c</dt><dd><p>Only the &#8220;linlogit&#8221; fit produces a third parameter <code>c</code> which is
    the variable f from the <code>linlogitf</code> function.</p></dd>
  If the parameter showED50 was set to TRUE, the ED50 values and their
  confidence intervals are also included on the original dose scale.

  If one or more response leves were specified in the argument EDx,
  the corresponding dose levels are given in addition.

    
    <h2 class="hasAnchor" id="note"><a class="anchor" href="#note"></a>Note</h2>

    <p>There is a demo for each dataset that can be accessed by
  <code>demo(dataset)</code></p>
    
    <h2 class="hasAnchor" id="see-also"><a class="anchor" href="#see-also"></a>See also</h2>

    <p>Further examples are given in help pages to the datasets
  <code><a href='antifoul.html'>antifoul</a></code>, <code><a href='IM1xIPC81.html'>IM1xIPC81</a></code> and
  <code><a href='IM1xVibrio.html'>IM1xVibrio</a></code>.
  Since version 0.6.1 of this package, there is a drop-in replacement function
  <code><a href='drcfit.html'>drcfit</a></code> which internally uses the drc package and also gives
  confidence intervals for EDx values via this package.</p>
    

    <h2 class="hasAnchor" id="examples"><a class="anchor" href="#examples"></a>Examples</h2>
    <pre class="examples"><div class='input'><span class='fu'>data</span>(<span class='no'>antifoul</span>)
<span class='no'>r</span> <span class='kw'>&lt;-</span> <span class='fu'>drfit</span>(<span class='no'>antifoul</span>, <span class='kw'>showED50</span> <span class='kw'>=</span> <span class='fl'>TRUE</span>, <span class='kw'>EDx</span> <span class='kw'>=</span> <span class='fu'>c</span>(<span class='fl'>5</span>, <span class='fl'>10</span>, <span class='fl'>20</span>))</div><div class='output co'>#&gt; <span class='message'></span>
#&gt; <span class='message'>TBT: Fitting data...</span></div><div class='output co'>#&gt; <span class='message'>Waiting for profiling to be done...</span></div><div class='output co'>#&gt; <span class='message'></span>
#&gt; <span class='message'>Zn Pyrithion: Fitting data...</span></div><div class='output co'>#&gt; <span class='message'>Waiting for profiling to be done...</span></div><div class='input'><span class='fu'>format</span>(<span class='no'>r</span>, <span class='kw'>digits</span> <span class='kw'>=</span> <span class='fl'>2</span>)</div><div class='output co'>#&gt;      Substance ndl   n  lld lhd  mtype logED50  2.5%  97.5%   unit sigma     a
#&gt; 1          TBT  38 135 -2.7 2.4 probit   -0.16 -0.27 -0.056 microM  0.19 -0.16
#&gt; 2 Zn Pyrithion  27  81 -2.1 2.0 probit   -0.40 -0.51 -0.292 microM  0.23 -0.40
#&gt;      b ED50 ED50 2.5% ED50 97.5%  EDx5 EDx10 EDx20
#&gt; 1 0.68 0.68      0.54       0.88 0.053 0.093  0.18
#&gt; 2 0.42 0.40      0.31       0.51 0.082 0.117  0.18</div></pre>
  </div>
  <div class="col-md-3 hidden-xs hidden-sm" id="sidebar">
    <h2>Contents</h2>
    <ul class="nav nav-pills nav-stacked">
      <li><a href="#arguments">Arguments</a></li>
      
      <li><a href="#value">Value</a></li>

      <li><a href="#note">Note</a></li>

      <li><a href="#see-also">See also</a></li>
      
      <li><a href="#examples">Examples</a></li>
    </ul>

    <h2>Author</h2>
    
  Johannes Ranke
  <a href='mailto:jranke@uni-bremen.de'>jranke@uni-bremen.de</a>
  <a href = 'http://www.uft.uni-bremen.de/chemie/ranke'>http://www.uft.uni-bremen.de/chemie/ranke</a>

  </div>
</div>

      <footer>
      <div class="copyright">
  <p>Developed by Johannes Ranke.</p>
</div>

<div class="pkgdown">
  <p>Site built with <a href="http://hadley.github.io/pkgdown/">pkgdown</a>.</p>
</div>

      </footer>
   </div>

  </body>
</html>

Contact - Imprint