diff --git a/DESCRIPTION b/DESCRIPTION index c8018a8..60ad7d7 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -15,8 +15,7 @@ Imports: ICC (>= 2.3.0), purrr (>= 0.3.2), rlang (>= 0.3.4), tidyr (>= 0.8.3), - tmvtnorm (>= 1.4-10), - truncnorm (>= 1.0-8) + tmvtnorm (>= 1.4-10) Suggests: ggplot2 (>= 3.1.0), roxygen2, diff --git a/NAMESPACE b/NAMESPACE index 75c2d46..e97fcf5 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,21 +1,4 @@ # Generated by roxygen2: do not edit by hand -export(":=") -export(.data) -export(as_label) -export(as_name) -export(enquo) -export(enquos) -export(expr) export(predict_dominance) -export(sym) -export(syms) -importFrom(rlang,":=") importFrom(rlang,.data) -importFrom(rlang,as_label) -importFrom(rlang,as_name) -importFrom(rlang,enquo) -importFrom(rlang,enquos) -importFrom(rlang,expr) -importFrom(rlang,sym) -importFrom(rlang,syms) diff --git a/R/data.R b/R/data.R new file mode 100644 index 0000000..62dc041 --- /dev/null +++ b/R/data.R @@ -0,0 +1,5 @@ +#' Example dataset with a single measurement of three individuals. +"example_data1" + +#' Example dataset with three measurements each on 100 individuals. +"example_data2" diff --git a/R/predict_asymmetry.R b/R/predict_dominance.R similarity index 66% rename from R/predict_asymmetry.R rename to R/predict_dominance.R index 9c86b62..307ea51 100644 --- a/R/predict_asymmetry.R +++ b/R/predict_dominance.R @@ -31,37 +31,23 @@ #' columns of \code{data}. #' @export #' @examples -#' ## Simple test dataset -#' data <- data.frame( -#' listening = c(-20, -23, -14), -#' handedness = "left", -#' stringsAsFactors = FALSE -#' ) -#' ## Compute predictions -#' predict_dominance(data) +#' # The package comes with two example datasets. +#' # The first contains single measurements on three subjects. +#' # We can first take a look at the data +#' example_data1 +#' # Next, compute predictions. +#' # Since there is no ID column, predict_dominance() will print a message telling +#' # the user that the rows are assumed to contain observations from different subjects. +#' predict_dominance(example_data1) #' -#' ## More interesting example, with multiple measurements per individual. -#' library(dplyr); library(purrr); library(tidyr); library(truncnorm) -#' ## First we sample test data -#' n <- 100 # number of individuals -#' reps <- 3 # number of measurements per individual -#' ## The distribution of subject means has standard deviation 10, and the -#' ## actual measurements for each subject are distributed with a standard -#' ## deviation of 10 around this mean. -#' set.seed(234) -#' data <- tibble( -#' ID = factor(1:n), -#' subject_mean = rtruncnorm(n, a = 0, b = 100, mean = 10, sd = 10), -#' handedness = "left") %>% -#' mutate( -#' listening = map(subject_mean, ~ rtruncnorm(reps, a = -100, b = 100, -#' mean = .x, sd = 10)) -#' ) %>% -#' unnest(listening) +#' # The next example dataset contains repeated measurements +#' example_data2 #' -#' predict_dominance(data) +#' # We compute the predictions as before: +#' predict_dominance(example_data2) #' #' +#' @importFrom rlang .data predict_dominance <- function(data, parameters = dplyr::tibble( dominance = rep(c("left", "right", "none"), each = 2), @@ -82,11 +68,11 @@ predict_dominance <- function(data, data$ID = as.character(seq(1, nrow(data), by = 1)) } - dat1 <- dplyr::select(data, .data$ID, .data$listening, .data$handedness) + dat1 <- dplyr::select_at(data, dplyr::vars("ID", "listening", "handedness")) dat1 <- dplyr::inner_join(dat1, parameters, by = "handedness") - dat1 <- dplyr::select(dat1, .data$ID, .data$handedness, .data$dominance, - .data$prob_dominance, .data$mean_li, .data$sd_li, .data$listening) - dat2 <- tidyr::nest(dat1, df = c(.data$listening, .data$mean_li, .data$sd_li)) + dat1 <- dplyr::select_at(dat1, dplyr::vars("ID", "handedness", "dominance", + "prob_dominance", "mean_li", "sd_li", "listening")) + dat2 <- tidyr::nest(dat1, df = c("listening", "mean_li", "sd_li")) dat3 <- dplyr::mutate(dat2, log_prob_listening = purrr::map_dbl(.data$df, function(x) { tmvtnorm::dtmvnorm(x$listening, @@ -100,10 +86,10 @@ predict_dominance <- function(data, log_posterior = log(.data$prob_dominance) + .data$log_prob_listening, probability = exp(.data$log_posterior) ) - dat4 <- dplyr::group_by(dat3, .data$ID) - dat5 <- dplyr::mutate(dat4, probability = .data$probability / sum(.data$probability)) + dat4 <- dplyr::group_by_at(dat3, dplyr::vars("ID")) + dat5 <- dplyr::mutate_at(dat4, dplyr::vars("probability"), ~ . / sum(.)) - dplyr::select(dplyr::ungroup(dat5), .data$ID, .data$handedness, - .data$dominance, .data$probability) + dplyr::select_at(dplyr::ungroup(dat5), dplyr::vars("ID", "handedness", + "dominance", "probability")) } diff --git a/R/utils-tidy-eval.R b/R/utils-tidy-eval.R deleted file mode 100644 index af7c474..0000000 --- a/R/utils-tidy-eval.R +++ /dev/null @@ -1,47 +0,0 @@ -#' Tidy eval helpers -#' -#' @description -#' -#' * \code{\link[rlang:quotation]{sym}()} creates a symbol from a string and -#' \code{\link[rlang:quotation]{syms}()} creates a list of symbols from a -#' character vector. -#' -#' * \code{\link[rlang:quotation]{enquo}()} and -#' \code{\link[rlang:quotation]{enquos}()} delay the execution of one or -#' several function arguments. \code{enquo()} returns a single quoted -#' expression, which is like a blueprint for the delayed computation. -#' \code{enquos()} returns a list of such quoted expressions. -#' -#' * \code{\link[rlang:quotation]{expr}()} quotes a new expression _locally_. It -#' is mostly useful to build new expressions around arguments -#' captured with [enquo()] or [enquos()]: -#' \code{expr(mean(!!enquo(arg), na.rm = TRUE))}. -#' -#' * \code{\link[rlang]{as_name}()} transforms a quoted variable name -#' into a string. Supplying something else than a quoted variable -#' name is an error. -#' -#' That's unlike \code{\link[rlang]{as_label}()} which also returns -#' a single string but supports any kind of R object as input, -#' including quoted function calls and vectors. Its purpose is to -#' summarise that object into a single label. That label is often -#' suitable as a default name. -#' -#' If you don't know what a quoted expression contains (for instance -#' expressions captured with \code{enquo()} could be a variable -#' name, a call to a function, or an unquoted constant), then use -#' \code{as_label()}. If you know you have quoted a simple variable -#' name, or would like to enforce this, use \code{as_name()}. -#' -#' To learn more about tidy eval and how to use these tools, visit -#' \url{https://tidyeval.tidyverse.org} and the -#' \href{https://adv-r.hadley.nz/metaprogramming.html}{Metaprogramming -#' section} of \href{https://adv-r.hadley.nz}{Advanced R}. -#' -#' @md -#' @name tidyeval -#' @keywords internal -#' @importFrom rlang expr enquo enquos sym syms .data := as_name as_label -#' @aliases expr enquo enquos sym syms .data := as_name as_label -#' @export expr enquo enquos sym syms .data := as_name as_label -NULL diff --git a/README.Rmd b/README.Rmd index a500cfe..89f227f 100644 --- a/README.Rmd +++ b/README.Rmd @@ -19,7 +19,7 @@ knitr::opts_chunk$set( [![Travis build status](https://travis-ci.org/LCBC-UiO/BayesianLaterality.svg?branch=master)](https://travis-ci.org/LCBC-UiO/BayesianLaterality) -The goal of BayesianLaterality is to predict latent hemispheric dominance based on observed laterality. +The goal of BayesianLaterality is to predict latent hemispheric dominance based on observed laterality using Bayes' theorem. ## Installation @@ -32,5 +32,23 @@ remotes::install_github("LCBC-UiO/BayesianLaterality") ``` +## Application Example + +```{r} +library(BayesianLaterality) +``` + + +The main (and only) function of the package is `predict_dominance()`. To see the arguments that can be set by the user and a more extended example, type `?predict_dominance` in the R terminal. Here is a simple example. The dataset `example_data1` contains three laterality measurements on three right-handed individuals. + +```{r} +example_data1 +``` + +We then obtain predicted hemispheric dominance as follows. The ID column reflects the row in the original dataset. + +```{r} +predict_dominance(example_data1) +``` diff --git a/README.md b/README.md index ea0f389..2847025 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ status](https://travis-ci.org/LCBC-UiO/BayesianLaterality.svg?branch=master)](ht The goal of BayesianLaterality is to predict latent hemispheric -dominance based on observed laterality. +dominance based on observed laterality using Bayes’ theorem. ## Installation @@ -21,3 +21,43 @@ with: # install.packages("remotes") remotes::install_github("LCBC-UiO/BayesianLaterality") ``` + +## Application Example + +``` r +library(BayesianLaterality) +``` + +The main (and only) function of the package is `predict_dominance()`. To +see the arguments that can be set by the user and a more extended +example, type `?predict_dominance` in the R terminal. Here is a simple +example. The dataset `example_data1` contains three laterality +measurements on three right-handed individuals. + +``` r +example_data1 +#> listening handedness +#> 1 20 right +#> 2 23 right +#> 3 14 right +``` + +We then obtain predicted hemispheric dominance as follows. The ID column +reflects the row in the original dataset. + +``` r +predict_dominance(example_data1) +#> No ID column in data, assuming one subject per row. +#> # A tibble: 9 x 4 +#> ID handedness dominance probability +#> +#> 1 1 right left 0.994 +#> 2 1 right right 0.00583 +#> 3 1 right none 0 +#> 4 2 right left 0.996 +#> 5 2 right right 0.00402 +#> 6 2 right none 0 +#> 7 3 right left 0.988 +#> 8 3 right right 0.0122 +#> 9 3 right none 0 +``` diff --git a/data/example_data1.rda b/data/example_data1.rda new file mode 100644 index 0000000..0e504a9 Binary files /dev/null and b/data/example_data1.rda differ diff --git a/data/example_data2.rda b/data/example_data2.rda new file mode 100644 index 0000000..07553df Binary files /dev/null and b/data/example_data2.rda differ diff --git a/man/example_data1.Rd b/man/example_data1.Rd new file mode 100644 index 0000000..8ad6f7d --- /dev/null +++ b/man/example_data1.Rd @@ -0,0 +1,14 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/data.R +\docType{data} +\name{example_data1} +\alias{example_data1} +\title{Example dataset with a single measurement of three individuals.} +\format{An object of class \code{tbl_df} (inherits from \code{tbl}, \code{data.frame}) with 3 rows and 2 columns.} +\usage{ +example_data1 +} +\description{ +Example dataset with a single measurement of three individuals. +} +\keyword{datasets} diff --git a/man/example_data2.Rd b/man/example_data2.Rd new file mode 100644 index 0000000..0f30632 --- /dev/null +++ b/man/example_data2.Rd @@ -0,0 +1,14 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/data.R +\docType{data} +\name{example_data2} +\alias{example_data2} +\title{Example dataset with three measurements each on 100 individuals.} +\format{An object of class \code{tbl_df} (inherits from \code{tbl}, \code{data.frame}) with 300 rows and 4 columns.} +\usage{ +example_data2 +} +\description{ +Example dataset with three measurements each on 100 individuals. +} +\keyword{datasets} diff --git a/man/predict_dominance.Rd b/man/predict_dominance.Rd index 74a00f8..aed7cfa 100644 --- a/man/predict_dominance.Rd +++ b/man/predict_dominance.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/predict_asymmetry.R +% Please edit documentation in R/predict_dominance.R \name{predict_dominance} \alias{predict_dominance} \title{Predict hemispheric dominance} @@ -51,35 +51,20 @@ The probability of left or right hemispheric dominance in additional Predict hemispheric dominance } \examples{ -## Simple test dataset -data <- data.frame( - listening = c(-20, -23, -14), - handedness = "left", - stringsAsFactors = FALSE - ) -## Compute predictions -predict_dominance(data) +# The package comes with two example datasets. +# The first contains single measurements on three subjects. +# We can first take a look at the data +example_data1 +# Next, compute predictions. +# Since there is no ID column, predict_dominance() will print a message telling +# the user that the rows are assumed to contain observations from different subjects. +predict_dominance(example_data1) -## More interesting example, with multiple measurements per individual. -library(dplyr); library(purrr); library(tidyr); library(truncnorm) -## First we sample test data -n <- 100 # number of individuals -reps <- 3 # number of measurements per individual -## The distribution of subject means has standard deviation 10, and the -## actual measurements for each subject are distributed with a standard -## deviation of 10 around this mean. -set.seed(234) -data <- tibble( - ID = factor(1:n), - subject_mean = rtruncnorm(n, a = 0, b = 100, mean = 10, sd = 10), - handedness = "left") \%>\% - mutate( - listening = map(subject_mean, ~ rtruncnorm(reps, a = -100, b = 100, - mean = .x, sd = 10)) - ) \%>\% - unnest(listening) +# The next example dataset contains repeated measurements +example_data2 -predict_dominance(data) +# We compute the predictions as before: +predict_dominance(example_data2) } diff --git a/man/tidyeval.Rd b/man/tidyeval.Rd deleted file mode 100644 index 5b97416..0000000 --- a/man/tidyeval.Rd +++ /dev/null @@ -1,51 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils-tidy-eval.R -\name{tidyeval} -\alias{tidyeval} -\alias{expr} -\alias{enquo} -\alias{enquos} -\alias{sym} -\alias{syms} -\alias{.data} -\alias{:=} -\alias{as_name} -\alias{as_label} -\title{Tidy eval helpers} -\description{ -\itemize{ -\item \code{\link[rlang:quotation]{sym}()} creates a symbol from a string and -\code{\link[rlang:quotation]{syms}()} creates a list of symbols from a -character vector. -\item \code{\link[rlang:quotation]{enquo}()} and -\code{\link[rlang:quotation]{enquos}()} delay the execution of one or -several function arguments. \code{enquo()} returns a single quoted -expression, which is like a blueprint for the delayed computation. -\code{enquos()} returns a list of such quoted expressions. -\item \code{\link[rlang:quotation]{expr}()} quotes a new expression \emph{locally}. It -is mostly useful to build new expressions around arguments -captured with \code{\link[=enquo]{enquo()}} or \code{\link[=enquos]{enquos()}}: -\code{expr(mean(!!enquo(arg), na.rm = TRUE))}. -\item \code{\link[rlang]{as_name}()} transforms a quoted variable name -into a string. Supplying something else than a quoted variable -name is an error. - -That's unlike \code{\link[rlang]{as_label}()} which also returns -a single string but supports any kind of R object as input, -including quoted function calls and vectors. Its purpose is to -summarise that object into a single label. That label is often -suitable as a default name. - -If you don't know what a quoted expression contains (for instance -expressions captured with \code{enquo()} could be a variable -name, a call to a function, or an unquoted constant), then use -\code{as_label()}. If you know you have quoted a simple variable -name, or would like to enforce this, use \code{as_name()}. -} - -To learn more about tidy eval and how to use these tools, visit -\url{https://tidyeval.tidyverse.org} and the -\href{https://adv-r.hadley.nz/metaprogramming.html}{Metaprogramming -section} of \href{https://adv-r.hadley.nz}{Advanced R}. -} -\keyword{internal}