Revision 400 trunk/test/priors/priors_user_guide.txt
priors_user_guide.txt (revision 400)  

1 
added feature of PRIOR_SECTION and LIKELIHOOD_SECTION for admb


1 
ADMB new feature: Prior and likelihood section


2  2  
3 
the section definition can be PRIOR_SECTION or PRIORS_SECTION, LIKELIHOOD_SECTION or LIKELIHOODs_SECTION. the user can choose to use any of these section, which allowed to be put before procedure_section, if you choose to use both of them, the basic order will be priors section, likelihood section, and procedure section. For random effect model, the preliminary calcs section only be allowed after likelihood section and before procedure section. Also for random effect, there are other limits too, one is the initialzation section should be before parameter section if you use it, the runtime section only can be put after either the report section or preliminary section, I suggest you put after the report section. 

4  3  
5 
adding the priors and likelihood sections was aim at help converting the winbugs model to admb. So the basic format is x ~ dnorm(mu,sigma); you can have any spaces between the ~ and within the argument lists. here the dnorm is just any function name which taken on log scale of the distribution, admb will provide some, you can has your own function. One thing need notice is when you define your own function or use admb provide dnorm here, the first argument of actual function will be put on the left side of ~, all the remaining will be on right side of ~, such as your real function dnorm(x, mu,sigma), when you use ~, the first argument x will be on the left side of ~, the right side of ~ will be dnorm(mu,sigma), it no need to be x, but should has the same data type as x. 

6  4  
7 
The priors, likelihood sections allow to use any valid c++ code inside, so don't forget the ; at the end of line except the if,else, while, for etc, and make sure they are valid c++ code. We will constrain the use of prior section only for parameters which are prefix init_ from parameter section, if not it will throw the warning. For the likelihood section, we constrain the use for constant data type, which from data_section only. If not, it throws the warning. It is just warning, will not affect your final results. Other than that, we move one step further, now we also allow ~ being used in the procedure section. So technically speaking, you can just use ~ inside the procedure section, and leave out the prior and likelihood section if you don't want to use them. We also initialize the objective function value as 0 at the beginning of the procedure section, so you don't need to reinitialize, although it is not harm if you still want to do so. Remember every ~ you defined will be count into the objective function automatically, so use with some caution.


5 
The priors and likelihood sections was aim at help converting the winbugs model to admb. So the basic format is the same as winbugs x ~ dnorm(mu,sigma); You can have any spaces between the ~ and within the argument lists. Here the dnorm is just any function name which taken on log scale of the distribution, admb will provide some, you can has your own function or use the contribute library in contrib folder. One thing need notice is the first argument of actual function will be put on the left side of ~, all the remaining will be on right side of ~, such as your real function definition dnorm(x, mu,sigma), when you use ~, the first argument x will be on the left side of ~, the right side of ~ will be dnorm(mu,sigma), it doesn?t need to be x, but should has the same data type as x.


8  6  
9 
we also defined two variables, prior_function_value and likelihood_function_value, each sum up the negative log likelihood function value for their section, and will be added to objective function value. Actually these two sections(including any C++ code there) will be appended at the end of procedure section. You can get the value by referring the above name in your report section, such as report<<prior_function_value<<endl;


7 
The section definition can be PRIOR_SECTION or PRIORS_SECTION, LIKELIHOOD_SECTION or LIKELIHOODS_SECTION. The user can choose to use any of these section, which allowed to be put before procedure_section, if you choose to use both of them, the basic order will be priors section, likelihood section, and procedure section. For random effect model, the preliminary_calcs section only be allowed after likelihood section and before procedure section. Also for random effect, there are other limits too, one is the initialization section should be before parameter section if you use it, the runtime section only can be put after either the report section or preliminary section, I suggest you put after the report section.


10  8  
11 
To avoid the layout trouble of different sections, I would suggest you follow this order for random effect model, Data section, initialziation, parameter, priors, likelihood, preliminary, procedure, [separable function, function section,] between phase section, report section, [runtime section, final section, top of main, global section]. there is no order for sections within [], and the last two also can be put in the very top before data section.


9 
The priors, likelihood sections allow to use any valid c++ code inside, it is like procedure_section, so don't forget the ; at the end of line except the if,else, for, while etc, and make sure they are valid c++ code. We will constrain the use of prior section only for parameters which are prefix init_ from parameter section. For the likelihood section, we constrain the use for constant data type, which from data_section only. If not, it throws the warning. But it is just remind warning, will not affect your final results. We also initialize the objective function value as 0 at the beginning of the procedure section, so you don't need to reinitialize, although it is not harm if you still want to do so. Remember every ~ you defined will be count into the objective function automatically, so use with some caution.


12  10  
13 
for regular model, there is not much limit on the order, basically you follow data, parameter, priors, likelihood, procedure,report section, you can put initialization around the parameter, preliminary around the priors or likelihood, all other sections can be put almost anywhere.


11 
We also defined two variables, prior_function_value and likelihood_function_value, each sum up the negative log likelihood function value for their respective section, and will be added to objective function value automatically. Actually these two sections (including any C++ code there) will be appended at the end of procedure section. You can get the value by referring the above name in your report section, such as report<<prior_function_value<<endl;


14  12  
13 
To avoid the layout trouble of different sections, I would suggest you follow this order for random effect model, data section, initialization, parameter, priors, likelihood, preliminary, procedure, [separable function, function section,] between phase section, report section, [runtime section, final section, top of main, global section]. There is no order for sections within [ ], and the last two also can be put on the very top before data section. 

14  
15 
For regular model, there is not much limit on the order, basically you follow data, parameter, priors, likelihood, procedure, report section, you can put initialization around the parameter, preliminary around the priors or likelihood, all other sections can be put almost anywhere. 

16 
Also available in: Unified diff