Added references, examples and revised the package in accordance with…

… CRAN revisor's report.

DESCRIPTION

@@ -1,11 +1,14 @@
 Package: bayes4psy
 Version: 1.0.2
-Title: An R Package for User Friendly Bayesian Data Analysis in Psychology
-Description: This is an R package intended for Bayesian statistical analysis in the field of psychology. This package should enable students and researchers to perform professional level Bayesian data analysis without advanced knowledge in programming and Bayesian statistics.
+Title: User Friendly Bayesian Data Analysis for Psychology
+Description: Contains several Bayesian models for data analysis of psychological tests. A user friendly interface for these models should enable students and researchers to perform professional level Bayesian data analysis without advanced knowledge in programming and Bayesian statistics. John Kruschke (2014, ISBN:978-0124058880)
 Authors@R:
     c(person("Jure", "Demšar", , "[email protected]", c("cre", "aut")),
     person("Grega", "Repovš", , "[email protected]", "aut"),
-    person("Erik", "Štrumbelj", , "[email protected]", "aut"))
+    person("Erik", "Štrumbelj", , "[email protected]", "aut"),
+    person("Trustees of", "Columbia University", role = "cph"),
+    person("John", "Kruschke", role = "cph", comment = "R/shared_functions.R - mcmc_hdi, src/stan_files/ttest.stan"),
+    person("Rasmus", "Baath", role = "cph", comment = "R/b_bootstrap.R"))
 License: GPL (>=3)
 Encoding: UTF-8
 LazyData: true

R/b_bootstrap.R

@@ -12,6 +12,20 @@
 #' @param weight_arg If the statistic function includes a named argument for the weights this could be specified here (default = NULL).
 #' @param ... Further arguments passed on to the statistic function.
 #' @return An object of class `linear_class`.
