# 3. Create a Research Project with R Markdown and rUM

## Introduction

This is a collection of document templates, available through R, from your friends at the University of Miami (UM). \(R+UM=rUM\)

The `rUM` package will help you create research manuscripts by removing the configuration hassles commonly encountered when learning to write papers using R. `rUM` will initialize a new RStudio project and a Markdown file that includes the outline for a research paper. The Markdown file comes preconfigured with a YAML header (don’t worry if you don’t know what that means yet) with code chunks to load the `tidyverse` and `conflicted` packages. Manuscript sections have been created for Introduction, Methods, Results, Conclusion, and References. The project also includes a `.gitignore` file which is designed to help protect against accidentally leaking data when using git with websites like www.github.com.

rUM’s documentation can be found here:

- https://raymondbalise.github.io/rUM/
- https://github.com/RaymondBalise/rUM

## How do I get `RMarkdown` and `rUM`? (Add a “quart o’ `rUM`”!)

1. Modern version RStudio (v2022.07 or later) ships with R Markdown integrated into the RStudio IDE.

2. Add `rUM` to your computer by:

   - using RStudio: click on the Packages tab in the bottom right windowpane, click the Install button, type rUM, and click Install.
   - downloading rUM from CRAN and installing it by running this code in R console:

       install.packages("rUM")

   - downloading the latest version of rUM from GitHub by running commands into the R console:

       if (!requireNamespace("remotes")) install.packages("remotes")
       remotes::install_github("RaymondBalise/rUM")

3. Use `rUM` by running this in the console of RStudio:

    library(rUM)

## Ordering `rUM` from the Menu

To create a research project that uses `rUM`, follow these steps. This will initialize a new RStudio project that has an `analysis.Rmd` R Markdown file using the `tidyverse` and `conflicted` packages and some other useful files which are described below.

1. Using the RStudio menus, choose: File > New Project > New Directory

2. Scroll down and then select `rUM` Research Project Template

   rUM Research Project Template

3. Specify the location of where your research project will be saved

   Choose location to save your rUM project in RStudio

## Add `rUM` into an existing folder/directory that does not have an RStudio project.

What if you have already created a folder containing the important files for your project? Create a new project in your existing folder! This will now be your project directory (complete with a `.Rproj` file).

1. Navigate to File > New Project > Existing Directory

2. Specify the location of where your research project will be saved

   Existing project working directory window in RStudio

3. Run the following script in your console:

    # Change the text inside the quotes on the next line to indicate the path to your folder/directory.
    PATH <- "~/Documents/blah"

    make_project(PATH, type = "R Markdown (analysis.Rmd)")

## After your `rUM` has been served

A new project directory has been created and it will be populated with these files:

- An aggressive `.gitignore` to help prevent the unintended sharing of sensitive study information or protected health information (PHI).
- `analysis.Rmd` is a Markdown template for writing your research project. It has a preconfigured YAML header; Introduction, Methods, Results, Conclusion, and Reference sections; and a code chunk to construct your bibliography using `knitr::write_bib()`.
- An empty folder named `data`. This folder is listed within the `.gitignore`. That means that git should not track these files. This should help prevent data leakage but be sure to talk to a data security expert before sharing any biomedical projects on websites like GitHub.
- A `.Rproj` file with the same name as your project folder.
- Two text files, `packages.bib` and `references.bib`, which are used to hold details for your paper’s bibliography. Refer to the Methods and References sections, respectively, within the `analysis.Rmd` file for initial examples of how to add/use references.
- `the-new-england-journal-of-medicine.csl` is the citation style language (CSL) based on the New England Journal of Medicine requirements.

Newly created files:

Display of newly created rUM project files in the RStudio Files pane

`analysis.Rmd`:

Screenshot of analysis.qmd template structure using the visual editor layout

## `rUM` infused Markdown headers

1. Navigate to File > New File > R Markdown

   Navigating the RStudio console to access R Markdown rUM headers

2. Select From Template

   RStudio menu window displaying to choose “html2 with rUM” to use the R Markdown headers

3. Choose a template:

- html2 with rUM
- html2 Details with rUM
- pdf2 showing LaTeX with rUM
- bookdown_site with rUM

This will create a new subdirectory in your current working directory with the same name as the name of the `.Rmd` file you specified. Within this directory, you will find the `analysis.Rmd` R Markdown file. For example, if you created an R Markdown file called `wrangle_cytometry_data.Rmd` with the steps above, then your current directory will now have a subdirectory called `wrangle_cytometry_data/` which will contain the file `wrangle_cytometry_data.Rmd` and any subsequent files from the knitting process (such as `.PDF`, `.html`, or `.docx` files created by knitting the R Markdown document).

### What are the headers

#### html2 with rUM

This is a basic web page

#### html2 Details with rUM

This is a basic web page with a table of contents

#### pdf2 showing LaTeX with rUM

PDF report where table and figures don’t float to other pages.

#### bookdown_site with rUM

A bookdown website with a good table of contents for a book

### Session

If you are new to R, ignore this.

    sessionInfo()
    #> R version 4.5.0 (2025-04-11)
    #> Platform: aarch64-apple-darwin20
    #> Running under: macOS Sequoia 15.5
    #>
    #> Matrix products: default
    #> BLAS:   /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRblas.0.dylib
    #> LAPACK: /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    #>
    #> locale:
    #> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    #>
    #> time zone: America/New_York
    #> tzcode source: internal
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] digest_0.6.37     R6_2.6.1          fastmap_1.2.0     xfun_0.52
    #>  [5] cachem_1.1.0      knitr_1.50        htmltools_0.5.8.1 rmarkdown_2.29
    #>  [9] lifecycle_1.0.4   cli_3.6.5         sass_0.4.10       jquerylib_0.1.4
    #> [13] compiler_4.5.0    rstudioapi_0.17.1 tools_4.5.0       evaluate_1.0.4
    #> [17] bslib_0.9.0       yaml_2.3.10       rlang_1.1.6       jsonlite_2.0.0