Dmean                 package:nlreg                 R Documentation

_D_i_f_f_e_r_e_n_t_i_a_t_e _t_h_e _M_e_a_n _F_u_n_c_t_i_o_n _o_f _a _N_o_n_l_i_n_e_a_r _M_o_d_e_l

_D_e_s_c_r_i_p_t_i_o_n:

     Calculates the gradient and Hessian of the mean function of a 
     nonlinear heteroscedastic model.

_U_s_a_g_e:

     Dmean(nlregObj, hessian = TRUE)

_A_r_g_u_m_e_n_t_s:

nlregObj: a nonlinear heteroscedastic model fit as obtained from a call
          to 'nlreg'.   

 hessian: logical value indicating whether the Hessian should be
          computed.   The default is 'TRUE'. 

_D_e_t_a_i_l_s:

     The mean function is differentiated with respect to the regression
      coefficients as specified in the 'coef' component of the  'nlreg'
     object.  The returned function definition, however,  includes all
     parameters - regression coefficients and variance  parameters - as
     arguments.  When evaluated, it implicitly refers  to the data to
     whom the model was fitted and which must be on the  search list. 
     The gradient and Hessian are calculated for each data point: the
     'gradient' attribute is a  _n x p_ matrix and the 'hessian' 
     attribute is a _n x p x p_ array,  where _n_ and _p_ are
     respectively the  number of data points and the number of
     regression coefficients.

_V_a_l_u_e:

     a function whose arguments are named according to the parameters
     of the nonlinear model 'nlregObj'.  When evaluated, it returns the
     value of the mean function along with attributes called 
     'gradient' and 'hessian', the latter if requested.  These  are the
     gradient and Hessian of the mean function with respect to the 
     regression coefficients.

_N_o_t_e:

     'Dmean' and 'Dvar' are the two workhorse functions of the 'nlreg'
     library.  The details are given in Brazzale  (2000, Section
     6.1.2).

     The symbolic differentiation algorithm is based upon the 'D'
     function.  As this algorithm is highly recursive, the 'hessian =
     TRUE' argument should only be used if the Hessian matrix is
     needed.  Whenever possible, derivatives should be stored so as to
     be re-used in further calculations.  This is, for instance,
     achieved by the nonlinear heteroscedastic model fitting routine
     'nlreg' through the argument  'hoa = TRUE'.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language: A Programming Environment for Data Analysis and 
     Graphics_.  London: Chapman & Hall.  Section 9.6.

     Brazzale, A. R. (2000) _Practical Small-Sample Parametric 
     Inference_.  Ph.D. Thesis N. 2230, Department of Mathematics,
     Swiss Federal Institute of Technology Lausanne.

_S_e_e _A_l_s_o:

     'Dvar', 'nlreg.object', 'deriv3', 'D'

_E_x_a_m_p_l_e_s:

     library(boot)
     data(calcium)
     calcium.nl <- nlreg( cal ~ b0*(1-exp(-b1*time)), 
                          start = c(b0 = 4, b1 = 0.1),  data = calcium )
     Dmean( calcium.nl )
     ##function (b0, b1, logs)
     ##{
     ##    .expr3 <- exp(-b1 * time)
     ##    .expr4 <- 1 - .expr3
     ##    .expr6 <- .expr3 * time
     ##    .value <- b0 * .expr4
     ##    .grad <- array(0, c(length(.value), 2), list(NULL, c("b0",
     ##        "b1")))
     ##    .hessian <- array(0, c(length(.value), 2, 2), list(NULL,
     ##        c("b0", "b1"), c("b0", "b1")))
     ##    .grad[, "b0"] <- .expr4
     ##    .hessian[, "b0", "b0"] <- 0
     ##    .hessian[, "b0", "b1"] <- .hessian[, "b1", "b0"] <- .expr6
     ##    .grad[, "b1"] <- b0 * .expr6
     ##    .hessian[, "b1", "b1"] <- -(b0 * (.expr6 * time))
     ##    attr(.value, "gradient") <- .grad
     ##    attr(.value, "hessian") <- .hessian
     ##    .value
     ##}
     ##
     param( calcium.nl )
     ##        b0         b1       logs
     ## 4.3093653  0.2084780 -1.2856765
     ##
     attach( calcium )
     calcium.md <- Dmean( calcium.nl )
     attr( calcium.md( 4.31, 0.208, -1.29 ), "gradient" )
     ##              b0       b1
     ## [1,] 0.08935305 1.766200
     ## [2,] 0.08935305 1.766200
     ## [3,] 0.08935305 1.766200
     ## [4,] 0.23692580 4.275505
     ## ...
     detach()

