lmfor (version 1.6)

volvff: The Variable Form-Factor Volume Model

Description

An R-function for the variable form-factor volume model and a function for computing bias-corrected volumes augmented with parameter uncertainty from a model fitted using nlme.

Usage

volvff(dbh,h,theta=NA,logita=NA,lambda=NA)
predvff(data,mod,p=0.05,varMethod="taylor",biasCorr="none",nrep=500)

Arguments

dbh

vector of individual tree diameters, cm

h

vector of individual tree heights (m), of same length as dbh.

theta, logita, lambda

The parameters logita and lambda can be given either in a two-column matrix where the number of rows equals to the length of dbh, or separately in objects logita and lambda, which can be scalars or vectors of same length as dbh. If theta is not NA, argumets logita and lambda are ignored.

data

A data set including variables dbh and h and all variables that are used as second-order predictors in mod.

mod

A variable form-factor model fitted using nlme. Any second-order predictors can be used for parameters logita and lambda. The bias-correction works properly only if the model includes random intercepts in logita.

p

The probability used in constructiong the confidence intervals for tree-level volumes and total volume. Symmetric \(100(1-p)\)% confidence intervals are returned.

varMethod

Either "taylor"(the default) or "simul". Specifies whether parameter uncertainty is approximated by using a linearized model based on the first-order Taylor approximation or by using Monte Carlo simulation.

biasCorr

Either "none"(the default), "integrate" or "twopoint". Specifies whether the bias correction is not done ("none"), is done by computing expected value of the prediction over the distribution of random intercepts in parameter logita, or by using the two-point approximation described in Kangas et al. (XXXX).

nrep

The number of replicates in the Monte Carlo simulation when varMethod="simul". Ignored if varMethod="taylor".

Value

Function volvff returns a vector of tree volumes (in liters) that is of same length as vector dbh. In addition, attribute grad returns the Jacobian, which is used in nlme fitting for computing the derivatives of the model with respect to parameters, and in approximating the parameter uncertainty when varMethod="taylor".

Function predvff returns a list with following objects

totvol

Total volume of the trees of dat, in \(m^3\).

totvolvar

The estimated variance of totvol, taking into account parameter uncertainty.

totvolci

The estimated \(100(1-p)\)% confidence interval of totvol, based on parameter uncertainty. If varMethod="taylor", it is based on normality and the approximated variance totvolvar. If varMethod="simul", the empirical quantiles of the nrep simulations are used.

And attributes

trees

A data frame of including tree-level volumes, their variance and 95% confidence intervals.

varmu

The variance-covariance matrix of prediction errors, taking into account theparameter uncertainty.

Details

The variance-form-factor function is of form $$ v(D,H,a,\lambda)=\pi \frac{\exp(a)}{1+\exp(a)} R(D,H,\lambda)^2 H $$ where \(a\) is the logit-transformed form factor and \(R(D,H,\lambda)\) is the stem radius at stump height, which is approximated using $$ R(D,H,\lambda)=w(H,\lambda)\frac{D}{2}+(1-w(H,\lambda))\frac{H}{H-B}\frac{D}{2} $$ where the weight is taken from the right tail of the logit transformation $$ w(H,\lambda)=2-2\frac{\exp\left( \frac{H-B}{\exp(\lambda)}\right)}{1+\exp\left( \frac{H-B}{\exp(\lambda)}\right)} $$

Parameter uncertainty is reported because the same realized errors are used always when a model based on certain model fitting data is used; therefore those errors behave in practice like bias. Variance for total volume is computed as sum of all elements of the variance-covariance matrix of prediction errors of the mean.

References

Kangas A., Pitkanen T., Mehtatalo L., Heikkinen J. (xxxx) Mixed linear and non-linear tree volume models with regionally varying parameters

Examples

# NOT RUN {
library(lmfor)
data(treevol)

treevol$formfactor<-treevol$v/volvff(treevol$dbh,treevol$h,logita=100,lambda=log(0.2))
treevol$logitff<-log((treevol$formfactor)/(1-(treevol$formfactor)))

ptrees<-treevol[treevol$species=="pine",]
mod.init<-lm(logitff~I(1/h)+h+dbh+I(h*dbh)+I(1/(h*dbh))+
                     dataset+dataset:dbh+dataset:h,data=ptrees)

mod<-nlme(v~volvff(dbh,h,logita=logita,lambda=lambda),
         fixed=list(logita~I(1/h)+h+dbh+I(h*dbh)+I(1/(h*dbh))+dataset+
                           dataset:dbh+dataset:h+soil+temp_sum,
                           lambda~1),
         random=logita~1|stand/plot,
         start=c(coef(mod.init),rep(0,2),log(0.2)),
         data=ptrees,
         weights=varComb(varIdent(form=~1 |dataset),varPower()),
         method="ML",
#         control=list(msVerbose=TRUE),
#         verbose=TRUE
)

pred1<-predvff(ptrees,mod,varMethod="simul",biasCorr="integrate") 
pred1$totvol    
pred1$totvolvar
pred1$totvolci         
head(attributes(pred1)$trees)    

pred2<-predvff(ptrees,mod,varMethod="taylor",biasCorr="twopoint") 
pred2$totvol    
pred2$totvolvar
pred2$totvolci         
head(attributes(pred2)$trees)   
# }