Merge branch 'cran-release-1.0.0'

.Rbuildignore

@@ -12,3 +12,4 @@
 ^vignettes/tntp-style-plots\.rmd$
 ^notes$
 ^cran-comments\.md$
+^CRAN-SUBMISSION$

DESCRIPTION

@@ -1,14 +1,20 @@
 Type: Package
 Package: tntpr
 Title: Data Analysis Tools Customized for TNTP
-Version: 1.0.0
-Author: Sam Firke [aut, cre], Jake Russ [aut, cre], Alex Spurrier [ctb],
-    Dustin Pashouwer [ctb], Kate Mullan [ctb], Shane Orr [ctb], Sam Talcott [ctb]
-Maintainer: Dustin Pashouwer <[email protected]>
-Description: An internal TNTP R package that includes functions and
-    templates customized with TNTP branding. It is intended for this R
-    package to be a one-stop shop for R tools by analysts and other data
-    users at TNTP.
+Version: 1.0.2
+Authors@R: c(
+      person("Dustin", "Pashouwer", role = c("aut", "cre"), 
+             email = "[email protected]"),
+      person("Sam", "Firke", role = "aut"),
+      person("Shane", "Orr", role = "aut",
+             email = "[email protected]"),
+      person("Sam", "Talcott", role = "aut", 
+             email = "[email protected]")
+    )
+Description: An assortment of functions and templates customized to meet 
+    the needs of data analysts at the non-profit organization TNTP. 
+    Includes functions for branded colors and plots, credentials management,
+    repository set-up, and other common analytic tasks.
 License: CC BY 4.0
 URL: https://github.com/tntp/tntpr, https://tntp.github.io/tntpr/
 Depends:

NAMESPACE

@@ -10,7 +10,6 @@ export(colors_tntp_palette)
 export(date_to_sy)
 export(factorize_df)
 export(figureN)
-export(font_se)
 export(header_tntp)
 export(import_segoe_ui)
 export(labelled_to_factors)

R/header_tntp.R

@@ -1,13 +1,12 @@
 #' Insert header_script_tntp.
 #'
-#' Call this function inside a .R file to insert the standard TNTP header.
+#' Call this function from inside a .R file in RStudio to insert the standard
+#' TNTP header into your active script.
 #'
 #' @export
 #' @returns nothing
-#' @examples
-#' \dontrun{
+#' @examplesIf rstudioapi::isAvailable()
 #' header_tntp()
