mcbette

mcbette: model comparison using babette - Published in JOSS (2020)

https://github.com/ropensci/mcbette

Scientific Fields

Engineering Computer Science - 60% confidence

Last synced: 6 months ago · JSON representation

Repository

Model Comparison using babette

Basic Info

Host: GitHub
Owner: ropensci
License: gpl-3.0
Language: R
Default Branch: master
Size: 26.7 MB

Statistics

Stars: 7
Watchers: 3
Forks: 3
Open Issues: 3
Releases: 17

Created about 7 years ago · Last pushed about 1 year ago

Metadata Files

Readme Changelog Contributing License Codemeta

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# mcbette


[![peer-review](https://badges.ropensci.org/360_status.svg)](https://github.com/ropensci/software-review/issues/360)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.02762/status.svg)](https://doi.org/10.21105/joss.02762)

Branch   |[![GitHub Actions logo](man/figures/GitHubActions.png)](https://github.com/ropensci/mcbette/actions) |[![Codecov logo](man/figures/Codecov.png)](https://www.codecov.io)
---------|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------
`master` |![R-CMD-check](https://github.com/ropensci/mcbette/workflows/R-CMD-check/badge.svg?branch=master)    |[![codecov.io](https://codecov.io/github/ropensci/mcbette/coverage.svg?branch=master)](https://codecov.io/github/ropensci/mcbette?branch=master)
`develop`|![R-CMD-check](https://github.com/ropensci/mcbette/workflows/R-CMD-check/badge.svg?branch=develop)   |[![codecov.io](https://codecov.io/github/ropensci/mcbette/coverage.svg?branch=develop)](https://codecov.io/github/ropensci/mcbette?branch=develop)



![](man/figures/mcbette_logo.png)

`mcbette` allows for doing a Model Comparison using `babette` (hence the name),
that is, given a (say, DNA) alignment, it compares multiple phylogenetic inference 
models to find the model that is likeliest to generate that alignment.
With this, one can find the phylogenetic inference model that is
simple enough, but not too simple.

To do so, `mcbette` uses `babette` [Bilderbeek and Etienne, 2018] with the addition
of using the BEAST2 [Bouckaert et al., 2019] nested sampling package
as described in [Russell et al., 2019].

## Installation

:warning: `mcbette` only works on Linux and Mac.

`mcbette` depends on the [rJava](https://cran.r-project.org/package=rJava) 
and [Rmpfr](https://cran.r-project.org/package=Rmpfr) packages.

On Linux, to install these, do (as root):

```
apt install r-cran-rjava libmpfr-dev
```

After this, installing `mcbette` is rather easy:

```r
install.packages("mcbette")
remotes::install_github("richelbilderbeek/beastierinstall")
beastierinstall::install_beast2()
remotes::install_github("richelbilderbeek/mauricerinstall")
mauricerinstall::install_beast2_pkg("NS")
```

Note that `mcbette` uses the non-CRAN extensions 
[beastierinstall](https://github.com/richelbilderbeek/beastierinstall) 
and [mauricerinstall](https://github.com/richelbilderbeek/mauricerinstall) 
to install and uninstall BEAST2 and its packages.

## Example

```{r load_mcbette}
library(mcbette)
```

Suppose we have a DNA alignment, obtained by sequencing multiple
species:

```{r example_alignment}
fasta_filename <- beautier::get_beautier_path("anthus_aco_sub.fas")
ape::image.DNAbin(ape::read.FASTA(fasta_filename))
```

Note that this alignment holds too little information to really base
a publishable research on.

To create a posterior distribution of phylogenies from this alignment,
one needs to specify an inference model. An inference model 
is (among others) a combination of a site model, clock model and tree 
model. See the 'Available models' section to see the available models.

In this example we let two inference models compete.

Here is the default inference model:

```{r example_inference_model_1}
inference_model_1 <- beautier::create_ns_inference_model()
message(
  paste(
    inference_model_1$site_model$name,
    inference_model_1$clock_model$name,
    inference_model_1$tree_prior$name
  )
)
```

The JC69 site model assumes that the four DNA nucleotides are equally
likely to mutate from/to. The strict clock model assumes that mutation
rates of all species are equal. The Yule tree model assumes that new
species form at a constant rate for an extinction rate of zero.

The competing model has a different site, clock and tree model:

```{r example_inference_model_2}
inference_model_2 <- inference_model_1
inference_model_2$site_model <- beautier::create_hky_site_model()
inference_model_2$clock_model <- beautier::create_rln_clock_model()
inference_model_2$tree_prior <- beautier::create_bd_tree_prior()
```

The HKY site model assumes that DNA substitution rates differ between
transitions (purine-to-purine or pyrimidine-to-pyrimidine) and 
translations (purine-to-pyrimidine or the other way around).
The relaxed log-normal clock model assumes that mutation
rates of all species are differ, where all these rates together follow
a log-normal distribution. 
The birth-death tree model assumes that new
species form and go extinct at a constant rate.

`mcbette` shows the evidence (also called marginal likelihood)
for each inference model, which is the likelihood that a model
has generated the data.

```{r example_est_marg_liks, cache=TRUE}
if (can_run_mcbette()) {
  marg_liks <- est_marg_liks(
    fasta_filename = fasta_filename,
    inference_models = list(inference_model_1, inference_model_2)
  )
}
```

Here we display the marginal likelihoods as a table:

```{r marg_liks_as_table}
if (can_run_mcbette()) {
  knitr::kable(marg_liks)
}
```

The most important result are the model weights.
When a model's weight is very close to one, 
one would prefer to use that inference model in doing a Bayesian inference.
If these model weights are rather similar, one could argue to use either
model. 

Here we display the marginal likelihoods as a barplot:

```{r plot_marg_liks}
if (can_run_mcbette()) {
  plot_marg_liks(marg_liks)
}
```

## Available models

The available site models:

```{r}
beautier::get_site_model_names()
```

The available clock models:

```{r}
beautier::get_clock_model_names()
```

The available tree models:

```{r}
beautier::get_tree_prior_names()
```

## Documentation

 * The mcbette vignette
 * [rOpenSci blog post: Call BEAST2 for Bayesian evolutionary analysis from R](https://ropensci.org/blog/2020/01/28/babette/)
 * [rOpenSci blog post: Selecting the Best Phylogenetic Evolutionary Model](https://ropensci.org/blog/2020/12/01/mcbette-selecting-the-best-inference-model/)

## FAQ

### Under which platforms does `mcbette` work?

`mcbette` only works on Linux and Mac, because BEAST2 package management
only works on those platforms.

### How do I let mcbette compare all models?

First, this is impossible, as there are infinitely many inference
models possible.

```{r}
inference_models <- list()
i <- 1
for (site_model in beautier::create_site_models()) {
  for (clock_model in beautier::create_clock_models()) {
    for (tree_prior in beautier::create_tree_priors()) {
      inference_models[[i]] <- beautier::create_ns_inference_model(
        site_model = site_model,
        clock_model = clock_model,
        tree_prior = tree_prior
      )
      i <- i + 1
    }
  }
}
```

Now, `inference_models` holds a list of inference models, to be used
with `mcbette::est_marg_liks`.

### `Error: dir.exists(examples_folder) is not TRUE`

Currently, this line gives a suboptimal error message:

```
beastier::get_beast2_example_filename("Primates.nex")
```

The error message is:

```
Error: dir.exists(examples_folder) is not TRUE
```

The error message it should display is:

```
Error: BEAST2 examples folder not found at path '[path]'.
Maybe BEAST2 is not installed? 
Tip: run 'beastier::install_beast2()'
```

This will be added in a future version of `beastier`.

## Using an existing BEAST2 installation

When BEAST2 is already installed, yet at a non-default location,
one can use the `beast2_bin_path` argument in
`create_mcbette_beast2_options`.

## Code of conduct

Please note that this package is released with a [Contributor
Code of Conduct](https://ropensci.org/code-of-conduct/). 
By contributing to this project, you agree to abide by its terms.

## Links

 * ['mcbette' CRAN page](https://CRAN.R-project.org/package=mcbette)

## References

 * Bilderbeek, Richel JC, and Rampal S. Etienne. "babette: BEAUti 2, BEAST 2 and Tracer for R." Methods in Ecology and Evolution (2018). https://doi.org/10.1111/2041-210X.13032
 * Bouckaert R., Vaughan T.G., Barido-Sottani J., Duchêne S., Fourment M., Gavryushkina A., et al. (2019) BEAST 2.5: An advanced software platform for Bayesian evolutionary analysis. PLoS computational biology, 15(4), e1006650.
 * Russel, Patricio Maturana, et al. "Model selection and parameter inference in phylogenetics using nested sampling." Systematic biology 68.2 (2019): 219-233.

```{r cleanup_at_end}
beastier::remove_beaustier_folders()
beastier::check_empty_beaustier_folders()
```

Owner

Name: rOpenSci
Login: ropensci
Kind: organization
Email: info@ropensci.org
Location: Berkeley, CA

Website: https://ropensci.org/
Twitter: rOpenSci
Repositories: 307
Profile: https://github.com/ropensci

JOSS Publication

mcbette: model comparison using babette

Published

October 26, 2020

DOI

10.21105/joss.02762

Volume 5, Issue 54, Page 2762

Authors

Richèl J.c. Bilderbeek

Theoretical & Evolutionary Community Ecology, TRES, GELIFES, University of Groningen

Editor

Kristen Thyng

CodeMeta (codemeta.json)

{
  "@context": [
    "https://doi.org/10.5063/schema/codemeta-2.0",
    "http://schema.org"
  ],
  "@type": "SoftwareSourceCode",
  "identifier": "mcbette",
  "description": "'BEAST2' (<https://www.beast2.org>) is a widely used\n    Bayesian phylogenetic tool, that uses DNA/RNA/protein data\n    and many model priors to create a posterior of jointly estimated \n    phylogenies and parameters.\n    'mcbette' allows to do a Bayesian model comparison over some\n    site and clock models, \n    using 'babette' (<https://www.github.com/ropensci/babette>).",
  "name": "mcbette: Model Comparison Using 'babette'",
  "codeRepository": "https://github.com/ropensci/mcbette",
  "issueTracker": "https://github.com/ropensci/mcbette/issues",
  "license": "https://spdx.org/licenses/GPL-3.0",
  "version": "1.8.4",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 3.6.3 (2020-02-29)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Richèl J.C.",
      "familyName": "Bilderbeek",
      "email": "richel@richelbilderbeek.nl",
      "@id": "https://orcid.org/0000-0003-1107-7049"
    }
  ],
  "contributor": {},
  "copyrightHolder": {},
  "funder": {},
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Richèl J.C.",
      "familyName": "Bilderbeek",
      "email": "richel@richelbilderbeek.nl",
      "@id": "https://orcid.org/0000-0003-1107-7049"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "ape",
      "name": "ape",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ape"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "devtools",
      "name": "devtools",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=devtools"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggplot2"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "hunspell",
      "name": "hunspell",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=hunspell"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "lintr",
      "name": "lintr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=lintr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "nLTT",
      "name": "nLTT",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=nLTT"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "phangorn",
      "name": "phangorn",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=phangorn"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rappdirs",
      "name": "rappdirs",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rappdirs"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "spelling",
      "name": "spelling",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=spelling"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "stringr",
      "name": "stringr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=stringr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 2.1.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "tracerer",
      "name": "tracerer",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=tracerer"
    }
  ],
  "softwareRequirements": [
    {
      "@type": "SoftwareApplication",
      "identifier": "babette",
      "name": "babette",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=babette"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "beautier",
      "name": "beautier",
      "version": ">= 2.4",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=beautier"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "beastier",
      "name": "beastier",
      "version": ">= 2.2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=beastier"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "curl",
      "name": "curl",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=curl"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "mauricer",
      "name": "mauricer",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=mauricer"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "Rmpfr",
      "name": "Rmpfr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=Rmpfr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testit",
      "name": "testit",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testit"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "txtplot",
      "name": "txtplot",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=txtplot"
    }
  ],
  "releaseNotes": "https://github.com/ropensci/mcbette/blob/master/NEWS.md",
  "readme": "https://github.com/ropensci/mcbette/blob/master/README.md",
  "fileSize": "0KB",
  "contIntegration": [
    "https://travis-ci.org",
    "https://www.appveyor.com",
    "https://www.codecov.io",
    "https://travis-ci.org/ropensci/mcbette",
    "https://ci.appveyor.com/project/ropensci/mcbette",
    "https://codecov.io/github/ropensci/mcbette?branch=master",
    "https://travis-ci.org/ropensci/mcbette",
    "https://ci.appveyor.com/project/ropensci/mcbette",
    "https://codecov.io/github/ropensci/mcbette?branch=develop"
  ],
  "review": {
    "@type": "Review",
    "url": "https://github.com/ropensci/software-review/issues/360",
    "provider": "https://ropensci.org"
  }
}

GitHub Events

Total

Push event: 1

Last Year

Push event: 1

Committers

Last synced: 7 months ago

All Time

Total Commits: 717
Total Committers: 3
Avg Commits per committer: 239.0
Development Distribution Score (DDS): 0.017

Past Year

Commits: 0
Committers: 0
Avg Commits per committer: 0.0
Development Distribution Score (DDS): 0.0

Top Committers

Name	Email	Commits
richelbilderbeek	r**l@r**l	705
richelbilderbeek	r**k@g**m	10
Maëlle Salmon	m**n@y**e	2

Committer Domains (Top 20 + Academic)

richelbilderbeek.nl: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 42
Total pull requests: 3
Average time to close issues: 24 days
Average time to close pull requests: about 10 hours
Total issue authors: 5
Total pull request authors: 2
Average comments per issue: 2.67
Average comments per pull request: 2.0
Merged pull requests: 3
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 0
Pull requests: 1
Average time to close issues: N/A
Average time to close pull requests: 1 day
Issue authors: 0
Pull request authors: 1
Average comments per issue: 0
Average comments per pull request: 1.0
Merged pull requests: 1
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

richelbilderbeek (35)
thijsjanzen (4)
dksam (1)
cjwoodruff50 (1)
stefaniebutland (1)

Pull Request Authors

maelle (2)
olivroy (2)

Top Labels

Issue Labels

depends (2) medium (1) high (1)

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- cran 206 last-month
Total docker downloads: 48

Total dependent packages: 1
Total dependent repositories: 1
Total versions: 6
Total maintainers: 1

cran.r-project.org: mcbette

Model Comparison Using 'babette'

Homepage: https://github.com/ropensci/mcbette/
Documentation: http://cran.r-project.org/web/packages/mcbette/mcbette.pdf
License: GPL-3
Latest release: 1.15.3
published over 1 year ago

Versions: 6
Dependent Packages: 1
Dependent Repositories: 1
Downloads: 206 Last month
Docker Downloads: 48

Rankings

Forks count: 14.3%

Dependent packages count: 18.3%

Stargazers count: 19.4%

Average: 20.2%

Dependent repos count: 24.2%

Downloads: 24.9%

Maintainers (1)

rjcbilderbeek@gmail.com

Last synced: 6 months ago

mcbette

Science Score: 93.0%

Scientific Fields

Repository

Basic Info

Statistics

Metadata Files

README.Rmd

Owner

JOSS Publication

mcbette: model comparison using babette

Authors

Editor

Tags

CodeMeta (codemeta.json)

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

cran.r-project.org: mcbette

Rankings

Maintainers (1)

Dependencies