getapv: Get apv, pv and ypv using the numerical method, the quadratic...

In Zhiqiangcao/iapvbs: Individual Age at Peak Velocity Based on SITAR

Get apv, pv and ypv using the numerical method, the quadratic function method and the model method

Description

After obtaining estimates from the SITAR model without covariates, this function can compute apv, pv and ypv using the numerical method, the quadratic function method and the model method.

Usage

getapv(object, method = 1, nmy = 365, xfun = NULL, yfun = NULL)

Arguments

object	an object inheriting from class sitar.
method	a number, which can take 3 values, i.e, 1, 2 and 3. method=1 means numerical method; method=2 means quadratic function method; and method=3 means model method.
nmy	number of measurements in a year produced by interpolation through original data. Default value is 365, which means in the interpoaltion data, each individual has 365 measurements in a year over range of age measurements. If nmy=4, which means in the interpolation data, every individual has 4 measurements in a year. If nmy=NULL, it means using original data to calculate pv, apv and ypv based on quadratic function method. When method=3, nmy can be any value, since model method does not use interpolated age.
xfun	an optional function to apply to x to convert it back to the original scale, e.g. if x = log(age) then xfun = function(z) exp(z). Defaults to NULL, which translates to ifun(object$call.sitar$x) and inverts any transformation applied to x in the original SITAR model call.
yfun	an optional function to apply to y to convert it back to the original scale, e.g. if y = sqrt(height) then yfun = function(z) z^2. Defaults to NULL, which translates to ifun(object$ call.sitar$y) and inverts any transformation applied to y in the original SITAR model call.

Details

The numerical method is used by default, and we suggest setting nmy=52 at least (i.e. at least one measurement every week). The default setting of nmy=365 ensures the accuracy of the difference quotient approach in velocity approximation. This method first uses predict.sitar to obtain the corresponding fitted values before applying the difference quotient approach. Since time measurements are very dense, denote dy by the first difference of fitted y and dx by the first difference of interpolated x, and then use dy/dx to approximate the velocity of fitted y. Thus, the maximum value of dy/dx is pv, the x corresponding to maximum dy/dx is apv, and ypv can also be obtained easily based on predict.sitar and apv.

The quadratic function method first finds the empirical maximum velocity through predict.sitar working on observed measurements of each individual. It then uses quadratic polynomial regression to approximate velocity in a small neighbourhood region of the empirical maximum velocity. Finally, with the help of the property of the quadratic function, it is easy to find the point corresponding to the maximum value of velocity in the quadratic function.

For all three methods, if apv is outside of the range of age measurementsat, warning indicator (flag) will be 3; if apv is equal to the minimum or maximum of age, warning indicator will be 2; if apv is too close to the minimum or maximum of age, i.e., in the same month of the minimum or maximum of age, warning indicator will be 1. If apv is NA, which means the estimated apv is questionable due to some other reasons, e.g., the coefficient of the quadratic term is greater than 0.

Note that the unit of x used in the SITAR model is year here. If month or day is used as the unit, a corresponding transformation must be performed.

Value

A data frame including id, pv, ypv, apv and flag (warning indicator: 0 means that the estimated apv is normal; 1 means that the estimated apv is too close to the minimum or maximum age measurement; 2 means that the estimated apv is equal to the minimum or maximum age measurement; 3 means the estimated apv is outside of the range of age measurements; and 4 means that the estimated apv is questionable due to some other reasons) will be outputed.

Author(s)

Zhiqiang Cao [e-mail], L.L. [e-mail] and M.Y. Wong [e-mail]

References

Beath KJ. Infant growth modelling using a shape invariant model with random effects. Statistics in Medicine 2007;26:2547-2564.

Cole TJ, Donaldson MD, Ben-Shlomo Y. SITAR–a useful instrument for growth curve analysis. Int J Epidemiol 2010;39:1558-1566.

Cao Zhiqiang, Hui L.L., Wong M.Y. New approaches to obtaining individual peak height velocity and age at peak height velocity from the SITAR model. Computer Methods and Programs in Biomedicine 2018;163:79-85.

Examples

library(sitar)
###x and y not transformed
m1 <- sitar(x=age,y=height,id=id,data=heights,df=5)
###using the numerical method (default) to compute apv
resu1 <- getapv(m1)
###using the quadratical method (24 measurements in a year) to compute apv
resu2 <- getapv(m1, method=2, nmy=24)
###using the quadratical method to compute apv with original data
resu3 <- getapv(m1, method=2, nmy=NULL)
###model method to compute apv
resu4 <- getapv(m1, method=3)

###x transformed but not y
m2 <- sitar(x=log(age),y=height,id=id,data=heights,df=5)
###using the numerical method (default) to compute apv
resu5 <- getapv(m2)
###using the quadratical method (24 measurements in a year) to compute apv
resu6 <- getapv(m2, method=2, nmy=24)
###the following code is equivalent to above code
resu7 <- getapv(m2, method=2, nmy=24, xfun=function(x) exp(x))
###model method to compute apv
resu8 <- getapv(m2, method=3)

###x not transformed but y transformed
m3 <- sitar(x=age,y=log(height),id=id,data=heights,df=5)
###using the numerical method (default) to compute apv
resu9 <- getapv(m3)
###using the quadratical method (24 measurements in a year) to compute apv
resu10 <- getapv(m3, method=2, nmy=24)
###the following code is equivalent to above code
resu11 <- getapv(m3, method=2, nmy=24, yfun=function(x) exp(x))
###model method to compute apv
resu12 <- getapv(m3, method=3)

Zhiqiangcao/iapvbs documentation built on March 12, 2024, 10:55 p.m.