improve documentation for create_jaatha_model

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: jaatha
-Version: 2.99.0.9222
-Date: 2015-11-25
+Version: 2.99.0.9223
+Date: 2015-12-01
 License: GPL (>= 3)
 Title: Simulation-Based Maximum Likelihood Parameter Estimation
 Authors@R: c(

R/coala_interface.R

@@ -45,7 +45,7 @@ create_jaatha_model.coalmodel <- function(x,
 
   if (length(jsfs_summary) > 1) jsfs_summary <- jsfs_summary[1]
 
-  sim_func <- function(pars, opts = NULL) simulate(x, pars = pars)
+  sim_func <- function(pars) simulate(x, pars = pars)
 
   # create parameter ranges
   par_table <- coala::get_parameter_table(x)

R/jaatha_model.R

@@ -20,9 +20,8 @@ jaatha_model_class <- R6Class("jaatha_model",
     initialize = function(sim_func, par_ranges, sum_stats, 
                           scaling_factor, test) {
       assert_that(is.function(sim_func))
-      if (length(formals(sim_func)) < 2) {
-        stop("The simulation function needs two arguments: ", 
-             "'Parameters' and 'Options'.")
+      if (length(formals(sim_func)) != 1) {
+        stop("The simulation function must have exactly one argument.")
       }
       private$sim_func <- sim_func
       private$par_ranges <- par_ranges_class$new(par_ranges)
@@ -96,11 +95,16 @@ jaatha_model_class <- R6Class("jaatha_model",
 )
 
 
-#' Specify a model for a Jaatha analysis 
+#' Specify a Model for a Jaatha Analysis 
+#' 
+#' This function can be used to create models for an analysis with Jaatha.
+#' Models can be created using simulation function  
+#' (see \code{\link{create_jaatha_model.function}}) or using a \pkg{coala} 
+#' model (see \code{\link{create_jaatha_model.coalmodel}}).
 #' 
 #' @param x The primary argument. Can be a function used for simulations,
 #'   or a coala model.
-#' @param ... Additinoal parameters passed on to the dispatched functions.
+#' @param ... Additional parameters passed on to the dispatch function.
 #' @param scaling_factor If your model is a down-scaled version of your data,
 #'   you can indicated this using this value. The estimated expectation values
 #'   are multiplied with this factor before the likelihood is calculated.
@@ -112,7 +116,37 @@ create_jaatha_model <- function(x, ..., scaling_factor = 1, test = TRUE) {
 }
 
 
+create_jaatha_model.default <- function(x, ..., scaling_factor = 1, test = TRUE) {
+  stop("Can create a model from an object of class '", class(x), "'")
+}
+
+
+#' Specify a jaatha model using a simulation function
+#' 
+#' This is the usual way to specify a jaatha model. An detailed exampled on 
+#' doing so is given in the `jaatha-intro` vignette.
+#' 
+#' @param x A simulation function. This function takes model parameters as 
+#'   input, and returns the simulated data. The function must take exactly one 
+#'   argument, which is a numeric vector of model parameters for which the 
+#'   simulation should be conducted. The function should return the simulation
+#'   results in an arbitrary format, that is then passed on to the summary
+#'   statistics.
+#' @param par_ranges A matrix stating the possible values for the model 
+#'   parameters. The matrix must have one row for each parameter, and two
+#'   columns which state the minimal and maximal possible value for the 
+#'   parameter.
+#' @param sum_stats A list of summary statistics created with 
+#'   \code{\link{create_jaatha_stat}}. The simulation results will be passed
+#'   to the statistics, which should convert them into a numeric vector.
+#' @param ... Currently unused.
+#' @inheritParams create_jaatha_model
+#'
 #' @export
+#' @examples 
+#' create_jaatha_model(function(x) rpois(10, x),
+#'                     par_ranges = matrix(c(0.1, 0.1, 10, 10), 2, 2),
+#'                     sum_stats = list(create_jaatha_stat("sum", sum)))
 create_jaatha_model.function <- function(x, par_ranges, sum_stats, ...,
                                          scaling_factor = 1, 
                                          test = TRUE) {
@@ -126,7 +160,7 @@ is_jaatha_model <- function(x) inherits(x, "jaatha_model")
 
 #' @importFrom stats rpois
 create_test_model <- function() {
-  create_jaatha_model(function(x, y) rpois(10, x),
+  create_jaatha_model(function(x) rpois(10, x),
                       par_ranges = matrix(c(0.1, 0.1, 10, 10), 2, 2),
                       sum_stats = list(stat_identity(), stat_sum()),
                       test = FALSE)

tests/testthat/test-jaatha-function.R

@@ -15,7 +15,7 @@ test_that("the main function works", {
 
 
 test_that("it supports a one parameter model", {
-  model <- create_jaatha_model(function(x, y) rpois(10, x),
+  model <- create_jaatha_model(function(x) rpois(10, x),
                                par_ranges = matrix(c(0.1, 10), 1, 2),
                                sum_stats = list(stat_identity(), stat_sum()),
                                test = FALSE)

tests/testthat/test-jaatha-model.R

@@ -6,19 +6,20 @@ test_that("jaatha model can be initialized", {
   expect_equal(model$get_par_number(), model$get_par_ranges()$get_par_number())
   expect_equal(model$get_scaling_factor(), 1)
 
-
+  expect_error(create_jaatha_model(1:5))
+  expect_error(create_jaatha_model("Not a model")) 
 })
 
 
-test_that("it checks that the simfunc has two arguments", {
-  sim_func <- function(x) rpois(10, x)
+test_that("it checks that the simfunc has one arguments", {
+  sim_func <- function(x, y) rpois(10, x)
   par_ranges = matrix(c(0.1, 0.1, 10, 10), 2, 2)
   expect_error(create_jaatha_model(sim_func, par_ranges, list(stat_identity())))
 })
 
 
 test_that("adding summary statistics works", {
-  sim_func <- function(x, y) rpois(10, x)
+  sim_func <- function(x) rpois(10, x)
   par_ranges = matrix(c(0.1, 0.1, 10, 10), 2, 2)
 
   model <- create_jaatha_model(sim_func, par_ranges, list(stat_identity()))
@@ -71,7 +72,7 @@ test_that("simulation works", {
 
 
 test_that("failing simulations are detected", {
-  model <- create_jaatha_model(function(x, y) stop("test"),
+  model <- create_jaatha_model(function(x) stop("test"),
                                par_ranges = matrix(c(0.1, 0.1, 10, 10), 2, 2),
                                sum_stats = list(stat_identity(), stat_sum()),
                                test = FALSE)

vignettes/jaatha-intro.Rmd

@@ -60,14 +60,14 @@ simulates data according to the model. In our example of the mixed samples
 from Poisson distributions, we can use the function
 
 ```{r sim_func}
-sim_func <- function(x, opts = NULL) rpois(10, x)
+sim_func <- function(x) rpois(10, x)
 sim_func(c(p1 = 1, p2 = 10))
 ```
 
-Simulation functions for jaatha must always take two arguments. The first one --
-here `x` -- is the parameters for which the simulation is conducted. It is 
-usually fine to ignore the second argument. There are no requirements on the
-return format of a simulation function from jaatha's site, any R objects work 
+Simulation functions for jaatha must have exactly one argument, which is the 
+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 
 with Jaatha. Here, the function returns an vector of ten integers.