Merge pull request #3 from LCBC-UiO/examples

Created examples and cleaned up imports

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,

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)

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"

R/predict_asymmetry.R → 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"))
 }
 

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)
 <!-- badges: end -->
 
-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)
+```
 
 

README.md

@@ -10,7 +10,7 @@ status](https://travis-ci.org/LCBC-UiO/BayesianLaterality.svg?branch=master)](ht
 <!-- badges: end -->
 
 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
+#>   <chr> <chr>      <chr>           <dbl>
+#> 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
+```