├── .Rbuildignore ├── .gitignore ├── DESCRIPTION ├── LICENSE ├── NAMESPACE ├── R ├── explain.R ├── explainr_output.R ├── load.R └── zzz.R ├── README.md ├── explainr.Rproj ├── inst └── themes │ ├── bioconductor │ └── MArrayLM.Rmd │ ├── default │ ├── htest.Rmd │ ├── htest.default.Rmd │ ├── power.t.test.Rmd │ └── prop.test.Rmd │ └── visual │ └── lm.Rmd ├── man ├── compile_template.Rd ├── explain.Rd ├── explain.default.Rd ├── explain_line.Rd ├── explainr_mode.Rd ├── explainr_output.Rd ├── explainr_themes.Rd ├── load_template.Rd ├── load_theme.Rd ├── load_themes.Rd └── print.explainr_output.Rd └── vignettes ├── bioconductor.Rmd └── intro.Rmd /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .Rproj.user 2 | .Rhistory 3 | .RData 4 | inst/doc 5 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: explainr 2 | Type: Package 3 | Title: Explains R in plain English 4 | Version: 0.1 5 | Date: 2015-03-26 6 | Authors@R: c( 7 | person("Hilary", "Parker", email = "hilary@etsy.com", role = c("aut", "cre")), 8 | person("David", "Robinson", email = "admiral.david@gmail.com", role = c("aut")), 9 | person("Stephanie", "Hicks", email = "stephaniechicks@gmail.com", role = c("aut")), 10 | person("Roger", "Peng", email = "rdpeng@gmail.com", role = c("aut")) 11 | ) 12 | Imports: 13 | dplyr, 14 | broom, 15 | stringr, 16 | yaml, 17 | knitr 18 | Maintainer: Hilary Parker 19 | Description: Explains R objects in plain English, based on a set of templates. 20 | License: MIT + file LICENSE 21 | LazyData: TRUE 22 | URL: http://github.com/hilaryparker/explainr 23 | VignetteBuilder: knitr 24 | BugReports: http://github.com/hilaryparker/explainr/issues 25 | Suggests: 26 | biobroom, 27 | ggplot2 28 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | YEAR: 2015 2 | COPYRIGHT HOLDER: Hilary Parker, David Robinson, Stephanie Hicks and Roger Peng 3 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | exportPattern("^[[:alpha:]]+") 2 | -------------------------------------------------------------------------------- /R/explain.R: -------------------------------------------------------------------------------- 1 | # basic explain S3 function 2 | 3 | #' Explain an object in plain English 4 | #' 5 | #' @param x an object 6 | #' @param ... extra arguments 7 | #' 8 | #' @return A text description of the object 9 | explain <- function (x, ...) UseMethod("explain") 10 | 11 | 12 | #' compile an object using a template 13 | #' 14 | #' @param template a template, typically loaded from \code{load_template} 15 | #' @param theme name of the theme to use 16 | #' @param ... objects to be provided to the template 17 | #' 18 | #' @return A compiled text version of the object 19 | compile_template <- function(template, theme = "default", ...) { 20 | if (is.character(theme)) { 21 | # retrieve theme 22 | theme <- explainr_themes[[theme]] 23 | } 24 | tem <- theme[[template]] 25 | 26 | if (is.null(tem)) { 27 | stop("Template for this object not found. You should write one!") 28 | } 29 | 30 | # knit content in a new environment 31 | env <- list2env(list(...)) 32 | 33 | # set options, but be able to set them back 34 | starting_options <- knitr::opts_chunk$get() 35 | knitr::opts_chunk$set(echo = FALSE, fig.path = "explainr-figures/", 36 | message = FALSE, results = 'asis') 37 | 38 | out <- knitr::knit(text = tem$content, envir = env, quiet = TRUE) 39 | 40 | # back to initial options 41 | do.call(knitr::opts_chunk$set, starting_options) 42 | explainr_output(out) 43 | } 44 | 45 | 46 | #' explain an S3 object in plain English 47 | #' 48 | #' @param x an object to be explained 49 | #' @param theme theme to use 50 | #' @param ... extra arguments 51 | #' 52 | #' @import dplyr 53 | explain.default <- function(x, theme = "default", template = NULL, ...) { 54 | if (is.null(template)) { 55 | template <- class(x)[1] 56 | } 57 | 58 | compile_template(template, x = x, theme = theme) 59 | } 60 | -------------------------------------------------------------------------------- /R/explainr_output.R: -------------------------------------------------------------------------------- 1 | #' Wrap an object as the output of an \code{explain} function 2 | #' 3 | #' @param x 4 | explainr_output <- function(x) { 5 | # trim whitespace 6 | x <- stringr::str_trim(x) 7 | 8 | x <- knitr::asis_output(x) 9 | class(x) <- c("explainr_output", class(x)) 10 | x 11 | } 12 | 13 | 14 | #' Print explainr output 15 | #' 16 | #' @param x 17 | print.explainr_output <- function(x) { 18 | cat(x, sep = "\n") 19 | } 20 | -------------------------------------------------------------------------------- /R/load.R: -------------------------------------------------------------------------------- 1 | #' Load a .Rmd template for displaying an object 2 | #' 3 | #' @param path Path to the .Rmd template file 4 | #' 5 | #' @return a list with two components: 6 | #' \item{header}{A named list containing the YAML components} 7 | #' \item{content}{A string with the contents of the string} 8 | load_template <- function(path) { 9 | txt <- readLines(path) 10 | 11 | header_pos <- which(stringr::str_detect(txt, "^---")) 12 | header_txt <- txt[(header_pos[1] + 1):(header_pos[2] - 1)] 13 | content_txt <- txt[(header_pos[2] + 1):length(txt)] 14 | 15 | header <- yaml::yaml.load(paste(header_txt, collapse = "\n")) 16 | content <- paste(content_txt, collapse = "\n") 17 | list(header = header, content = content) 18 | } 19 | 20 | 21 | #' Load a theme, which is a directory of templates 22 | #' 23 | #' @param path Path to a theme directory of .Rmd files 24 | #' 25 | #' @return a named list of templates 26 | load_theme <- function(path) { 27 | templates <- list.files(path, full.names = TRUE) 28 | ret <- lapply(templates, load_template) 29 | names(ret) <- sapply(ret, function(tm) tm$header$name) 30 | ret 31 | } 32 | 33 | 34 | #' Load all themes 35 | #' 36 | #' Load themes, by default from explainr's built-in themes directory. 37 | #' 38 | #' @param directory directory to load themes from 39 | #' 40 | #' @return a named list of themes 41 | load_themes <- function(directory = system.file("themes", package = "explainr")) { 42 | themes <- list.files(directory) 43 | paths <- paste(directory, themes, sep = "/") 44 | ret <- lapply(paths, load_theme) 45 | names(ret) <- themes 46 | ret 47 | } 48 | -------------------------------------------------------------------------------- /R/zzz.R: -------------------------------------------------------------------------------- 1 | #' Built-in themes 2 | #' 3 | #' These are loaded from the \code{themes/} directory in the package, using 4 | #' \code{\link{load_themes}}. So far they include: 5 | #' \itemize{ 6 | #' \item{default}{default text description} 7 | #' \item{visual}{graphical displays of objects} 8 | #' } 9 | #' 10 | #' @name explainr_themes 11 | NULL 12 | 13 | # load built-in themes 14 | explainr_themes <- load_themes() 15 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # explainr 2 | 3 | ### What is explainr? 4 | 5 | **explainr** translates S3 objects into text using standard templates in a simple and convenient way. 6 | 7 | For help with the **explainr** R-package, there is a vignette available in the /vignettes folder. 8 | 9 | # Installation 10 | 11 | The package can be installed with 12 | 13 | devtools::install_github("hilaryparker/explainr") 14 | 15 | After installation, the package can be loaded into R. 16 | 17 | library(explainr) 18 | 19 | # Using explainr 20 | 21 | The main function in the **explainr** package is `explain()`. 22 | 23 | ``` 24 | ptest <- prop.test(x = 500, n = 1008) 25 | explain(ptest) 26 | ``` 27 | 28 | # Bug reports 29 | Report bugs as issues on the [GitHub repository](https://github.com/hilaryparker/explainr) 30 | 31 | # Contributors 32 | 33 | * [Hilary Parker](https://github.com/hilaryparker) 34 | * [David Robinson](https://github.com/dgrtwo) 35 | * [Stephanie Hicks](https://github.com/stephaniehicks) 36 | * [Roger Peng](https://github.com/rdpeng) 37 | 38 | # Inspiration 39 | This project draws inspiration from the [CausalImpact package](https://github.com/google/CausalImpact). 40 | -------------------------------------------------------------------------------- /explainr.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 4 10 | Encoding: UTF-8 11 | 12 | RnwWeave: knitr 13 | LaTeX: pdfLaTeX 14 | 15 | AutoAppendNewline: Yes 16 | StripTrailingWhitespace: Yes 17 | 18 | BuildType: Package 19 | PackageUseDevtools: Yes 20 | PackageInstallArgs: --no-multiarch --with-keep.source 21 | PackageRoxygenize: rd,collate,namespace 22 | -------------------------------------------------------------------------------- /inst/themes/bioconductor/MArrayLM.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | name: MArrayLM 3 | type: S3 4 | --- 5 | 6 | ```{r, echo = FALSE, message=FALSE, warning=FALSE} 7 | library(dplyr) 8 | library(biobroom) 9 | ``` 10 | 11 | 12 | ```{r} 13 | mthd <- ifelse(x$method == "ls", "least squares", "robust regression") 14 | ``` 15 | 16 | 17 | The `limma` R/Bioconductor package can be used to find differentially expressed genes between groups of samples in an experiment using microarray or RNA-Sequencing data. The function `lmFit()` is used to fit a linear model for each of the genes including residual errors using `r mthd` for estimation. The function `eBayes()` is used to calculate the likelihood that a residual error would be seen by chance, or that a given is differentially expressed. 18 | 19 | In this analysis, there were `r dim(x$coefficients)[1]` genes assessed for differential expression between `r dim(x$coefficients)[2]` groups (after removing for rows with expression levels all equal to 0). The top 10 genes that appear to be the mostly differentially expressed are 20 | 21 | ```{r kable} 22 | knitr::kable(topTable(x)) 23 | ``` 24 | 25 | 26 | A volcano plot combines the measure of statistical significance with the magnitude of change in differential expression for each gene. The plots compares the log-fold changes versus log-odds of differential expression and is useful to identify large differences. 27 | 28 | ```{r} 29 | limma::volcanoplot(fit, main = "Volcano plot", coef = 2, highlight = 10) 30 | ``` 31 | 32 | The MAplot is a plot of the M-values (log-ratios) vs the A-values (average intensities). 33 | 34 | ```{r} 35 | limma::plotMA(fit, main = "MA plot", coef = 2) 36 | ``` 37 | 38 | A histogram of the p-values 39 | 40 | ```{r} 41 | hist(tidy(x)$p.value, main = "Histogram of p-values\nfor differential expression", xlab = "p-value") 42 | ``` 43 | 44 | 45 | -------------------------------------------------------------------------------- /inst/themes/default/htest.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | name: htest 3 | type: S3 4 | --- 5 | 6 | ```{r} 7 | if (grepl("proportions", x$method)) { 8 | compile_template("prop.test", x = x, theme = theme) 9 | } else { 10 | compile_template("htest.default", x = x, theme = theme) 11 | } 12 | ``` 13 | -------------------------------------------------------------------------------- /inst/themes/default/htest.default.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | name: htest.default 3 | type: S3 4 | --- 5 | 6 | This hypothesis test had a p-value of `r x$p.value`. 7 | -------------------------------------------------------------------------------- /inst/themes/default/power.t.test.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | name: power.t.test 3 | type: S3 4 | --- 5 | 6 | ```{r} 7 | ## Convert power.htest to something usable (later use broom?) 8 | ## z <- as.data.frame(unclass(x)) 9 | z <- x 10 | single <- nrow(z) == 1L ## let's assume single run for now 11 | onesample <- grepl("^One-sample", z$method) ## otherwise two-sample 12 | if(onesample) { 13 | method <- "one-sample *t* test of a normal mean" 14 | } else { 15 | method <- "two-sample *t* test of normal means" 16 | } 17 | 18 | txt1 <- paste0( 19 | "A total of ", ceiling(z$n) + ceiling(z$n) %% 2, 20 | " subjects will be enrolled in this study. Using a ", 21 | method, " we have ", trunc(z$power * 100), 22 | "% power to detect a treatment effect at a two-sided ", z$sig.level, 23 | " significance level, if the true effect is ", 24 | z$delta, " ", 25 | ifelse(z$delta == 1, "unit", "units"), " different from zero. This is based on the assumption that the standard deviation of the response variable is ", 26 | z$sd, "." 27 | ) 28 | 29 | txt2 <- paste0( 30 | "A total of ", ceiling(z$n) + ceiling(z$n) %% 2, 31 | " subjects will be enrolled in this study. Using a ", 32 | method, " we have ", trunc(z$power * 100), 33 | "% power to detect a treatment difference at a two-sided ", z$sig.level, 34 | " significance level, if the true difference in the response between treatment groups is ", 35 | z$delta, " ", ifelse(z$delta == 1, "unit", "units"), ". This is based on the assumption that the standard deviation of the response variable is ", 36 | z$sd, "." 37 | ) 38 | 39 | if(onesample) { 40 | cat(txt1, "\n") 41 | } else { 42 | cat(txt2, "\n") 43 | } 44 | 45 | ``` 46 | 47 | 48 | 49 | 50 | 51 | -------------------------------------------------------------------------------- /inst/themes/default/prop.test.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | name: prop.test 3 | type: S3 4 | --- 5 | 6 | ```{r} 7 | library(dplyr) 8 | library(broom) 9 | tidyx <- tidy(x) 10 | onesamp <- TRUE 11 | if (length(x$estimate) == 2) onesamp <- FALSE 12 | ``` 13 | 14 | ```{r stmt1} 15 | stmt1 <- 16 | if (onesamp) { 17 | paste0( 18 | "This was a one-sample proportion test of the null hypothesis that the true population proportion is equal to ", 19 | x$null.value 20 | ) 21 | } else { 22 | "This was a two-sample proportion test of the null hypothesis that the true population proportions are equal" 23 | } 24 | ``` 25 | 26 | ```{r stmt2} 27 | stmt2 <- 28 | if (x$p.value < 1 - attr(x$conf.int, "conf")) { 29 | if (onesamp) { 30 | paste0( 31 | "conclude that true population proportion is different than ", 32 | x$null.value 33 | ) 34 | } else { 35 | "conclude that two population proportions are not equal" 36 | } 37 | 38 | } else { 39 | if (onesamp) { 40 | paste0( 41 | "cannot conclude that true population proportion is different than ", 42 | x$null.value 43 | ) 44 | } else { 45 | "cannot conclude that two population proportions are different from one another" 46 | } 47 | } 48 | ``` 49 | 50 | ```{r stmt3} 51 | ## TODO: Add logic to take out sample size numbers, in the case that you've inputted a variable rather than a raw value 52 | stmt3 <- 53 | 54 | if (onesamp) { 55 | 56 | samps <- strsplit(x$data.name, ",") %>% 57 | unlist() %>% 58 | strsplit(split = " ") %>% 59 | unlist() 60 | 61 | x1 <- as.numeric(samps[1]) 62 | n1 <- as.numeric(samps[4]) 63 | 64 | paste0( 65 | "The observed sample proportion is ", 66 | x$estimate, 67 | " (", 68 | prettyNum(x1, big.mark=","), 69 | " events out of a total sample size of ", 70 | prettyNum(n1, big.mark=","), 71 | ")" 72 | ) 73 | } else { 74 | 75 | samps <- strsplit(x$data.name, "\\(" ) %>% 76 | unlist() %>% 77 | strsplit(split="\\)") %>% 78 | unlist() %>% 79 | strsplit(split=",") %>% 80 | unlist() 81 | 82 | x1 <- as.numeric(samps[2]) 83 | x2 <- as.numeric(samps[3]) 84 | n1 <- as.numeric(samps[5]) 85 | n2 <- as.numeric(samps[6]) 86 | 87 | paste0( 88 | "The observed difference in proportions is ", 89 | x$estimate[2] - x$estimate[1], 90 | ". The observed proportion for the first group is ", 91 | x$estimate[1], 92 | " (", 93 | prettyNum(x1, big.mark=","), 94 | " events out of a total sample size of ", 95 | prettyNum(n1, big.mark=","), 96 | "). For the second group, the observed proportion is ", 97 | x$estimate[2], 98 | " (", 99 | prettyNum(x2, big.mark=","), 100 | ", out of a total sample size of ", 101 | prettyNum(n2, big.mark=","), 102 | ")" 103 | ) 104 | } 105 | ``` 106 | 107 | ```{r stmt4} 108 | stmt4 <- 109 | 110 | if(onesamp) { 111 | 112 | paste0( 113 | x$null.value + abs(x$estimate - x$null.value), 114 | " or less than ", 115 | x$null.value - abs(x$estimate - x$null.value) 116 | ) 117 | 118 | } else { 119 | 120 | paste0( 121 | abs(x$estimate[2] - x$estimate[1]), 122 | " or less than ", 123 | -abs(x$estimate[2] - x$estimate[1]) 124 | ) 125 | } 126 | ``` 127 | 128 | `r stmt1`. Using a significance level of `r 1 - attr(x$conf.int, "conf")`, we `r if (x$p.value < 1 - attr(x$conf.int, "conf")) "reject" else "do not reject"` the null hypothesis, and `r stmt2`. `r stmt3`. 129 | 130 | The confidence interval for the true `r if (onesamp) "population proportion" else "difference in population proportions"` is (`r tidyx$conf.low`, `r tidyx$conf.high`). This interval will contain the true `r if(onesamp) "population proportion" else "difference in population proportions"` 95 times out of 100. 131 | 132 | The p-value for this test is `r x$p.value`. This, formally, is defined as the probability -- if the null hypothesis is true -- of observing a `r if (onesamp) "sample proportion" else "difference in sample proportions"` that is as or more extreme than the `r if (onesamp) "sample proportion" else "difference in sample proportions"` from this data set. In this case, this is the probability -- if the true `r if (onesamp) paste0("population proportion is ", x$null.value) else "population proportions are equal"` -- of observing a `r if (onesamp) "sample proportion" else "difference in sample proportions"` that is greater than `r stmt4`. 133 | -------------------------------------------------------------------------------- /inst/themes/visual/lm.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | name: lm 3 | type: S3 4 | --- 5 | 6 | ```{r coef_plot} 7 | library(ggplot2) 8 | 9 | td <- tidy(x, conf.int = TRUE) 10 | ggplot(td, aes(estimate, term, color = term)) + 11 | geom_point() + 12 | geom_errorbarh(aes(xmin = conf.low, xmax = conf.high)) + 13 | geom_vline() + 14 | ggtitle("Coefficient plot, with 95% confidence intervals") 15 | ``` 16 | -------------------------------------------------------------------------------- /man/compile_template.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/explain.R 3 | \name{compile_template} 4 | \alias{compile_template} 5 | \title{compile an object using a template} 6 | \usage{ 7 | compile_template(template, theme = "default", ...) 8 | } 9 | \arguments{ 10 | \item{template}{a template, typically loaded from \code{load_template}} 11 | 12 | \item{theme}{name of the theme to use} 13 | 14 | \item{...}{objects to be provided to the template} 15 | } 16 | \value{ 17 | A compiled text version of the object 18 | } 19 | \description{ 20 | compile an object using a template 21 | } 22 | 23 | -------------------------------------------------------------------------------- /man/explain.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/explain.R 3 | \name{explain} 4 | \alias{explain} 5 | \title{Explain an object in plain English} 6 | \usage{ 7 | explain(x, ...) 8 | } 9 | \arguments{ 10 | \item{x}{an object} 11 | 12 | \item{...}{extra arguments} 13 | } 14 | \value{ 15 | A text description of the object 16 | } 17 | \description{ 18 | Explain an object in plain English 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/explain.default.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/explain.R 3 | \name{explain.default} 4 | \alias{explain.default} 5 | \title{explain an S3 object in plain English} 6 | \usage{ 7 | \method{explain}{default}(x, theme = "default", template = NULL, ...) 8 | } 9 | \arguments{ 10 | \item{x}{an object to be explained} 11 | 12 | \item{theme}{theme to use} 13 | 14 | \item{...}{extra arguments} 15 | } 16 | \description{ 17 | explain an S3 object in plain English 18 | } 19 | 20 | -------------------------------------------------------------------------------- /man/explain_line.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/explain_dplyr.R 3 | \name{explain_line} 4 | \alias{explain_line} 5 | \title{explain a line of dplyr code} 6 | \usage{ 7 | explain_line(expr, value, ok, visible) 8 | } 9 | \arguments{ 10 | \item{expr}{expression performed} 11 | 12 | \item{value}{value returned} 13 | 14 | \item{ok}{ok} 15 | 16 | \item{visible}{visible} 17 | } 18 | \description{ 19 | explain a line of dplyr code 20 | } 21 | 22 | -------------------------------------------------------------------------------- /man/explainr_mode.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/explain_dplyr.R 3 | \name{explainr_mode} 4 | \alias{explainr_mode} 5 | \title{register a session so that it explains each line} 6 | \usage{ 7 | explainr_mode() 8 | } 9 | \description{ 10 | register a session so that it explains each line 11 | } 12 | 13 | -------------------------------------------------------------------------------- /man/explainr_output.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/explainr_output.R 3 | \name{explainr_output} 4 | \alias{explainr_output} 5 | \title{Wrap an object as the output of an \code{explain} function} 6 | \usage{ 7 | explainr_output(x) 8 | } 9 | \arguments{ 10 | \item{x}{} 11 | } 12 | \description{ 13 | Wrap an object as the output of an \code{explain} function 14 | } 15 | 16 | -------------------------------------------------------------------------------- /man/explainr_themes.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/zzz.R 3 | \name{explainr_themes} 4 | \alias{explainr_themes} 5 | \title{Built-in themes} 6 | \description{ 7 | These are loaded from the \code{themes/} directory in the package, using 8 | \code{\link{load_themes}}. So far they include: 9 | \itemize{ 10 | \item{default}{default text description} 11 | \item{visual}{graphical displays of objects} 12 | } 13 | } 14 | 15 | -------------------------------------------------------------------------------- /man/load_template.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/load.R 3 | \name{load_template} 4 | \alias{load_template} 5 | \title{Load a .Rmd template for displaying an object} 6 | \usage{ 7 | load_template(path) 8 | } 9 | \arguments{ 10 | \item{path}{Path to the .Rmd template file} 11 | } 12 | \value{ 13 | a list with two components: 14 | \item{header}{A named list containing the YAML components} 15 | \item{content}{A string with the contents of the string} 16 | } 17 | \description{ 18 | Load a .Rmd template for displaying an object 19 | } 20 | 21 | -------------------------------------------------------------------------------- /man/load_theme.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/load.R 3 | \name{load_theme} 4 | \alias{load_theme} 5 | \title{Load a theme, which is a directory of templates} 6 | \usage{ 7 | load_theme(path) 8 | } 9 | \arguments{ 10 | \item{path}{Path to a theme directory of .Rmd files} 11 | } 12 | \value{ 13 | a named list of templates 14 | } 15 | \description{ 16 | Load a theme, which is a directory of templates 17 | } 18 | 19 | -------------------------------------------------------------------------------- /man/load_themes.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/load.R 3 | \name{load_themes} 4 | \alias{load_themes} 5 | \title{Load all themes} 6 | \usage{ 7 | load_themes(directory = system.file("themes", package = "explainr")) 8 | } 9 | \arguments{ 10 | \item{directory}{directory to load themes from} 11 | } 12 | \value{ 13 | a named list of themes 14 | } 15 | \description{ 16 | Load themes, by default from explainr's built-in themes directory. 17 | } 18 | 19 | -------------------------------------------------------------------------------- /man/print.explainr_output.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2 (4.1.0): do not edit by hand 2 | % Please edit documentation in R/explainr_output.R 3 | \name{print.explainr_output} 4 | \alias{print.explainr_output} 5 | \title{Print explainr output} 6 | \usage{ 7 | \method{print}{explainr_output}(x) 8 | } 9 | \arguments{ 10 | \item{x}{} 11 | } 12 | \description{ 13 | Print explainr output 14 | } 15 | 16 | -------------------------------------------------------------------------------- /vignettes/bioconductor.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Introduction to explainr: Using Bioconductor Data" 3 | author: "Hilary Parker, David Robinson, and Stephanie Hicks" 4 | date: "`r Sys.Date()`" 5 | output: rmarkdown::html_vignette 6 | vignette: > 7 | %\VignetteIndexEntry{Introduction to explainr: Using Bioconductor Data} 8 | %\VignetteEngine{knitr::rmarkdown} 9 | \usepackage[utf8]{inputenc} 10 | --- 11 | 12 | ```{r setup, echo = FALSE} 13 | knitr::opts_chunk$set(echo = TRUE, fig.width = 5, fig.height = 5) 14 | # options(digits=3) 15 | ``` 16 | 17 | This is a vignette for the **explainr** R package with the Bioconductor theme. We consider the Bottomly data set available on [Recount](http://bowtie-bio.sourceforge.net/recount/eset_tips.shtml). After finding the differentially expressed genes using two R/Bioconductor packages **voom** + **limma**, the object that is created is an `MArrayLM` object. We will apply the `explain()` function to the `MArrayLM` object which will explain the methods used for finding the differentially expressed genes and provide some basic summary plots. 18 | 19 | 20 | ## Load libraries and RNA-Seq data 21 | ```{r, message=FALSE, warning=FALSE} 22 | # Load libraries 23 | library(Biobase) 24 | library(biomaRt) 25 | library(edgeR) 26 | library(limma) 27 | library(dplyr) 28 | library(explainr) 29 | 30 | # Load data 31 | bottomly.local <- load(url("http://bowtie-bio.sourceforge.net/recount/ExpressionSets/bottomly_eset.RData")) 32 | ``` 33 | 34 | Create the RNA-Seq count table (ExpressionSet), phenotypic information, design matrix. 35 | ```{r} 36 | eset <- exprs(bottomly.eset) 37 | keepMeID <- sapply(1:nrow(eset), function(x){ any(eset[x,] != 0) }) 38 | eset <- eset[keepMeID,] 39 | 40 | pd <- phenoData(bottomly.eset)@data # sample information about the experiment 41 | design <- model.matrix(~pd$strain) 42 | ``` 43 | 44 | Calculate normalization factors to scale raw library sizes 45 | ```{r} 46 | dge <- DGEList(counts = eset) 47 | dge <- calcNormFactors(dge) 48 | 49 | # applies voom transformation to count data 50 | v <- voom(dge, design = design) 51 | ``` 52 | 53 | ## Find the differentially expressed genes 54 | 55 | Create the `MArrayLM` object using the R/Bioconductor `limma` package 56 | ```{r} 57 | # Linear model for each gene and creates an MArrayLM object 58 | fit <- lmFit(v, design) 59 | fit <- eBayes(fit) 60 | ``` 61 | 62 | ## `explain()` the analysis and results 63 | 64 | ```{r, results = 'asis'} 65 | fit %>% explain(theme = "bioconductor") 66 | ``` 67 | 68 | -------------------------------------------------------------------------------- /vignettes/intro.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Introduction to explainr" 3 | author: "Hilary Parker, David Robinson, and Stephanie Hicks" 4 | date: "`r Sys.Date()`" 5 | output: rmarkdown::html_vignette 6 | vignette: > 7 | %\VignetteIndexEntry{Introduction to explainr} 8 | %\VignetteEngine{knitr::rmarkdown} 9 | \usepackage[utf8]{inputenc} 10 | --- 11 | 12 | ```{r setup, echo = FALSE} 13 | knitr::opts_chunk$set(echo = TRUE, fig.width = 5, fig.height = 5) 14 | ``` 15 | 16 | The `explainr` package turns R objects into easily understood plain English. For example, suppose we have a proportion test: 17 | 18 | ```{r ttest} 19 | pt <- prop.test(2, 10, .5) 20 | ``` 21 | 22 | We could turn it into plain English with: 23 | 24 | ```{r explain1} 25 | library(explainr) 26 | explain(pt) 27 | ``` 28 | 29 | In a knitr document, you might prefer to put `results = 'asis'`. For instance, in this next chunk, the output just looks like regular text: 30 | 31 | ```{r explain2, results = 'asis'} 32 | explain(pt) 33 | ``` 34 | 35 | ### Visual theme 36 | 37 | You can change what theme you use. For instance, the `visual` theme, instead of just providing text, also displays images: 38 | 39 | ```{r lmdisplay, results = 'asis'} 40 | m <- lm(mpg ~ wt + mpg, mtcars) 41 | 42 | explain(m, "visual") 43 | ``` 44 | --------------------------------------------------------------------------------