Loading experiments

This page explains how to load experiments from PhyloData.

What is an experiment?

An experiment is a Bayesian phylogenetic analysis that has been conducted as part of a publication. It consists of a bunch of files (like BEAST2 XML files, BEAST2 log files, trees, etc.) and metadata (like the title of the paper, the authors, the species investigated, etc.). Check out an example experiment to get an idea of what an experiment looks like.

For now, it is important to know that each experiment has a unique ID (like munro-2019-climate-6tvf) and a version number (like 1). The version number is incremented every time the experiment is updated.

Loading an experiment

We use the ExperimentLoader class to load an experiment from PhyloData.

There are multiple possibilities when it comes to loading an experiment, let’s go through them one by one.

Specifying the experiment to load

The simplest way to load an experiment is to specify the ID and version:

PaperWithExperiment experiment = new ExperimentLoader(
    "munro-2019-climate-6tvf", 1
).load();

You always have to specify the version of the experiment to load. This ensures that you get the same results even if the experiment is updated.

Where are the files stored?

By default, the experiment files are stored in a folder called data in the current working directory. If you want to specify a different directory, you can do so as follows:

PaperWithExperiment experiment = new ExperimentLoader(
    "munro-2019-climate-6tvf", 1
).intoDirectory(Paths.get("some/other/folder")).load();

PhyloData will only download the files if they don’t already exist. Simply put the loadExperiment method call at the beginning of your program; it won’t download the files more than once.

Only download some files

In some cases, you might only be interested in a subset of the files. You can restrict the downloaded files by specifying file names:

PaperWithExperiment experiment = new ExperimentLoader(
    "munro-2019-climate-6tvf", 1
).restrictFileNames(
    "Meta.subset1.trim1.ingroup.B.xml",
    "Meta.subset1.trim1.ingroup.B.10K.pruned.trees"
).load();

Alternatively, you can only download files of a certain type:

PaperWithExperiment experiment = new ExperimentLoader(
    "munro-2019-climate-6tvf", 1
).restrictFileTypes(
    File.FileType.POSTERIOR_TREES,
    File.FileType.SUMMARY_TREE
).load();

You can choose from the following file types: File.FileType.BEAST2_CONFIGURATION, File.FileType.BEAST2_POSTERIOR_LOGS, File.FileType.POSTERIOR_TREES, File.FileType.SUMMARY_TREE, File.FileType.UNKNOWN.

Only fetch the metadata

If you only want to fetch the metadata of an experiment, you can use the restrictFileNames method without any arguments:

PaperWithExperiment experiment = new ExperimentLoader(
    "munro-2019-climate-6tvf", 1
).restrictFileNames().load();

All possible options

The most general ExperimentLoader.loadExperiment method allows you to combine all the above options:

PaperWithExperiment experiment = new ExperimentLoader(
    "munro-2019-climate-6tvf", 1
)
    .intoDirectory(Paths.get("some/other/folder"))
    .restrictFileNames("Meta.subset1.trim1.ingroup.B.10K.pruned.trees")
    .restrictFileTypes(File.FileType.POSTERIOR_TREES)
    .preferPreview()
    .forceDownload()
    .citationsInto(Paths.get("some/citations.bib"))
    .load();

Loading multiple experiments

You can also load multiple experiments at once with the ExperimentsLoader class. It behaves exactly like the ExperimentLoader class:

List<PaperWithExperiment> experiments = new ExperimentsLoader(
	new ExperimentToLoad("nen-2019-postglacial-qh0e", 1),
	new ExperimentToLoad("nen-2019-postglacial-n1bf", 1)
).load();

This will return a list of PaperWithExperiment objects. The ExperimentsLoader class supports the same options as ExperimentLoader.