From 2b6a98512561bd2e90ea0e74570600fb79b05c05 Mon Sep 17 00:00:00 2001 From: "Raymond R. Balise" Date: Fri, 23 Feb 2024 13:14:24 -0500 Subject: [PATCH 1/2] Gabriel's feedback and import quarto, man extra quote & example comments, stop if wrong quarto version, new example gists, remove licences, rename run_me.R, add legal to vignette 4 --- DESCRIPTION | 1 + R/make_project.R | 34 ++++++++++++++++++-------- inst/gists/manual_change_qmd_vigette.R | 6 +---- inst/gists/manual_change_rmd_vigette.R | 6 +---- man/make_project.Rd | 15 ++++++------ vignettes/O4_make_a_package.Rmd | 8 +++--- 6 files changed, 38 insertions(+), 32 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 6b3cacb..1f6b6f3 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -48,6 +48,7 @@ Imports: conflicted, glue, gtsummary, + quarto, rio, rlang, rmarkdown, diff --git a/R/make_project.R b/R/make_project.R index 92c5894..df2475f 100644 --- a/R/make_project.R +++ b/R/make_project.R @@ -12,8 +12,8 @@ #' \code{./rstudio/templates/project/}) #' @param type Choose between "Quarto (analysis.qmd)" or #' "R Markdown (analysis.Rmd)" -#' @param example Will the analysis file include an example table/figure?" -#' @param vignette Will the analysis file be saved as a package vignette?" +#' @param example Will the analysis file include an example table/figure? +#' @param vignette Will the analysis file be saved as a package vignette? #' #' @details Behind the scenes, this function used by research_project.dcf when #' a user selects New project... > New Directory > rUM Research Project Template @@ -38,15 +38,14 @@ #' #' @examples #' \dontrun{ +#' # This makes a project with an example Quarto paper in the project's folder. #' make_project(path = "~/test", type = "Quarto (analysis.qmd)", example = TRUE, vignette = TRUE) -#' } -#' \dontrun{ +#' # make_project() allows abbreviations on the project type: "Q" for Quarto or "R" for R Markdown #' make_project(path = "~/test_project", "Q", TRUE, TRUE) -#' } -#' \dontrun{ +#' +#' # This makes a project with an example R Markdown paper in the project's folder. #' make_project(path = "~/test", type = "R Markdown (analysis.Rmd)", example = TRUE, vignette = TRUE) -#' } -#' \dontrun{ +#' # This makes a project with an example paper in the project's folder. #' make_project(path = "~/test_project", "R", example = TRUE) #' } @@ -61,12 +60,27 @@ make_project <- function( # ensure path exists dir.create(path, recursive = TRUE, showWarnings = FALSE) + # get version of Quarto on the machine and save it as a version + the_version <- quarto::quarto_version() + + if (vignette == FALSE){ # make paper project w/o package infrastructure # If the project object does not exist add it. if (length(list.files(path = path, pattern = "\\.Rproj$")) == 0) { usethis::create_project(path = path, open = TRUE, rstudio = TRUE) } } else { # make paper project with package infrastructure + if (type == "Quarto (analysis.qmd)" & the_version < "2.4.549"){ + message( + paste0( + "STOPPING: You need a modern version of Quarto from ", + "https://quarto.org/docs/download/ in order to make the package ", + "with a Quarto vignette." + ) + ) + return(invisible(NULL)) + } + if (length(list.files(path = path, pattern = "\\.Rproj$")) == 0) { usethis::create_package(path = path, open = TRUE, rstudio = TRUE) } @@ -91,14 +105,14 @@ make_project <- function( gist_w_ex_path_rmd <- paste0( "https://gist.githubusercontent.com/RaymondBalise/", "c8399e7b3474a6022eeae373d059a042/", - "raw/cf9080a2d2096ddde5f5550abbb6c790126f7d10/analysis_with_example.Rmd" + "raw/bea479a3a3bcdef9c45122a5ce7b9dcdaec93815/analysis_with_example.Rmd" ) # path to analysis.qmd with example gist_w_ex_path_qmd <- paste0( "https://gist.githubusercontent.com/RaymondBalise/", "40e8e1cc0dec94b225b7cb307f4fa959/raw/", - "d4883d98163f565915e514d96d3e4c9fcdda1405/analysis_with_example.qmd" + "91709c686876f65904be12e0bb8be45f347a5bb0/analysis_with_example.qmd" ) diff --git a/inst/gists/manual_change_qmd_vigette.R b/inst/gists/manual_change_qmd_vigette.R index c279098..9d0a2a3 100644 --- a/inst/gists/manual_change_qmd_vigette.R +++ b/inst/gists/manual_change_qmd_vigette.R @@ -17,10 +17,6 @@ usethis::use_package("tidyverse", type = "imports") usethis::use_vignette("x","x") invisible(file.remove(paste0(here::here(), "/vignettes/x.Rmd"))) -##### For in development set a bogus licence -# cut me later -usethis::use_proprietary_license("Me") - ##### Fix vignette header library(stringr) @@ -52,5 +48,5 @@ readr::write_file(modified_contentX, paste0(here::here(), "/DESCRIPTION")) rm(list = c("modified_contentX", "file_content")) ##### delete this file -invisible(file.remove(paste0(here::here(), "/run_me.R"))) +invisible(file.remove(paste0(here::here(), "/RUN_ME_FIRST.R"))) diff --git a/inst/gists/manual_change_rmd_vigette.R b/inst/gists/manual_change_rmd_vigette.R index 0d66ba3..8e7c03a 100644 --- a/inst/gists/manual_change_rmd_vigette.R +++ b/inst/gists/manual_change_rmd_vigette.R @@ -16,10 +16,6 @@ usethis::use_package("tidyverse", type = "imports") usethis::use_vignette("x","x") invisible(file.remove(paste0(here::here(), "/vignettes/x.Rmd"))) -##### For in development set a bogus licence -# cut me later -usethis::use_proprietary_license("Me") - ##### Fix vignette header library(stringr) @@ -40,5 +36,5 @@ readr::write_file(modified_contentX, paste0(here::here(), "/vignettes/analysis.R rm(list = c("modified_contentX", "file_content")) ##### delete this file -invisible(file.remove(paste0(here::here(), "/run_me.R"))) +invisible(file.remove(paste0(here::here(), "/RUN_ME_FIRST.R"))) diff --git a/man/make_project.Rd b/man/make_project.Rd index 975fffa..747d701 100644 --- a/man/make_project.Rd +++ b/man/make_project.Rd @@ -18,9 +18,9 @@ make_project( \item{type}{Choose between "Quarto (analysis.qmd)" or "R Markdown (analysis.Rmd)"} -\item{example}{Will the analysis file include an example table/figure?"} +\item{example}{Will the analysis file include an example table/figure?} -\item{vignette}{Will the analysis file be saved as a package vignette?"} +\item{vignette}{Will the analysis file be saved as a package vignette?} } \value{ Returns nothing. See description above. @@ -41,15 +41,14 @@ within the RSutdio IDE. See \code{./rstudio/templates/project/}. } \examples{ \dontrun{ + # This makes a project with an example Quarto paper in the project's folder. make_project(path = "~/test", type = "Quarto (analysis.qmd)", example = TRUE, vignette = TRUE) -} -\dontrun{ + # make_project() allows abbreviations on the project type: "Q" for Quarto or "R" for R Markdown make_project(path = "~/test_project", "Q", TRUE, TRUE) -} -\dontrun{ + + # This makes a project with an example R Markdown paper in the project's folder. make_project(path = "~/test", type = "R Markdown (analysis.Rmd)", example = TRUE, vignette = TRUE) -} -\dontrun{ + # This makes a project with an example paper in the project's folder. make_project(path = "~/test_project", "R", example = TRUE) } } diff --git a/vignettes/O4_make_a_package.Rmd b/vignettes/O4_make_a_package.Rmd index 23aa386..608efd5 100644 --- a/vignettes/O4_make_a_package.Rmd +++ b/vignettes/O4_make_a_package.Rmd @@ -1,8 +1,8 @@ --- -title: "Make a Package" +title: "4. Make a Package" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{Make a Package} + %\VignetteIndexEntry{4. Make a Package} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -25,13 +25,13 @@ Saving your data and analyses into an R package helps to create reproducible res All you need to do is add `vignette = TRUE` when you use the `make_project()` function. Once the project is created, run the **run_me.R** file. For example type: 1. `rUM::make_project("~/Desktop/my.example", "R", example=TRUE, vignette=TRUE)`. This creates a new project with all the files for a package in the current directory. The vignette includes an example table and figure and all the R Markdown syntax for adding hyperlinks to the table and figures. -2. After the new project is open, run the **read_me.R** file. The easiest way to do this is by typing `source(run_me.R)` into the RStudio IDE console and then pressing enter. If you are working in RStudio it will ask you if it can/should close windows for two deleted files. Say **Yes**. They are a couple temporary files that we used to set options the project. +2. After the new project is open, run the **RUN_ME_FIRST.R** file. The easiest way to do this is by typing `source(RUN_ME_FIRST.R)` into the RStudio IDE console and then pressing enter. If you are working in RStudio it will ask you if it can/should close windows for two deleted files. Say **Yes**. They are a couple temporary files that we used to set options the project.
![](say_yes.png){width="50%"}
-3. Set the license for your package. If you are not planning on publicly sharing your data we recommend using a proprietary license. For example, type `usethis::use_proprietary_license("Your Name Goes Here")`. To learn more about licences look at the documentation for `use_proprietary_license()` by typing: `?usethis::use_proprietary_license`. +3. Set the license for your package. **REMEMBER: Do share sensitive data. Talk to the data privacy officer at your institution/organization before sharing any data. Ask them for advice on setting a software license.** If you are not planning on publicly sharing your data consider using a proprietary license. For example, type `usethis::use_proprietary_license("Your Name Goes Here")`. To learn more about licences look at the documentation for `use_proprietary_license()` by typing: `?usethis::use_proprietary_license`. You can also learn more at [choosealicense.com](https://choosealicense.com/) or [here](https://gist.github.com/nicolasdao/a7adda51f2f185e8d2700e1573d8a633) but talk to the legal counsel at your institution/organization before making a decision. ## Can I write my vignette with Quarto? From f978182eef8ea20cc8f57269e1de79d8329e5516 Mon Sep 17 00:00:00 2001 From: "Raymond R. Balise" Date: Fri, 23 Feb 2024 13:49:36 -0500 Subject: [PATCH 2/2] First draft of example = TRUE vignette --- vignettes/O5_show_example.Rmd | 73 +++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 vignettes/O5_show_example.Rmd diff --git a/vignettes/O5_show_example.Rmd b/vignettes/O5_show_example.Rmd new file mode 100644 index 0000000..ead1d3b --- /dev/null +++ b/vignettes/O5_show_example.Rmd @@ -0,0 +1,73 @@ +--- +title: "5. Include an example in the analysis paper outline" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{5. Include an example in the analysis paper outline} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + +```{r, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>" +) +``` + +## Introduction + +If you would like to see an example paper, that has code blocks to produce a summary table and a graphic, include the `example = TRUE` argument when you use the `make_project()` function. For example, if you type `rUM::make_project("~/Desktop/my.example", "R", example=TRUE)`, in the **Results** section of the paper you will see code like: + +````r +#| tbl-cap: "Cross-references to tables use labels for the code chunk starting with tbl-." + +# To learn how to use tbl_summary look at https://www.danieldsjoberg.com/gtsummary/ +analysis |> + tbl_summary( + include = c(everything()), # choose your variables here + # change auto_man to the name of your column variable or delete by = auto_man + by = auto_man, # split table by group + missing = "no" # don't list missing data separately + ) %>% + # add_n() %>% # add column with total number of non-missing observations + # add_p() %>% # test for a difference between groups + modify_header(label = "") %>% # update the column header to be blank + bold_labels() +```` + +and + +````r + +#| fig-cap: "Remember figure labels begin with fig-" +# To learn how to use ggplot start here: https://ggplot2.tidyverse.org/#learning-ggplot2 +analysis |> + ggplot() + + labs( + title = "Your short title goes here.", + caption = "Your data sources/citation goes here." + ) + + geom_blank() + # remove geom_blank() and add details here +```` + +You will also notice that there are sentences, which begin with +"As can be seen in" that contain cross-reference hyperlinks to the tables and figures. + +### Simpler Tables +The example table is created using a package called `gtsummary`. It makes completely customizable, beautiful, summary tables which support hyperlinks/cross-references in the sentences you write in your paper. + +A simpler option is to use the `table1()` function from the `table1` package. It makes excellent tables with nearly no typing. If you would like to try it, paste the code below into the `tbl-table1` code chunk. Unfortunately `table1` does not have good support for hyperlinks/cross-references from your writing/prose. + + +````r +library(table1) + +analysis |> + select(everything()) |> # choose your variables here + table1( + # change auto_man to the name of your column variable or delete | auto_man + ~ . | auto_man, + data = _ +) +````