Package 'rUM'

List all slide decks in a package

Description

Returns the names of all Quarto slide decks in a package. This is designed to work with rUM::show_slides() to preview the slide deck. For more information look in the Creating Slides with write_slides() vignette.

Usage

find_slides(package = NULL)

Arguments

package

Character. Provide the package containing one or more slide decks.

Value

A list of class "slide_finder" containing the name of the package and the name of the slides.

Examples

if (interactive()) {
  find_slides("rUM")
}

---

Make an Analysis Project

Description

This function creates the structure for an R package. An analysis.Qmd (or analysis.Rmd) is created in the vignettes directory. This project includes an aggressive .gitignore which is designed to help protect against leaking data (with protected health information), a starter bibliography file called "references" (in standard .bib format), and a stock Citation Style Language (.csl) file for the New England Journal of Medicine.

Usage

make_package(
  path,
  type = c("Quarto (analysis.qmd)", "R Markdown (analysis.Rmd)"),
  example = FALSE,
  overwrite = FALSE,
  openInteractive = TRUE
)

Arguments

path	Path automatically set by research_project.dcf (see ./rstudio/templates/project/)
type	Choose between "Quarto (analysis.qmd)" or "R Markdown (analysis.Rmd)"
example	Will the analysis file include an example table/figure?
overwrite	Will an existing RStudio project be overwritten? This is needed for for Posit.Cloud. You will be prompted to confirm this option.
openInteractive	Should this new project be opened in a new RStudio window? Defaults to TRUE. NOTE: this option exists to prevent RStudio from opening two duplicate versions of the new project when this function is executed from RStudio menus. MODIFY WITH CAUTION.

Details

Behind the scenes, this function used by research_project.dcf when a user selects New project... > New Directory > rUM Research Project Template within the RStudio IDE. See ./rstudio/templates/project/.

Value

Returns nothing. See description above.

Note

If you need to create multiple packages from the same session, restart RStudio/Positron after making each one. See open issue.

Examples

## Not run: 
  # This makes a package with an example Quarto paper in the vignettes folder.
  make_package(path = "~/test", type = "Quarto (analysis.qmd)", example = TRUE)
  
  # make_package() allows abbreviations on the project type: "Q" for Quarto or "R" for R Markdown
  make_package(path = "~/test_project", "Q", TRUE)
  
  # This makes a package with an example R Markdown paper in the vignettes folder.
  make_package(path = "~/test", type = "R Markdown (analysis.Rmd)", example = TRUE)
              
  # This makes a project with an example paper in the vignettes folder.
  make_package(path = "~/test_project", "R", example = TRUE)

## End(Not run)

---

Make an Analysis Project

Description

This function makes an R project that includes an analysis.Rmd or analysis.qmd file using the conflicted and tidyverse packages. This project automatically includes an aggressive .gitignore which is designed to help protect against leaking data (with protected health information), a starter bibliography file called "references" (in standard .bib format), and a stock Citation Style Language (.csl) file for the New England Journal of Medicine.

Usage

make_project(
  path,
  type = c("Quarto (analysis.qmd)", "R Markdown (analysis.Rmd)"),
  example = FALSE,
  vignette = FALSE,
  overwrite = FALSE,
  openInteractive = TRUE
)

Arguments

path	Path automatically set by research_project.dcf (see ./rstudio/templates/project/)
type	Choose between "Quarto (analysis.qmd)" or "R Markdown (analysis.Rmd)"
example	Will the analysis file include an example table/figure?
vignette	Will the analysis file be saved as a package vignette?
overwrite	Will an existing RStudio project be overwritten? This is needed for for Posit.Cloud. You will be prompted to confirm this option.
openInteractive	Should this new project be opened in a new RStudio window? Defaults to TRUE. NOTE: this option exists to prevent RStudio from opening two duplicate versions of the new project when this function is executed from RStudio menus. MODIFY WITH CAUTION.

Details

Behind the scenes, this function used by research_project.dcf when a user selects New project... > New Directory > rUM Research Project Template within the RStudio IDE. See ./rstudio/templates/project/.