-#' }
 #'
 header_tntp <- function() {
   rstudioapi::insertText("# TITLE: [enter]

R/knitr-utils.R

@@ -6,8 +6,8 @@
 #'
 #' @returns nothing
 #' @export
-#' @examples
-#' # not run: set_data_memo_formatting()
+#' @examplesIf interactive()
+#' set_data_memo_formatting()
 #'
 set_data_memo_formatting <- function() {
   # set knitr options
@@ -25,10 +25,12 @@ set_data_memo_formatting <- function() {
 #' Create sequential figure numbers
 #'
 #' @param x character string description of the figure
-#' @returns nothing
+#' @returns An atomic character vector prepended with a Figure number
 #' @export
 #' @examples
-#' # not run, in RMarkdown doc: `r figureN("Distribution of cars by cylinder count")`
+#'
+#' figureN("Distribution of cars by cylinder count")
+#' # Inline RMarkdown code: `r figureN("Distribution of cars by cylinder count")`
 #'
 #' #
 figureN <- local({
@@ -47,10 +49,12 @@ figureN <- local({
 #'
 #' @param x character string description of the figure
 #'
-#' @returns nothing
+#' @returns An atomic character vector prepended with a Table number
 #' @export
 #' @examples
-#' # not run, in RMarkdown doc: `r tableN("Distribution of cars by cylinder count")`
+#'
+#' tableN("Distribution of cars by cylinder count")
+#' # Inline RMarkdown code: `r tableN("Distribution of cars by cylinder count")`
 tableN <- local({
   i <- 0
   function(x) {

R/palette_tntp.R

@@ -60,9 +60,8 @@ palette_tntp <- function(...) {
 #' @md
 #'
 #' @examples
-#' \dontrun{
 #' tntp_colors()
-#' }
+#'
 #' @export
 "colors_tntp"
 colors_tntp <- c( # TNTPPalette
@@ -112,9 +111,8 @@ colors_tntp <- c( # TNTPPalette
 #'
 #' @md
 #' @examples
-#' \dontrun{
 #' tntp_colors()
-#' }
+#'
 #' @export
 "colors_tntp_palette"
 colors_tntp_palette <-
@@ -144,9 +142,8 @@ colors_tntp_palette <-
 #'
 #' @md
 #' @examples
-#' \dontrun{
 #' tntp_palette('likert_6')
-#' }
+#'
 #' @export
 "colors_tntp_likert"
 colors_tntp_likert <-
@@ -167,9 +164,8 @@ colors_tntp_likert <-
 #'
 #' @md
 #' @examples
-#' \dontrun{
 #' tntp_palette('bg_6')
-#' }
+#'
 #' @export
 "colors_tntp_likert_orange_to_green"
 colors_tntp_likert_orange_to_green <-
@@ -191,9 +187,8 @@ colors_tntp_likert_orange_to_green <-
 #'
 #' @md
 #' @examples
-#' \dontrun{
 #' show_tntp_palette()
-#' }
+#'
 #' @export
 "palette_names"
 palette_names <- c(
@@ -216,9 +211,8 @@ palette_names <- c(
 #'
 #' @returns a character vector
 #' @examples
-#' \dontrun{
-#' colors <- palette_tntp_scales('likert_5pt')
-#' }
+#' colors <- tntp_palette("likert_5")
+#'
 #' @export
 #'
 palette_tntp_scales <- function(palette = palette_names) {
@@ -257,7 +251,6 @@ palette_tntp_scales <- function(palette = palette_names) {
 #' @returns a ggplot Scale object
 #'
 #' @examples
-#' \dontrun{
 #' library(ggplot2)
 #' library(dplyr)
 #'
@@ -268,7 +261,6 @@ palette_tntp_scales <- function(palette = palette_names) {
 #' ggplot(x, aes(x = cyl, y = n, fill = am)) + # you need a fill aesthetic
 #'   geom_col() +
 #'   scale_fill_manual(values = tntp_palette())
-#' }
 #'
 scale_colour_tntp <- function(palette = palette_names,
                               ...) {

R/setup_repo.R

@@ -9,6 +9,7 @@
 #' that project and the analyst(s) working on it.  These latter two values are
 #' used to create a README.Md file.
 #'
+#' @param project_path the path to the main project directory. To use the current project, use `project_path = here::here()`.
 #' @param subfolder a character vector containing the concise name of a project subfolder.
 #' E.g., if the repository is the name of a city "Anywhere City", a project subfolder might be
 #' "ela_access" or "aps_talent_landscape").
@@ -20,24 +21,31 @@
 #' @export
 #' @returns nothing
 #' @examples
-#' # After the user has created a repository "Anywhere City" and set their working
-#' # directory to that folder:
-#' \dontrun{
-#' setup_repo("ela_access",
-#'   proj_name = "Access to Grade-Level ELA Content",
-#'   analyst_name = "Dustin Pashouwer and Sam Firke")
-#' }
-setup_repo <- function(subfolder, proj_name, analyst_name) {
+#' # Setting up in a temporary directory
+#' setup_repo(project_path = tempdir(),
+#'            subfolder = "ela_access",
+#'            proj_name = "Access to Grade-Level ELA Content",
+#'            analyst_name = "Dustin Pashouwer and Sam Firke")
+setup_repo <- function(project_path, subfolder, proj_name, analyst_name) {
+  if (missing(project_path)) {
+    cli::cli_abort("Required argument {.var project_path} is missing. For your current project, run with {.code project_path = here::here()}.")
+  }
+  if (!dir.exists(project_path)) {
+    cli::cli_abort("Path {.val {project_path}} is not a valid directory.")
+  }
   if (missing(subfolder)) {
-    stop("Specify the subfolder name of the project within this repo you'll be working on")
+    cli::cli_abort("Required argument {.var subfolder} is missing. Please provide a name for your subfolder.")
   }
   if (missing(proj_name)) {
-    stop("Specify the full name of the subfolder project as it should appear in the README")
+    cli::cli_abort("Required argument {.var proj_name} is missing. Please provide a full name for the subfolder project as it should appear in the README.")
   }
   if (missing(analyst_name)) {
-    stop("Specify the analyst(s) working on this subfolder project")
+    cli::cli_abort("Required argument {.var analyst_name} is missing. Please specify the analyst(s) working on this subfolder project.")
   }
 
+  # Fixes issues with ~ leading to different paths in different functions
+  project_path <- normalizePath(project_path)
+
   # Files for git to ignore
   to_ignore <- c(
     ".Rhistory", ".RData", ".Rproj.user" # set RStudio to not store .Rhistory
@@ -47,22 +55,27 @@ setup_repo <- function(subfolder, proj_name, analyst_name) {
   # Create project using the current working directory
   #  If no .Rproj is returned (may see a .here file) then ensure
   #  RStudio is available
-  usethis::create_project(path = getwd())
-  unlink("R", recursive = TRUE) # create_project created "R" folder, we don't want
-  usethis::use_git_ignore(ignores = to_ignore)
+  usethis::create_project(path = normalizePath(project_path))
+  unlink(file.path(project_path, "R"), recursive = TRUE) # create_project created "R" folder, we don't want
+  usethis::with_project(
+    project_path,
+    usethis::use_git_ignore(ignores = to_ignore),
+    quiet = TRUE
+  )
 
   # Create subfolder
-  invisible(lapply(subfolder, setup_subdirectory, proj_name, analyst_name))
+  invisible(lapply(subfolder, \(subfolder) setup_subdirectory(project_path, subfolder, proj_name, analyst_name)))
+
 
   # Create main repo readme
-  if (!any(grepl("README.Md", list.files(), ignore.case = TRUE))) {
-    writeLines(create_repo_readme(proj_name, analyst_name), "README.Md")
+  if (!any(grepl("README.Md", list.files(project_path), ignore.case = TRUE))) {
+    writeLines(create_repo_readme(project_path, proj_name, analyst_name), file.path(project_path, "README.Md"))
   } else {
     overwrite_repo_readme <- utils::menu(c("Keep current README.Md", "Replace with template README.Md"),
       title = "This repository already contains a file README.Md.  Do you wish to replace with the tntpr template README file?"
     )
     if (overwrite_repo_readme == 2) {
-      writeLines(create_repo_readme(proj_name, analyst_name), "README.Md")
+      writeLines(create_repo_readme(project_path, proj_name, analyst_name), file.path(project_path, "README.Md"))
     }
   }
 }
@@ -82,6 +95,7 @@ setup_repo <- function(subfolder, proj_name, analyst_name) {
 #' and create the RProject and .gitignore files.  Add subsequent analysis project folders
 #' with this function.
 #'
+#' @param project_path the path to the main project directory. To use the current project, use `project_path = here::here()`.
 #' @param subfolder a character vector containing the concise name of a project subfolder.
 #' E.g., if the repository is the name of a city "Anywhere City", a project subfolder might be
 #' "ela_access" or "aps_talent_landscape").
@@ -93,71 +107,80 @@ setup_repo <- function(subfolder, proj_name, analyst_name) {
 #' @export
 #' @returns nothing
 #' @examples
-#' # When there's already a repository "Anywhere City" with an RProject and a .gitignore
-#' # and a new project analysis subfolder is needed within that repo:
-#' \dontrun{
-#' setup_subdirectory("ela_access",
-#   proj_name = "Equitable Access to Grade-Level ELA",
-#   analyst_name = "Dustin Pashouwer and Sam Firke")
-#' }
-
-setup_subdirectory <- function(subfolder, proj_name, analyst_name) {
+#' # Setting up in a temporary directory
+#' setup_subdirectory(tempdir(),
+#'                    subfolder = "ela_access",
+#'                    proj_name = "Equitable Access to Grade-Level ELA",
+#'                    analyst_name = "Dustin Pashouwer and Sam Firke")
+
+setup_subdirectory <- function(project_path, subfolder, proj_name, analyst_name) {
+  if (missing(project_path)) {
+    cli::cli_abort("Required argument {.var project_path} is missing. For your current project, run with {.code project_path = here::here()}.")
+  }
+  if (!dir.exists(project_path)) {
+    cli::cli_abort("Path {.val {project_path}} is not a valid directory.")
+  }
+  if (missing(subfolder)) {
+    cli::cli_abort("Required argument {.var subfolder} is missing. Please provide a name for your subfolder.")
+  }
   if (missing(proj_name)) {
-    stop("Specify the full name of the subfolder project as it should appear in the README")
+    cli::cli_abort("Required argument {.var proj_name} is missing. Please provide a full name for the subfolder project as it should appear in the README.")
   }
   if (missing(analyst_name)) {
-    stop("Specify the analyst(s) working on this subfolder project")
+    cli::cli_abort("Required argument {.var analyst_name} is missing. Please specify the analyst(s) working on this subfolder project.")
   }
 
+  # Fixes issues with ~ leading to different paths in different functions
+  project_path <- normalizePath(project_path)
+
   # Check if project exists in main directory, if not create it
-  existing_files <- list.files(all.files = TRUE)
+  existing_files <- list.files(path = project_path, all.files = TRUE)
   if (!any(grepl(".Rproj$", existing_files))) {
-    usethis::create_project(path = getwd())
-    unlink("R", recursive = TRUE) # create_project created "R" folder, we don't want
+    usethis::create_project(path = project_path)
+    unlink(file.path(project_path, "R"), recursive = TRUE) # create_project created "R" folder, we don't want
   }
   if (!any(grepl(".gitignore", existing_files))) {
     to_ignore <- c(
       ".Rhistory", ".RData", ".Rproj.user", "~$*" # set RStudio to not store .Rhistory
       # and .RData ... but just in case someone didn't
     )
-    usethis::use_git_ignore(ignores = to_ignore)
+    usethis::with_project(
+      project_path,
+      usethis::use_git_ignore(ignores = to_ignore)
+    )
   }
 
   # Create project directories
-  dirs_to_make <- paste(
+  dirs_to_make <- file.path(
     subfolder,
-    c(
-      "data",
+    c("data",
       "data/raw",
       "data/clean",
       "code",
       "code/prep", # these scripts should read from the data/raw directory
       "code/analysis", # these scripts should read from the data/clean directory
-      "output"
-    ), # Reports, with figures etc. in subdirectories as needed
-    sep = "/"
-  )
-  invisible(lapply(dirs_to_make, usethis::use_directory))
+      "output")) # Reports, with figures etc. in subdirectories as needed
 
+  invisible(lapply(dirs_to_make, \(dir) {
+    usethis::with_project(project_path,
+                          usethis::use_directory(dir),
+                          quiet = TRUE)
+  }))
 
   # Create subfolder readme
-  if (!any(grepl("README.Md", list.files(subfolder), ignore.case = TRUE))) {
+  if (!any(grepl("README.Md", list.files(file.path(project_path, subfolder)), ignore.case = TRUE))) {
     writeLines(
       create_subfolder_readme(proj_name, analyst_name),
-      paste0(subfolder, "/README.Md")
+      file.path(project_path, subfolder, "README.Md")
     )
   } else {
-    warning(paste0(
-      "README.Md already exists in subdirectory ",
-      subfolder,
-      "; no new README.Md created"
-    ))
+    cli::cli_warn("{.val README.Md} already exists in subdirectory {.val {subfolder}}; no new {.val README.Md} created.")
   }
 }
 
 # Create the vector of info to generate a standard README.Md main repo template
-create_repo_readme <- function(proj_name, analyst) {
-  repo_dir <- getwd()
+create_repo_readme <- function(project_path, proj_name, analyst) {
+  repo_dir <- project_path
   repo_dir <- stringr::str_split(repo_dir, "/")
   repo_dir <- dplyr::last(repo_dir[[1]])