[Rd] nlme: New variance function structure varConstProp

[Johannes Ranke]

Dear R developers,

recently I have written a wishlist bug report for nlme containing a patch that 
adds the variance function structure

s2(v) = t1^2 + t2^2*v^2

where v denotes the variance covariate, s2(v) denotes the variance function 
evaluated at v, and t, t1 and t2 are the variance function coefficients. The 
covariate can also be the fitted response.

The idea that the residual variance has an additive component and a component
proportional to the observed or fitted response is found in analytical 
chemistry [2, 3], pharmacokinetics [4], and has recently also been introduced 
to chemical degradation kinetics [5, 6].

As discussed in a recent monograph on mixed effects models [7, p. 55] and in a 
manuscript dedicated to the comparison of different variants of this error 
model [4], there are two principal possibilities to implement the idea of 
combining additive and proportional error. The variant implemented in the 
proposed patch assumes that the sources of the additive and the proportional 
component are independent. An alternative variant would be

s2(v) = (t1 + t2*abs(v))^2

However, I have less frequently found that alternative proposal in the 
literature, and I also think that it makes sense to assume independent sources 
of the two components.

I think that adding the possibility to specify this error model greatly 
enhances the potential of the nlme package in the area of generalised linear 
models (gls), generalised nonlinear models (gnls) and, last but not least, 
generalised nonlinear mixed effects models (nlme).

In addition, the patch is rather unobtrusive, as it only adds a further 
variance function structure. The documentation contains an example application 
using gnls(), and there is a test using nlme() and group dependent values for 
t1 and t2.

Therefore, I would recommend the proposed patch for your kind consideration.

Johannes Ranke

[1] https://bugs.r-project.org/bugzilla/show_bug.cgi?id=17954
[2] https://doi.org/10.1093/clinchem/24.11.1895
[3] https://doi.org/10.1016/j.aca.2003.12.047
[4] https://doi.org/10.1016/j.ejps.2017.05.021
[5] https://doi.org/10.3390/environments6120124
[6] https://pkgdown.jrwb.de/mkin/dev/reference/sigma_twocomp.html
[7] https://doi.org/10.1201/b17203