2 Syntax description

2.1 Calling the programs and writing the option files.

The programs in the Bio++ Program Suite are command line-driven. Arguments may be passed as parameter=value options, either directly to the command line or using an option file:

{program} parameter1=value1 parameter2=value2 ... parameterN=valueN

or

{program} param=option_file

where {program} is the name of the program to use (bppml, bppseqgen, etc.). Option files contain parameter=value lines, with only one parameter per line. They can be written from scratch using a regular text editor, but since these files can potentially turn to be quite complex, it is probably wiser to start with a sample provided along with the program (if any!).

Extra-space may be included between parameter names, equal sign and value:

first_parameter   = value1
second_parameter  = value2

and lines can be broken using the backslash character:

parameter = value1,\
            value2,\
            value3

Comment may be included, in either scripting format:

# This is a comment

C format:

/* This is a comment
*/

or C++ format:

// This is a comment

Command line and file options may be combined:

{program} param=option_file parameterX=valueX

In case parameterX is specified in both option file and command line, the command line value will be used. This allows to run the programs several times by changing a single option, like the name of the data set for instance.

Option files can be nested, by using param=nestedoptionfile within an option file, as with the command line. It is possible to use this option as often as needed, this will load all the required option files.

2.2 Different types of options

The next chapters describe the whole set of options available in BppSuite. For each parameter, the type of parameter value expected is defined as:

{chars}

A character chain

{path}

A file path, which may be absolute or related to the current directory

{int}

An integer

{int}, {int>0}, {int>=0}, {int[2,10]}

An integer, a positive integer, a positive non-null integer, an integer falling between 2 and 10

{real}, {real>0}, etc

A real number, a positive real number, etc.

{boolean}

A Boolean value, which may be one of ’yes’, ’no’, ’true’ or ’false’

{xxx|yyy|zzz}

A set of allowed values

{list<type>}

A list of values of specified type, separated by comas.

If an option availability or choice depends on another parameters, it will be noted as

parameter1={xxx|yyy|zzz}

parameter2={chars} [[parameter1=zzz]]

meaning that parameter2 is available only if parameter1 is set to ’zzz’.

Any optional argument will be noted within hooks [].

In some cases, the argument value is more complexe and follows the ’keyval’ syntax. This syntax will be quite familiar for users using languages like R, Python, or certain LaTeX packages. A keyval procedure is a name that does no contain any space, together with some arguments within parentheses. The arguments take the form key=value, separated by comas:

parameter=Function(name1=value1, name2=value2)

Space characters are allowed around the ’=’ and ’,’ ponctuations.

2.3 Variables

It is possible to recall anywhere the value of an option by using $(parameter).

optimization.topology.algorithm = NNI
optimization.topology.algorithm_nni.method = phyml
output.tree.file = MyData_$(optimization.topology.algorithm)_$(optimization.topology.algorithm_nni.method).dnd

You can use this syntax to define global variables:

data=MyData
input.sequence.file=$(data).fasta
input.tree.file=$(data).dnd
output.infos=$(data).infos

Important note: it is not possible to use a macro with the ’param’ option. This is because all nested option files are parsed before the variable resolution. Writing param=$(model1).bpp will not work, but this allows the user to override variables in nested files, as with the command line. For instance:

#Option file 1:
param=options2.bpp
input.sequence.file=$(data).fasta
input.sequence.format=Fasta

#Option file 2:
data=LSU
#etc