Usage

BEASTling is a command-line tool, with no graphical interface. On Linux or OS X machines, it can be used from a terminal. On Windows machines, it can be run from the command prompt or, for a less painful experience, you can use cygwin.

You can get a brief explanation of the various options by running beastling --help or beastling -h, but these are discussed more fully below.

Basic usage

Typical usage is to run:

$ beastling my_config.conf

where “my_config.conf” is a valid BEASTling configuration file (see Configuration file to learn what goes in a configuration file). This will produce an XML file, whose name is determined by the “basename” parameter in the config file. Alternatively, the output filename can be specified explicitly using -o or --output:

$ beastling my_config.conf --output my_output.xml

If the my_output.xml file already exists and you want to overwrite it, use the --overwrite option:

$ beastling my_config.conf --output my_output.xml --overwrite

To write the XML output to stdout instead of a file, use - in place of an output filename:

$ beastling my_config.conf -

Running your analysis

Once you have your output XML file, you can get BEAST to run your analysis by simply running:

$ beast my_output.xml

Or you can load the XML file using BEAST’s graphical user interface if that’s what you are used to, just like an XML file produced by BEAUti

Sampling from the prior

If your analysis is working nicely and you’d like to sample from the prior distribution to make sure your results are really dependent upon your data, you don’t need to make a new config file! You can simply run BEASTling again using -p or --prior:

$ beastling --prior my_config.conf

This will create a separate XML file whose filename is formed by adding _prior to the end of whatever you have set “basename” too. Log files will also have _prior added to them, so you can run this analysis in the same directory as your posterior analysis without overwriting anything.

Verbose mode

If you run BEASTling in verbose mode, using either -v or --verbose, BEASTling will print messages while processing your configuration file. These messages will let you know of BEAST packages that your analysis depends upon, and of various decisions it makes which you may like to be aware of. For example:

$ beastling -v my_config.conf my_output.xml
[DEPENDENCY] ConstrainedRandomTree is implemented in the BEAST package BEASTLabs.
[DEPENDENCY] The Lewis Mk substitution model is implemented in the BEAST package "morph-models".
[INFO] Model "my_model": Trait f3 excluded because its value is constant across selected languages.  Set "remove_constant_features=False" in config to stop this.
[INFO] Model "my_model": Trait f6 excluded because there are no datapoints for selected languages.
[INFO] Model "my_model": Using 8 features from data file ./tests/data/basic.csv
[INFO] 5 languages included in analysis.

In future, BEASTling in verbose mode may also offer hints on hwo you can tweak your configuration to improve performance.

Generating reports

In addition to creating a BEAST XML file, BEASTling is also capable of simultaneously creating high-level, human-readable analysis reports. To generate these reports, include the --report option when running BEASTling. This will produce two files, my_config.md and my_config.geojson.

The my_config.md file contains Markdown-formatted text. This report briefly summarise things like which languages are included in the analysis and which families they come from, how many features from the datafiles are used and which substitution models have been applied, calibration dates which have been applied, and more. The my_config.geojson file is a GEOJson file which encodes the location of all the languages in your analysis.

If you keep your BEASTling configuration file and the generated reports in a GitHub repository, then when you view the reports GitHub will automatically render the Markdown into nicely formatted text, and will automatically render the GEOJson as a zoomable, pannable world-map, where languages are colour-coded by family. This is probably the quickest and easiest way to view the reports, and it makes it super simple to share your work with others by sending around the URLs for these reports. People who have no idea how to read BEAST XML files or even BEASTling configuration files can look at these two reports and immediately understand the high-level details of what you are doing. Besides, you were alreay going to put your data and configuration on GitHub anyway, right, so your fellow scientists can reproduce your results and easily run their own modifications?

Generating language lists

BEASTling permits you to analyse only a subset of the languages in your data file, by specifying a particular set of families or subfamilies, or geographic macroareas, or by insisting that languages have non-missing data for at least some proportion of the features. As such, you might not actually know exactly which languages will end up being included in an analysis when all these options are applied. If you run BEASTling with the --language-list option then in addition to the XML file (and in addition to the high-level report if you specified --report), BEASTling will produce a text file called my_config_languages.txt. This file will list all of the languages included in the analysis, one language per line.

Extracting configurations from XMLs

If you have a pre-existing BEAST XML file which was generated by BEASTling, then you can use the --extract option to extract the original configuration file and, if embed_data was enabled in that configuration file, any data files. This makes it extremely easy to start experimenting with variations on a published analysis. Note that --extract will not overwrite existing files unless --overwrite is specified.

Advanced stuff

These usage patterns will cover the vast majority of uses of BEASTling. If you’re feeling funky, you can read the linguistic data from stdin instead of a .csv file (see Data formats), or you can generate XML files directly from a Python script, using BEASTling as a library (see Scripting BEASTling).