Value

Returns nothing. See description above.

Examples

## Not run: 
  # 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)
  
  # make_project() allows abbreviations on the project type: "Q" for Quarto or "R" for R Markdown
  make_project(path = "~/test_project", "Q", TRUE, TRUE)
  
  # 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)
              
  # This makes a project with an example paper in the project's folder.
  make_project(path = "~/test_project", "R", example = TRUE)

## End(Not run)

---

Preview slide deck from a package

Description

Render a Quarto slide deck from the supplied package in the Viewer or browser. For more information look in the Creating Slides with write_slides() vignette.

Usage

show_slides(package = NULL, deck = NULL, ...)

Arguments

package	Character. Provide the package containing one or more slide decks.
deck	Character. The name of the slide deck to render without ".qmd".
...	Optional arguments passed to quarto::quarto_preview().

Note

Uses quarto::quarto_preview() to display the slide deck in the Viewer pane or browser.

Examples

if (interactive()) {
  # Preview a known slide deck name from a package:
  show_slides(package = "rUM", deck = "rUM_the_package")

  # Use find_slides to pipe the output:
  find_slides(package = "rUM") |> show_slides()
}

---

Write a manual page for package dataset documentation

Description

This function produces a roxygen2 R manual (man) page for a dataset that will be included in an R package. To be documented, the dataset needs to be in the global environment. The new documentation template will be named to match the datasets and will be saved in the R folder (i.e., using an analysis dataset will produce the R/analysis.Rd file). The page will indicate if the dataset is a data frame or tibble along with the number of rows and columns. For each variable documentation will indicate the variables a type, factor level information (if appropriate), and a generic description section. If the variable is labelled (using the labelled package or packages which use labelled, like tidyREDCap) the variable label will be used as the default description.

Usage

write_man(the_dataset)

Arguments

the_dataset

Dataset object (unquoted) or dataset as character (quoted)

Value

A .Rd file in the man package directory corresponding to the name of the supplied dataset.

Note

You will need to import the roxygen2 package and add Roxygen: list(markdown = TRUE) to your DESCRIPTION file. If you made a project using rUM this happens automatically.

Examples

if (interactive()) {
  # Dataset object from Global Environment (unquoted)
  write_man(mtcars)
  
  # Dataset object from Global Environment as character string (quoted)
  write_man("mtcars")
}

---

Create a project progress note

Description

This function streamlines project documentation by creating and managing both README.md and dated_progress_notes.md files. It provides interactive prompts for existing files and maintains consistent project documentation structure.

Usage

write_notes(path = here())

Arguments

path	The destination directory for the progress notes file. Defaults to here::here().

Details

The dated_progress_notes.md file is initialized with the current date and is designed to help track project milestones chronologically. If the progress notes file already exists, the function will stop and warn the user.

Value

Creates a chronological project progress notes tracker

Examples

# Create new progress note file in temporary directory
tmp <- tempdir()
write_notes(path = tmp)

---

Create a New Quarto Document

Description

This function creates a new Quarto document (.qmd file) complete with a useful header.

Usage

write_quarto(filename = NULL, path = here(), example = NULL)

Arguments

filename	Character string. The name of the file without the '.qmd' extension. Only letters, numbers, hyphens, and underscores are allowed.
path	Character string. Directory where the file will be created. Defaults to the current project's base directory.
example	Logical. Will the analysis file include a paper example with table/ figure? Default is NULL and will use a default, non-paper template. If this is set to TRUE, then it will use the Quarto paper template with examples of a table and figure with cross-referencing. If this is FALSE, then it will use the Quarto paper template without examples for tables.

Value

Opens file after creating the Quarto document.

Examples

## Not run: 
# Create a new Quarto document
write_quarto(filename = "data_cleaning", path = tempdir())

## End(Not run)

---

Create a project README file

Description

This function streamlines project documentation by creating and managing a README.md file. It provides interactive prompts for existing files and maintains consistent project documentation structure.

Usage

write_readme(path = here())

Arguments

path	The destination directory for the README file. Defaults to here::here().

Details

