diff --git a/DESCRIPTION b/DESCRIPTION index 460f938..d97dd98 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,5 +1,5 @@ Package: jaatha -Version: 2.99.0.9224 +Version: 3.0.0 Date: 2015-12-02 License: GPL (>= 3) Title: Simulation-Based Maximum Likelihood Parameter Estimation @@ -7,11 +7,13 @@ Authors@R: c( person('Paul', 'Staab', , 'develop@paulstaab.de', role=c('aut', 'cre')), person('Lisha', 'Mathew', role=c('aut')), person('Dirk', 'Metzler', role=c('aut', 'ths')) ) -Description: A composite likelihood method for inferring evolutionary - parameters using genetic data. Given a model of the evolutionary history of - two biological populations as well as genetic data from multiple individuals - from each population, it estimates model parameters like the time of - separation of both species. +Description: Jaatha is an estimation method that can use computer simulations to + approximate maximum-likelihood estimates even when the likelihood function can not + be evaluated directly. It can be applied whenever it is feasible to conduct many + simulations, but works best when the data is approximately Poisson distributed. + Jaatha was originally designed for demographic inference in evolutionary + biology. It has optional support for conducting coalescent simulation using + the 'coala' package. URL: http://evol.bio.lmu.de/_statgen/software/jaatha BugReports: https://github.com/statgenlmu/jaatha/issues Imports: diff --git a/README.md b/README.md index 75855d5..1f853db 100644 --- a/README.md +++ b/README.md @@ -7,65 +7,79 @@ Jaatha ====== -Jaatha is a frequentistic, simulation-based parameter estimation method primarily designed -for Evolutionary Biology. The method is described in the publications +Jaatha is an estimation method that uses computer simulations to produce +maximum-likelihood estimates even when the likelihood function can not be +evaluated directly. It can be applied whenever it is feasible to conduct many +simulations, but works best when the data is at least approximately Poisson +distributed. -> L. Naduvilezhath, L.E. Rose and D. Metzler: -> Jaatha: a fast composite-likelihood approach to estimate demographic -> parameters. Molecular Ecology 20(13):2709-23 (2011). +Jaatha was originally designed for demographic inference in evolutionary +biology. It has optional support for conducting coalescent simulation using +the [coala](https://github.com/statgenlmu/coala) R package, but can also be +used for different applications. -> L.A. Mathew, P.R. Staab, L.E. Rose and D. Metzler: -> [Why to account for finite sites in population genetic studies and -> how to do this with Jaatha 2.0][1]. Ecology and Evolution (2013). - -Practical instructions for running Jaatha are provided in the -[The Jaatha HowTo][2]. Instructions how to use Jaatha with a non-standard -simulation method are given in the [Custom Simulation Method HowTo][3]. +Jaatha is implemented as an [R](https://www.r-project.org) package and available on +[CRAN](https://cran.r-project.org/web/packages/jaatha). -Jaatha is developed openly on [GitHub][4]. Feel free to open an issue there if -you encounter problems using Jaatha or have suggestions for future versions. Installation ------------ -### Stable Version - -To install the current stable version of jaatha from CRAN, type +Jaatha can be installed from CRAN using the `install.packages` command: ```R install.packages('jaatha') ``` -in R. +Usage +----- -### Development Version - -You can install the development version from [GitHub][4] using: +The R package includes an introduction vignette that explains how a jaatha +analysis is conducted. After the package is installed, you can open the +vignette using: ```R -devtools::install_github('statgenlmu/jaatha') +vignette("jaatha-intro") ``` +A second vignette called `jaatha-evolution` describes how jaatha can be used +together with `coala` for demographic inference. +Further help is provided using R's help system, in particular via `?jaatha`, +`?create_jaatha_model` and `?create_jaatha_data`. -Usage ------ -Please refer to the [The Jaatha HowTo][2] for usage information. +References +---------- +Jaatha's original algorithm is described in the publication: -Links ------ +> L. Naduvilezhath, L.E. Rose and D. Metzler: +> Jaatha: a fast composite-likelihood approach to estimate demographic +> parameters. Molecular Ecology 20(13):2709-23 (2011). + +The revised version of the algorithm that is implemented in this package +is described in: + +> L.A. Mathew, P.R. Staab, L.E. Rose and D. Metzler: +> [Why to account for finite sites in population genetic studies and +> how to do this with Jaatha 2.0](http://onlinelibrary.wiley.com/doi/10.1002/ece3.722/abstract). +> Ecology and Evolution (2013). -[1]: http://onlinelibrary.wiley.com/doi/10.1002/ece3.722/abstract -[2]: https://github.com/statgenlmu/jaatha/raw/master/howtos/jaatha_howto.pdf -[3]: https://github.com/statgenlmu/jaatha/raw/master/howtos/custom_simulator_howto.pdf -[4]: https://github.com/statgenlmu/jaatha -* [Jaatha's Homepage](http://evol.bio.lmu.de/_statgen/software/jaatha) -* [Source Code on GitHub](https://github.com/statgenlmu/jaatha) -* [Bug tracker](https://github.com/paulstaab/statgenlmu/issues) -* [Jaatha's page on CRAN](http://cran.r-project.org/web/packages/jaatha/index.html) + +Development +----------- + +Jaatha is developed openly on [GitHub](https://github.com/statgenlmu/jaatha). +Feel free to open an issue there if you encounter problems using Jaatha or +have suggestions for future versions. + +The current development version can be installed using: + +```R +devtools::install_github('statgenlmu/jaatha') +``` diff --git a/vignettes/jaatha-intro.Rmd b/vignettes/jaatha-intro.Rmd index 784d971..f9cdd57 100644 --- a/vignettes/jaatha-intro.Rmd +++ b/vignettes/jaatha-intro.Rmd @@ -15,7 +15,7 @@ evaluated directly. It can be applied whenever it is feasible to conduct many simulations, but works best when the data is at least approximately possion distributed. -Jaatha was orginially designed for demographic inference in evolutionary +Jaatha was originally designed for demographic inference in evolutionary biology. Please also refer to the vignette ```{r eval=FALSE} @@ -42,9 +42,9 @@ Imagine that we have observed the following data data_obs <- c(2, 8, 0, 6, 1, 3, 2, 2, 0, 7) data_obs ``` -and we assume that the data are indepented samples from two Poisson +and we assume that the data are independent samples from two Poisson distributions with parameters p1 and p2, respectively. The odd positions of the -vector are samples from the first distribtion, and the even positions are +vector are samples from the first distribution, and the even positions are samples taken from the second distribution. In order to run jaatha, we need first formalize this model and convert the data @@ -64,7 +64,7 @@ sim_func <- function(x) rpois(10, x) sim_func(c(p1 = 1, p2 = 10)) ``` -Simulation functions for jaatha must have exactly one argument, which is the +Simulation functions for jaatha must have exactly one argument, which is a vector of model parameters for which the simulation is conducted. There are no requirements on the return format of a simulation function from jaatha's site, any R objects work @@ -85,7 +85,7 @@ sum_stats <- list(create_jaatha_stat("id", function(x, opts) x)) Note that we create a list containing our statistic. In our example, we'll use just one statistic, but it is possible to add more than one statistic to this list. Please refer to the documentation for `create_jaatha_stat` for additional -information, in particular if you can not generate Possison distributed +information, in particular if you can not generate Poisson distributed statistics from the simulation results easily. @@ -101,7 +101,7 @@ par_ranges This three components -- a simulation function, parameter ranges and a list of -summary statistics -- are required to descibe an probabilistic framework within +summary statistics -- are required to describe an probabilistic framework within witch jaatha can fit parameters. Since we have the pieces together now, we can use the `create_jaatha_model` function to combine them into a formal model that we can pass to the `jaatha` function later: @@ -145,4 +145,4 @@ positions. For real applications, higher values are recommended. In this simple toy example, the above values work quite well: ```{r print_estimates} estimates -``` \ No newline at end of file +```