=====
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 <https://www.cygwin.com/>`_.

Basic usage
-----------

Typical usage is to run:

::

	$ beastling my_config.conf

where "my_config.conf" is a valid BEASTling 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 as a second parameter:
	
::

        $ beastling my_config.conf my_output.xml

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

        $ beastling --overwrite my_config.conf my_output.xml

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

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?

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 :doc:`data`), or you can generate XML files directly from a Python script, using BEASTling as a library (see :doc:`scripting`).