The README.md template includes structured sections for:

• Project description (study name, principal investigator, author)

• Project setup steps for reproducibility

• File and directory descriptions

• Miscellaneous project notes

If the README file already exists, the function will stop and warn the user. The templates include example documentation that can be modified to suit project needs.

Value

Creates a comprehensive README template for project documentation.

Examples

# Create new README in temporary directory
tmp <- tempdir()
write_readme(path = tmp)

---

Create a Quarto SCSS file

Description

This function creates the .scss file so that any Quarto project can be easily customized with SCSS styling variables, mixins, and rules. When creating additional SCSS files beyond the default custom.scss, the function will attempt to update the YAML of your Quarto document while preserving any existing SCSS configurations.

Usage

write_scss(name = "custom", path = here(), add_to_yaml = FALSE)

Arguments

name	The name of the scss file without extension. Default name is "custom".
path	The destination directory for the SCSS file. Defaults to here::here().
add_to_yaml	Boolean. Add the new SCSS filename to YAML structure.

Details

The function includes a robust YAML handling mechanism that:

• Preserves existing YAML structure and indentation

• Safely adds new SCSS files without disrupting existing ones

• Provides manual instructions if the YAML structure differs from expected

For more information on customizing Quarto documents with SCSS, please refer to https://quarto.org/docs/output-formats/html-themes.html#customizing-themes, https://quarto.org/docs/output-formats/html-themes-more.html, and https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss will provide you with over 1500 lines of SCSS variables.

Value

A .scss file to customize Quarto styling. If name is not "custom", the function will also attempt to update the Quarto document's YAML to include the new SCSS file while preserving any existing SCSS configurations.

Examples

# Create the default custom.scss in a temporary directory
tmp <- tempdir()
write_scss(name = "custom", path = tmp)

# Add another SCSS file and update YAML in the temporary directory
write_scss(name = "special_theme", path = tmp)

---

Create a Quarto slide deck template

Description

Creates a pre-formatted .qmd file for presentation slides using reveal.js along with necessary supporting files (SCSS styling and RStudio theme). The generated template includes optimized YAML configuration and slide structure to quickly start building academic & professional presentations. For more information look in the Creating Slides with write_slides() vignette.

Usage

write_slides(
  filenames,
  path = here(),
  new_folder = "slides",
  example = FALSE,
  template = "none",
  format = "revealjs"
)

Arguments

filenames	Character vector with minimal length of 1. This allows for the ability to batch create multiple slide decks in one function call.
path	Character string. Directory where the file will be created. Defaults to the current project's base directory.
new_folder	Character. Default folder is "slides". Options are: "none": No folder is created. All files (.qmd & other) are created in the working directory (path of here::here()). "all": One folder is created for each value in the length of filenames. "slide_": One folder is created by appending "slides_" to the first file in filenames argument. If filenames = "day_1", then the folder will be named "slides_day_1". A character value.
example	Logical. Whether to include example slides with demonstrations of including content.
template	Character. Whether to include a slide template for common slide layouts and formatting (default: "none") optional: "miami" for a University of Miami theme. optional: "rmed" for a R/Med theme.
format	Character string. Slide format to use. Currently supports 'reveal.js', with planned support for PowerPoint and Beamer in future releases.

Details

The function creates three files:

• A .qmd file with the specified filename containing the slide template

• A slides.scss file for custom styling

• An RStudio theme file for consistent code highlighting

All filenames must contain only letters, numbers, hyphens, and underscores.

Value

Invisibly returns NULL. The created .qmd file is automatically opened in the RStudio editor upon successful creation.

Note

Be sure to specify path = "inst" if you are adding slides to a package.

Examples

if (interactive()) {
  # Create basic slides template in current directory
  write_slides(filenames = "my_presentation")

  # Create slides with example content in a specific directory
  tmp <- tempdir()
  write_slides(filenames = "tutorial_slides", path = tmp, example = TRUE)

  # Create a slidedeck for a package in the inst directory
  tmp <- tempdir()
  write_slides(filenames = "tutorial_slides", path = 'inst', example = TRUE)
}

---