Merge pull request #49 from RaymondBalise/gabriel_feedback

Gabriel feedback

DESCRIPTION

@@ -48,6 +48,7 @@ Imports:
     conflicted,
     glue,
     gtsummary,
+    quarto,
     rio,
     rlang,
     rmarkdown,

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"
   )
 
 

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")))
 

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")))
 

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.
 
 <center>
 ![](say_yes.png){width="50%"}
 </center>
 
-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?
 

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 = _
+) 
+````