+#'
+#' @examples
+#'
+#' # linear function of seqence vs. response
+#' lm_statistic <- function(data) {
+#'   lm(sequence ~ response, data)$coef
+#' }
+#'
+#' # load data
+#' data <- adaptation_level_small
+#'
+#' # bootstrap
+#' data_bootstrap <- b_bootstrap(data, lm_statistic, n1=1000, n2=1000)
+#'
 b_bootstrap <- function(data, statistic, n1=1000, n2=1000, use_weights=FALSE, weight_arg=NULL, ...) {
   # Draw from a uniform Dirichlet dist. with alpha set to rep(1, n_dim).
   # Using the facts that you can transform gamma distributed draws into

R/b_color.R

@@ -13,6 +13,72 @@
 #' @param control A named list of parameters to control the sampler's behavior (default = NULL).
 #' @param suppress_warnings Suppress warnings returned by Stan (default = TRUE).
 #' @return An object of class `color_class`
+#'
+#' @examples
+#' # priors for rgb
+#' mu_prior <- b_prior(family="uniform", pars=c(0, 255))
+#' sigma_prior <- b_prior(family="uniform", pars=c(0, 100))
+#'
+#' # attach priors to relevant parameters
+#' priors_rgb <- list(c("mu_r", mu_prior),
+#'                    c("sigma_r", sigma_prior),
+#'                    c("mu_g", mu_prior),
+#'                    c("sigma_g", sigma_prior),
+#'                    c("mu_b", mu_prior),
+#'                    c("sigma_b", sigma_prior))
+#'
+#'
+#' # generate data (rgb)
+#' r <- as.integer(rnorm(100, mean=250, sd=20))
+#' r[r > 255] <- 255
+#' r[r < 0] <- 0
+#'
+#' g <- as.integer(rnorm(100, mean=20, sd=20))
+#' g[g > 255] <- 255
+#' g[g < 0] <- 0
+#'
+#' b <- as.integer(rnorm(100, mean=40, sd=20))
+#' b[b > 255] <- 255
+#' b[b < 0] <- 0
+#'
+#' colors_rgb <- data.frame(r=r, g=g, b=b)
+#'
+#' # fit
+#' fit_rgb <- b_color(colors=colors_rgb, priors=priors_rgb, chains=1)
+#'
+#'
+#' # priors for hsv
+#' h_prior <- b_prior(family="uniform", pars=c(0, 2*pi))
+#' sv_prior <- b_prior(family="uniform", pars=c(0, 1))
+#' kappa_prior <- b_prior(family="uniform", pars=c(0, 500))
+#' sigma_prior <- b_prior(family="uniform", pars=c(0, 1))
+#'
+#' # attach priors to relevant parameters
+#' priors_hsv <- list(c("mu_h", h_prior),
+#'                    c("kappa_h", kappa_prior),
+#'                    c("mu_s", sv_prior),
+#'                    c("sigma_s", sigma_prior),
+#'                    c("mu_v", sv_prior),
+#'                    c("sigma_v", sigma_prior))
+#'
+#' # generate data (hsv)
+#' h <- rnorm(100, mean=2*pi/3, sd=0.5)
+#' h[h > 2*pi] <- 2*pi
+#' h[h < 0] <- 0
+#'
+#' s <- rnorm(100, mean=0.9, sd=0.2)
+#' s[s > 1] <- 1
+#' s[s < 0] <- 0
+#'
+#' v <- rnorm(100, mean=0.9, sd=0.2)
+#' v[v > 1] <- 1
+#' v[v < 0] <- 0
+#'
+#' colors_hsv <- data.frame(h=h, s=s, v=v)
+#'
+#' # fit
+#' fit_hsv <- b_color(colors=colors_hsv, hsv=TRUE, priors=priors_hsv, chains=1)
+#'
 b_color <- function(colors,
                     priors=NULL,
                     hsv=FALSE,

R/b_linear.R

@@ -14,6 +14,33 @@
 #' @param control A named list of parameters to control the sampler's behavior (default = NULL).
 #' @param suppress_warnings Suppress warnings returned by Stan (default = TRUE).
 #' @return An object of class `linear_class`.
+#'
+#' @examples
+#' # priors
+#' mu_prior <- b_prior(family="normal", pars=c(0, 100))
+#' sigma_prior <- b_prior(family="uniform", pars=c(0, 500))
+#'
+#' # attach priors to relevant parameters
+#' priors <- list(c("mu_a", mu_prior),
+#'                c("sigma_a", sigma_prior),
+#'                c("mu_b", mu_prior),
+#'                c("sigma_b", sigma_prior),
+#'                c("mu_s", sigma_prior),
+#'                c("sigma_s", sigma_prior))
+#'
+#' # generate data
+#' x <- vector()
+#' y <- vector()
+#' s <- vector()
+#' for (i in 1:5) {
+#'   x <- c(x, rep(1:10, 2))
+#'   y <- c(y, rnorm(20, mean=1:10, sd=2))
+#'   s <- c(s, rep(i, 20))
+#' }
+#'
+# fit
+#' fit <- b_linear(x=x, y=y, s=s, priors=priors, chains=1)
+#'
 b_linear <- function(x,
                      y,
                      s,

R/b_reaction_time.R

@@ -12,7 +12,29 @@
 #' @param refresh Frequency of output (default = NULL).
 #' @param control A named list of parameters to control the sampler's behavior (default = NULL).
 #' @param suppress_warnings Suppress warnings returned by Stan (default = TRUE).
-#' @return An object of class `reaction_time_class`.
+#' @return An object of class `reaction_time_class`
+#'
+#' @examples
+#' # priors
+#' mu_prior <- b_prior(family="normal", pars=c(0, 100))
+#' sigma_prior <- b_prior(family="uniform", pars=c(0, 500))
+#' lambda_prior <- b_prior(family="uniform", pars=c(0.05, 5))
+#'
+#' # attach priors to relevant parameters
+#' priors <- list(c("mu_m", mu_prior),
+#'               c("sigma_m", sigma_prior),
+#'               c("mu_s", sigma_prior),
+#'               c("sigma_s", sigma_prior),
+#'               c("mu_l", lambda_prior),
+#'               c("sigma_l", sigma_prior))
+#'
+#' # generate data
+#' s <- rep(1:5, 20)
+#' rt <- emg::remg(100, mu=10, sigma=1, lambda=0.4)
+#'
+#' # fit
+#' fit <- b_reaction_time(t=rt, s=s, priors=priors, chains=1)
+#'
 b_reaction_time <- function(t,
                             s,
                             priors=NULL,

R/b_results.R

@@ -1,13 +1,5 @@
 #' @title b_results
 #' @description Parent S4 class for declaring shared function generics.
-#'
-#' \strong{Functions}
-#'
-#' summary(`b_results_class`): prints a summary of the fit.
-#'
-#' print(`b_results_class`): prints a more detailed summary of the fit.
-#'
-#' show(`b_results_class`): prints a more detailed summary of the fit.
 setClass("b_results")
 
 
@@ -28,16 +20,16 @@ setGeneric(name="get_subject_parameters", function(object) standardGeneric("get_
 
 
 #' @title compare_means
-#' @description \code{compare_means} prints difference between two or multiple groups.
+#' @description \code{compare_means} prints difference between means of two or multiple fits.
 #' @param object S4 class object from bayes4psy library.
-#' @param ... see documentation for specific class for the description of available parameters, e.g. ?compare_ttest or ?compare_linear.
+#' @param ... see documentation for specific class for the description of available parameters, e.g. ?compare_means_ttest or ?compare_means_linear.
 #' @rdname b_results-compare_means
 #' @exportMethod compare_means
 setGeneric(name="compare_means", function(object, ...) standardGeneric("compare_means"))
 
 
 #' @title plot_means_difference
-#' @description \code{plot_means_difference} plots difference between two groups.
+#' @description \code{plot_means_difference} plots difference between means of two or multiple fits.
 #' @param object S4 class object from bayes4psy library.
 #' @param ... see documentation for specific class for the description of available parameters, e.g. ?plot_means_difference_ttest or ?plot_means_difference_linear.
 #' @rdname b_results-plot_means_difference
@@ -46,7 +38,7 @@ setGeneric(name="plot_means_difference", function(object, ...) standardGeneric("
 
 
 #' @title plot_means
-#' @description \code{plot_means} plots means for one or two groups.
+#' @description \code{plot_means} plots means for one or multiple fits.
 #' @param object S4 class object from bayes4psy library.
 #' @param ... see documentation for specific class for the description of available parameters, e.g. ?plot_means_ttest or ?plot_means_linear.
 #' @rdname b_results-plot_means
@@ -55,7 +47,7 @@ setGeneric(name="plot_means", function(object, ...) standardGeneric("plot_means"
 
 
 #' @title compare_distributions
-#' @description \code{compare_distributions} draws samples from distribution of the first group and compares them against samples drawn from the distribution of the second group,
+#' @description \code{compare_distributions} draws samples from distribution of the first fit and compares them against samples drawn from the distribution of the second fit, or against samples from multiple fits.
 #' @param object S4 class object from bayes4psy library.
 #' @param ... see documentation for specific class for the description of available parameters, e.g. ?compare_distributions_ttest or ?compare_distributions_linear.
 #' @rdname b_results-compare_distributions
@@ -73,7 +65,7 @@ setGeneric(name="plot_distributions", function(object, ...) standardGeneric("plo
 
 
 #' @title plot_distributions_difference
-#' @description \code{plot_distributions_difference} a visualization of the difference between the distribution of the first group and the distribution or a constant value for the second group.
+#' @description \code{plot_distributions_difference} a visualization of the difference between the distributions of two or more fits.
 #' @param object S4 class object from bayes4psy library.
 #' @param ... see documentation for specific class for the description of available parameters, e.g. ?plot_distributions_difference_ttest or ?plot_distributions_difference_linear.
 #' @rdname b_results-plot_distributions_difference

R/b_success_rate.R

@@ -13,6 +13,23 @@
 #' @param control A named list of parameters to control the sampler's behavior (default = NULL).
 #' @param suppress_warnings Suppress warnings returned by Stan (default = TRUE).
 #' @return An object of class `success_rate_class`.
+#'
+#' @examples
+#' # priors
+#' p_prior <- b_prior(family="beta", pars=c(1, 1))
+#' tau_prior <- b_prior(family="uniform", pars=c(0, 500))
+#'
+#' # attach priors to relevant parameters
+#' priors <- list(c("p", p_prior),
+#'                c("tau", tau_prior))
+#'
+#' # generate data
+#' s <- rep(1:5, 20)
+#' data <- rbinom(100, size=1, prob=0.6)
+#'
+#' # fit
+#' fit <- b_success_rate(r=data, s=s, priors=priors, chains=1)
+#'
 b_success_rate <- function(r,
                            s,
                            priors=NULL,

R/b_ttest.R

@@ -12,6 +12,22 @@
 #' @param control A named list of parameters to control the sampler's behavior (default = NULL).
 #' @param suppress_warnings Suppress warnings returned by Stan (default = TRUE).
 #' @return An object of class `ttest_class`.
+#'
+#' @examples
+#' # priors
+#' mu_prior <- b_prior(family="normal", pars=c(0, 1000))
+#' sigma_prior <- b_prior(family="uniform", pars=c(0, 500))
+#'
+#' # attach priors to relevant parameters
+#' priors <- list(c("mu", mu_prior),
+#'               c("sigma", sigma_prior))
+#'
+#' # generate some data
+#' data  <- rnorm(20, mean=150, sd=20)
+#'
+#' # fit
+#' fit <- b_ttest(data=data, priors=priors, chains=1)
+#'
 b_ttest <- function(data,
                     priors=NULL,
                     warmup=1000,