Chapter 5 Advanced Features of AD Model Builder

Section 1 Using other class libraries in AD Model Builder programs

A useful feature of C++ is its open nature. This means that the user can combine several class libraries into one program. In general this simply involves including the necessary header files in the program and then declaring the appropriate class instances in the program. Instances of external classes can be declared in AD Model Builder program in several ways. They can always be declared in the procedure or report section of the program as local objects. It is sometimes desired to include instances of external classes in a more formal way into an AD Model Builder program. This section describes how to include them into the DATA_SECTION or PARAMETER_SECTION. After that they can be referred to as though they were part of the AD Model Builder code (except for the technicalities to be discussed below).

AD Model Builder employs a strategy of late initialization of class members. The reason for this is to allow time for the user too carry out any calculations which may be necessary for determining parameter values etc. which are used in the initializatin of the object. Because of the nature of constructors in C++ this means that every object declared in the DATA_SECTION or the PARAMETER_SECTION must have a default constructor which takes no arguments. The actual allocation of the object is carried out by a class member function named allocate which takes any desired arguments. Since external classes will not generally satisfy these requirments a different strategy is employed for these classes. A pointer to the object is included in the appropriate AD Model Builder class. This pointer has the prefix pad_ inserted before the name of the object. The pointer to myobj would have the form pad_myobj.


 !!CLASSfooclass myobj( .... )

The user can refer to the object in the code simply by using its name.

Section 2 Appendix 1 -- The regression function

The robust_regression function calculates the log-likelihood function for the standard statistical model of independent normally distributed errors with mean 0 and equal variance. The code is written in terms of Autodif objects such as dvariable and dvar_vector. They are described in the Autodif User's Manual.


dvariable regression(const dvector& obs,const dvar_vector& pred)
{
  double nobs=double(size_count(obs));  // get the number of
                                        // observations
  dvariable vhat=norm2(obs-pred);  // sum of squared deviations
  vhat/=nobs;                      //mean of squared deviations
  return (.5*nobs*log(vhat));     //return log-likelihood value
}

Section 3 Appendix 2 -- AD Model Builder types

The effect of a declaration depends on whether it occurs in the DATA_SECTION or in the PARAMETER_SECTION. Objects declared in the DATA_SECTION are constant, that is like data. Objects declared in the PARAMETER_SECTION are variable, that is like the parameters of the model which are to be estimated. Any objects which depend on variable objects must themselves be variables objects, that is they are declared in the PARAMETER_SECTION and not in the DATA_SECTION.

In the DATA_SECTION the prefix init_ indicates that the object is to be read in from the data file. In the PARAMETER_SECTION the prefix indicates that the object is an initial parameter whose value will be used to calculate the value of other (non initial) parameters. In the PARAMETER_SECTION initial parameters will either have their values read in from a parameter file or will be initialized with their default initial values. The actual default values used can be modified in the INITIALIZATION_SECTION. From a mathematical point of view objects declared with the init_ prefix are independent variables which are used to calculate the objective function being minimized.

The prefixes bounded_ and dev_ can only be used in the PARAMETER_SECTION. The prefix bounded_ restricts the numerical values which an object can take on to lie in a specified bounded interval. The prefix dev_ can only be applied to the declaration of vector objects. It has the effect of restricting the sum of the individual components of the vector object to sum to 0.

The prefix sdreport_ can only be used in the PARAMETER_SECTION. An object declared with this prefix will appear in the covariance matrix report. This provides a convenient method for obtaining estimates for the variance of any parameter which may be of interest. Note that the prefixes sdreport_ and init_ can not both be applied to the same object. There is no need to do so since initial parameters are automatically included in the standard deviations report. AD Model Builder also has three and four dimensional arrays. They are declared like


3darray dthree(1,10,2,20,3,10)
4darray df(1,10,2,20,3,10)
init_3darray dd(1,10,2,20,3,10)    // data section only
init_4darray dxx(1,10,2,20,3,10)   // data section only

The following table contains a summary of declarations and the types of objects associatated with them in AD Model Builder. The types dvariable, dvector, dmatrix, d3_array, dvar_vector, dvar_matrix, and dvar3_array are are described in the AUTODIF Users's manual.

Section 4 References

Bard, Yonathan. Nonlinear Parameter Estimation. Academic Press. N.Y. 1974

Gelman, Andrew., John B. Carlin, Hal S. Stern, and Donald B. Rubin. Bayesian Data Analysis. Chapman and Hall.

Hilborn, Ray and Carl Walters. Quantitative Fisheries Stock Assessment and Management: Choice, Dynamics, and Uncertainty. 1992.

Section 5 How to order AD Model Builder

AD Model Builder bundled with Autodif is available for a wide variety of compilers on 80386 computers including Borland C++, Zortech (Symantec) C++, Visual C++ (32 bit) and the ``GNU'' C++ compiler DJGPP Other compilers are supported at present on SUN, HP, and SGI UNIX workstations. It is important that you tell us the exact form of your hardware and version of your compiler. Multi-user and site licenses are available. Contact Otter Research Ltd

PO Box 265, Station A

Nanaimo, B.C. V9R 5K9 Canada Voice or Fax (250)-756-0956 Email otter@island.net

Internet: otter-rsch.com