We will show a few patterns commonly used with BEAST 2, illustrating how the MCMC framework can be exploited to write efficient models. The way BEAST 2 classes are based on BEAST-objects has the advantage that it does automatically define a fairly readable form of XML and allows automatic checking of a number of validation rules. The validation helps in debugging models. These advantages are based on Java introspection and there are a few peculiarities due to the limitations of Java introspection which can lead to unexpected behaviour. These issues will be highlighted in this chapter.

We start with some basic patterns for BEAST-objects, inputs and the core StateNode and CalulationNode BEAST-objects, and how to write efficient versions of them. We also show a number of the most commonly used BEAST-objects from the evolution library and how to extend them. Finally, there are some tips and a list of common errors that one should be aware of.

Basic patterns

First, we have a look at some basic patterns.

14.1.1 Basic BEAST-object layout

Box 14.1 shows the layout of most BEAST-objects that you will find in the BEAST code. We all love to have documented code, so it starts with a Description annotation, typically a one-line comment on the function of the BEAST-object, but multiline descriptions are fine as well. The Description is used in documentation and in online help in GUIs like BEAUti. Omitting such a description leads to failure of the DocumentationTest. This does not mean that further Java comments are not allowed or necessary, but the description does help in documenting classes for code writers as well.

Every BEAST-object implements BEASTInterface. BEASTObject is a base implementation of BEASTInterface and many BEASTObjects extend the BEASTObject class. By implementing BEASTInterface, services that use introspection, like validation of models, are automatically provided. To specify an input for a BEAST-object, just declare an Input member. Input is a template class, so the type of input can be specified to make sure that when Inputs are connected to BEAST-objects the correct type of BEAST-object is used.