“R will always be arcane to those who do not make a serious effort to learn it. It is not meant to be intuitive and easy for casual users to just plunge into. It is far too complex and powerful for that. But the rewards are great for serious data analysts who put in the effort.”

— Berton Gunter R-help August 2007 (archived at https://perma.cc/KY9N-2FTT)

“Evelyn Hall: I would like to know how (if) I can extract some of the information from the summary of my nlme.

Simon Blomberg: This is R. There is no if. Only how.”

— Evelyn Hall and Simon ‘Yoda’ Blomberg, R-help April 2005 (archived at https://perma.cc/KY9N-2FTT)

1 Learning R

1.1 Base R

Here are a slew of resources for learning base R (in addition to the documents in the lab’s Primer Articles folder):

1.2 Statistics (using R)

The following are resources for learning statistics using R.

1.3 tidyverse

The following are resources for learning tidyverse, which is a collection of R packages for data management:

1.4 Getting Help/Questions

If you have R questions, you can ask them in a number of places:

The following article provides additional resources and good guidance: https://www.r-bloggers.com/where-to-get-help-with-your-r-question/ (archived at https://perma.cc/4RRE-KL33).

When posting a question on forums or mailing lists, keep a few things in mind:

  • Read the posting guidelines before posting!
  • Be respectful of other people and their time. R is free software. People are offering their free time to help. They are under no obligation to help you. If you are disrespectful or act like they owe you anything, you will rub people the wrong way and will be less likely to get help.
  • Provide a minimal, reproducible example. Providing a minimal, reproducible example can be crucial for getting a helpful response. By going to the trouble of creating a minimal, reproducible example and identifying the minimum conditions necessary to reproduce the issue, you will often figure out how to resolve it. Here are guidelines on providing a minimal, reproducible example: https://stackoverflow.com/help/minimal-reproducible-example (archived at https://perma.cc/6NUB-UTYF). Here are a good example and guidelines for providing a minimal, reproducible example in R: https://stackoverflow.com/a/5963610 (archived at https://perma.cc/PC9L-DQZG). Provide a reprex whenever possible: https://reprex.tidyverse.org.

2 Initial Set Up

Note: many of these initial setup steps described below are not necessary for general use; many of these steps are necessary only for using lab-related repositories (e.g., to gain API access to export data from REDCap, to use absolute paths rather than relative paths so repos can communicate with each other, etc.).

  1. Make sure you are logged onto a computer that can access the lab server (either a lab computer, or a computer you can VPN into the lab server), and that you have admin access to install and uninstall software
  2. Install R (https://www.r-project.org) into a directory that contains no spaces; On PC, change the location from the default C:/Program Files/R/[R-VERSION] (which contains a space) to C:/R/[R-VERSION] (which does not contain any spaces; archived at https://perma.cc/6VMX-3LYX—this is because some packages that require compilation to install cannot read filepaths with spaces; archived at https://perma.cc/XA3V-JTPY); may have to right click and “Run As Administrator”
    • If R was already installed in a directory that contains spaces (e.g., C:/Program Files/R/[R-VERSION]), uninstall R before installing it in a directory that doesn’t contain spaces
  3. Install RStudio Desktop (https://www.rstudio.com/products/rstudio/download/) in the main program files directory; may have to right click and “Run As Administrator”. RStudio is the best available graphical user interface for R.
  4. Set the executables for R and RStudio to always run with administrator permissions.
    • If on Windows, open File Explorer and find the main executable of R (C:/R/[R-VERSION]/bin/R.exe) and RStudio (C:/Program Files/RStudio/bin/RStudio.exe). Right-click it to open the contextual menu. Then, click or tap on “Properties”. In the Properties window, go to the Compatibility tab. At the bottom of the window, check the box next to the “Run this program as an administrator” option, and then click or tap on Apply or OK.
  5. Install tools to allow you to compile R packages so you can install packages from source, if necessary (i.e., if package binaries are not available):
  6. Set up git, GitLab, and the GitHub Desktop App in the main program files directory; may have to right click and “Run As Administrator”; For instructions setting up and using GitLab, see here: https://devpsylab.github.io/DataAnalysis/git.html#toBegin
  7. The Rprofile.site file in the etc folder of the R installation directory is the code that is run for every user at the beginning each time you load R. We will update the default Rprofile.site file with the lab’s Rprofile.site file so R installs packages in the correct location, sets the default package repository, updates packages, and gives you a fortune cookie. To do this, perform the following steps:
    • Rename the Rprofile.site file in the R installation directory (C:/R/R-[InsertVersionNumber]/etc/Rprofile.site) to be Rprofile_BACKUP.site
    • Download the lab’s Rprofile.site file located in this repository at the following location (https://research-git.uiowa.edu/PetersenLab/R-InitialSetup/-/blob/master/R%20Setup%20Files/Rprofile.site), and paste it into the R installation directory (PC: C:/R/R-[InsertVersionNumber]/etc/Rprofile.site; Mac: /Library/Frameworks/R.framework/Versions/[InsertVersionNumber]/Resources/etc/Rprofile.site)
  8. The .Rprofile file in the user’s Documents folder is the code that is run for the particular user at the beginning each time you load R. We will update the default .Rprofile file (if there is one) with the lab’s .Rprofile file so R knows which computer you are using and which path to use (relative to where your R projects are located). To do this, perform the following steps:
    • Download the lab’s .Rprofile template file in this repository at the following location, and make sure to remove anything besides .Rprofile in the filename: https://research-git.uiowa.edu/PetersenLab/R-InitialSetup/-/blob/master/R%20Setup%20Files/.Rprofile
    • Open the lab’s .Rprofile file, and revise it with your HawkID
    • Revise the lab’s .Rprofile file with the local path to the Documents folder for each of the computers you will use to access R (e.g., home computer, work computer, laptop). Make sure to use forward slashes (/), not back slashes (\) in the path.
    • You will save the file in your HOME directory. To find the HOME directory, open R and type the following command: Sys.getenv("HOME")—the output of the command is the location of your HOME directory; If this is a lab computer, it may be located here: //home.iowa.uiowa.edu/[user]/Documents. If this is your personal computer, it may be located here: PC: C:/Users/[user]/Documents; Mac: /Users/[user]. Then close R.
    • If your HOME directory is in a OneDrive folder (or another cloud-based sync folder), you will want to change the directory of your HOME path so that it is not in a OneDrive folder. To do that, open Environment Variables (archived at https://perma.cc/A2E5-B5VA) in Windows. Then, add/edit HOME as the “variable name” with the intended location as the “variable value” (e.g., C:/Users/[user]/Documents, where you replace “user” with your HawkID).
      • You may also solve this issue by placing the following command in the Rprofile.site from the previous step
        • Sys.setenv("HOME" = "C:/Users/[specific user ID])/Documents")
    • Move the revised .Rprofile file to the HOME directory and overwrite the original .Rprofile file (if it exists). You may have to show hidden files in order to see the file (PC: see Windows Explorer settings; Mac: Command+Shift+Dot).
    • Make sure to show filename extensions in your file explorer window, and make sure the file is named .Rprofile (not .Rprofile.Rprofile). Make sure there is a period at the beginning of the filename.
  9. Run RStudio. If the Rprofile.site and .Rprofile files are correctly set up, they should pre-populate your path location when you open R. If the contents of the Global Environment in RStudio are empty, your Rprofile.site and/or .Rprofile files are not set up correctly.
    • If you get this error (Error: could not find function "install.packages"), run the following line manually and then restart RStudio after the package finishes installing: install.packages("fortunes")
  10. For reproducibility purposes, prevent R/RStudio from saving your workspaces automatically using the following steps:
    • With RStudio running, choose Tools → Global Options from the menus.
    • In the Options dialog, change the value for Save workspace to .RData on exit to Never.
    • Click OK.
  11. Install the petersenlab R package using the following steps:
    • Install the remotes package using the following command: install.packages("remotes")
    • Install the petersenlab package using the following command: remotes::install_github("DevPsyLab/petersenlab")
  12. Request an API token for the following REDCap project(s); note: please check with Dr. P before requesting an API token. In general, RAs should not have an API token.
  13. Complete the survey(s) provided by REDCap administration
    • The first section will be some basic questions about the planned usage of the API(s)
      • You will need to provide the public IP address for your workspace computer
      • To obtain the public IP address for a Windows PC:
        • Open Command Prompt
        • Type in ipconfig and press Enter
        • The IPv4 Address corresponds to your public IP
  14. When your API token has been approved for these projects, open the Encrypt REDCap Token.R script: https://research-git.uiowa.edu/petersenlab/R-InitialSetup/blob/master/REDCap%20Credentials/Encrypt%20REDCap%20Token.R
  15. Revise the API tokens to reflect yours, then run the script to save your encrypted credentials on the lab server and your encryption key on your local computer
    • Verify that the Encryption Key (REDCap Encryption Key.RData) was saved where you intended it to be saved on your local computer
    • Verify that a file named with your HawkID was saved here: //lc-rs-store24.hpc.uiowa.edu/lss_itpetersen/Lab/Studies/School Readiness Study/Data Management/REDCap/Tokens/
  16. Copy the Encryption Key (REDCap Encryption Key.RData) to the comparable location of any other computers you own that you plan to access the data from
    • The file has to be in the comparable location (relative to the path variable you set in Rprofile.site) of every computer in order for it to be found by the Export Data.R script. The default location is: file.path(path, "GitHub/R/Data/REDCap Encryption Key.RData"), so if path is set as "C:/User/YourName", the file would be saved in: C:/User/YourName/GitHub/R/Data/REDCap Encryption Key.RData. The recommended location for GitHub repos is to create a folder titled GitHub in your Documents folder, and to put repos in the GitHub folder; it is NOT recommended to put git repos in a OneDrive folder because git files tend not to play nice with syncing services (archived at https://perma.cc/XZ6F-43G3; e.g., OneDrive, Dropbox)
  17. Add the SRS Data Processing repo from the lab drive to your GitHub Desktop App (//lc-rs-store24.hpc.uiowa.edu/lss_itpetersen/Lab/Studies/School Readiness Study/Data Processing)
  18. Open RStudio by using “Run as Administrator” (always open RStudio as an administrator so it has write access to the program files directory);
  19. Open the Export Data.R script in R: https://research-git.uiowa.edu/petersenlab/srs/SRS-DataProcessing/blob/master/1.%20Export%20Data/Export%20Data.R \\lc-rs-store24.hpc.uiowa.edu\lss_itpetersen\Lab\Studies\School Readiness Study\Data Processing\1. Export Data\Export Data.R
  20. Ensure your HawkID and location of your encryption key in the script are correct, and then run the script to verify that you can export data from REDCap
  21. For antialiased plots in RStudio, change the Graphics backend to Cairo: Tools → Global Options → Graphics

3 Lab Package

The petersenlab package is here: https://devpsylab.github.io/petersenlab. To install the petersenlab package, see instructions here.

4 Install Packages

To install and load R packages, see the instructions here.

5 Update Packages

To update packages, use the following code:

Code
update.packages(checkBuilt = TRUE)

One indication that the packages might not be updating to the latest version is seeing the same packages showing as needing an update after having run the update.packages() function. If this does not update the package(s) to the latest version, you may need to install the latest version of the package(s) from source (see the section on “Initial Set Up” of R for the software needed to install R packages from source):

Code
update.packages(checkBuilt = TRUE, type = "source")

6 Update R

Instructions adapted from: https://mirror.las.iastate.edu/CRAN/bin/windows/base/rw-FAQ.html#What_0027s-the-best-way-to-upgrade_003f (archived at https://perma.cc/W5QW-MA6Q)

  1. Uninstall R
  2. Install the new R version into a directory that contains no spaces (see Step 2 in the Initial Set Up section above)
  3. [You only need to do this step if you installed packages in the R-version-specific “Library” folder rather than the common/shared “Packages” folder—that is, you don’t need to do this step if you used the lab’s Rprofile.site file, as described above, which installs packages to the common/shared “Packages” folder]:
    • Copy installed packages in the “Library” folder to the “Library” folder in the new installation
  4. In new R version folder, copy the current Rprofile.site file as a backup (Rprofile_BACKUP.site) and overwrite the original file with the lab’s version of Rprofile.site from here: https://research-git.uiowa.edu/PetersenLab/R-InitialSetup/-/blob/master/R%20Setup%20Files/Rprofile.site
    • R will run the file named Rprofile.site at initial runtime.
  5. Set the executables for R and RStudio to always run with administrator permissions.
    • If on Windows, open File Explorer and find the main executable of R (C:\R\R-VERSION\bin\R.exe) and RStudio (C:\Program Files\RStudio\bin\RStudio.exe). Right-click it to open the contextual menu. Then, click or tap on “Properties”. In the Properties window, go to the Compatibility tab. At the bottom of the window, check the box next to the “Run this program as an administrator” option, and then click or tap on Apply or OK.
  6. Make sure you have the latest version of the tools necessary to compile packages from source (i.e., Rtools for Windows or R Compiler Tools for Rcpp on MacOS; see the instructions in the section on initial set up)
  7. Open the new R version and run update.packages(checkBuilt = TRUE, ask = FALSE), and install any necessary packages
  8. Close R
  9. Delete anything left of the old installation

7 Style Guide and Best Practices

7.1 Create Rstudio Project

For each data analysis project (i.e., each GitLab/GitHub repo), create an RStudio Project. This helps keep your project files organized.

7.2 Use R Notebooks for “Computational Notebooks”

Using R Notebooks for “Computational Notebooks” is helpful for reproducible code that can be shared with others. To create computational notebooks see the Markdown section on computational notebooks in the Data Analysis guides.

7.3 Separate sections in code

  • In R scripts, use sections.
    • To insert a section in RStudio, use CTRL-Shift-R or “Code” - “Insert Section”
  • In R Notebooks/Markdown, use Headers and code chunks.
    • Headers: 1, 2, or 3 pound signs
    • Code Chunks: Ctrl+Alt+I; or click “Insert” button then “R”

7.4 Naming variables

  • Use meaningful variable names; we want to know what a variable represents without having to consult an external codebook for every variable
  • Variable names should include the prefix for the measure followed by an underscore
    • e.g., cbcl_ for the Child Behavior Checklist variables
  • Use lower camel case for variable naming
    • e.g., prefix_thisIsTheVariableName
  • Do not include spaces in variable names

7.5 Comment code frequently and clearly!

It is important to comment code frequently and clearly. You want you (and others) to easily be able to understand your code if you come back to it several years later!

7.6 Don’t save your workspace image

For reproducibility purposes, it is important not to save your workspace image (archived at https://perma.cc/9SCZ-L4DE). It is best practices to begin R each session with a clean workspace. If there is a .Rdata file in the same folder as the Rstudio Project, Rstudio will automatically load the objects into the workspace at the beginning of the session. This is problematic because those objects can interact/interfere with the code and can lead to problems with replicability for others who are running the code without those objects in the workspace. When you exit RStudio, RStudio asks if you want to “Save workspace image to [filepath]/.Rdata?” Make sure to select “Don’t Save”! However, do make sure to save your R scripts before exiting Rstudio.

8 Data Management

9 Saving Plots

png(); dev.off()

10 Saving Output

R Markdown

11 Shortcuts

  • Run selected line(s) of code: Ctrl + Enter
  • Comment/uncomment code: Ctrl + Shift + C
  • Pipe: Ctrl + Shift + M
  • Insert Code Chunk: Ctrl + Alt + I
  • Assignment operator: Alt + - (alt-dash)
  • Select multiple lines: Ctrl + Alt, up or down; or Alt + drag mouse
  • Search: Ctrl + Shift + F
  • Show all keyboard shortcuts: Alt + Shift + K

12 Statistics Examples

13 Running Scripts Automatically with Windows

https://www.spsanderson.com/steveondata/posts/2023-06-29/index.html (archived at https://perma.cc/9EXK-W99Y)

R scripts can be run automatically. For example, it can be helpful to have an R markdown report run automatically before the day begins.

  1. Open the Notepad app and create a file with the following syntax.
    • Location of R executable file\R CMD BATCH "Path location of script that should be automatically run"
    • Example:
    • C:\R\4.1.3\bin\R CMD BATCH "R:\Lab\Studies\School Readiness Study\Data Processing\5. Reports\automatic_reports\Run_Reports_auto.R"
  2. Save the file as a .bat file in the desired location
  3. Once the .bat file has been created, search Task Scheduler in the search bar task scheduler
  4. In the Actions selection bar, select Create basic Task...
  5. Name the task and provide a description
  6. Next, set the trigger for the new task (i.e., how often the task should run)
  7. Set the action for the task by selecting Start a program
  8. Under, Program/script browse to the .bat file that was created in step 1 and select Next
  9. Click Finish and the script is now configured to run automatically
  10. If you wish to schedule a task to run during a time at which your computer is likely to be asleep, you’ll need to change the Conditions of the task to ensure that the computer “wakes up” to execute the script
    • In the Task Scheduler Library, select the task you just created
    • The task should appear on the lower half of the screen (double click to open in a new window). Select Conditions from the tabs across the top of the task window
    • Select Wake the computer to run this task
      • Note that elevated account permissions may be required to set this condition
  11. Note: When R is updated, the path to the bin folder within R needs to be updated to reflect an accurate absolute path to R.
    • Example: C:\R\4.1.3\bin\R CMD BATCH changed to C:\R\4.3.0\bin\R CMD BATCH

13.1 Troubleshooting

13.1.1 Pandoc error

This error may appear if you are attempting to render a markdown file

pandoc version 1.12.3 or higher is required and was not found.

The solution to this problem can be found at this link (archived at https://perma.cc/YX57-BPRS)

14 Using R Script to Commit and Push Changes

When using R to perform such actions as rendering sites and processing data, it can be useful to include code that commits and pushes relevant changes into the appropriate git repository. The steps below assume that you have Git and the GitHub desktop app installed. The instructions to download and configure git software can be found here

  1. Install and/or load git2r package

  2. Specify the path to your repository

    repoPath <- "C:/Users/username/Documents/GitHub/exampleRepo"

  3. Open and define the repository

    repo <- repository(repoPath)

  4. Stage changes to be committed

    • Stage all files in repo: r add(repo, "*")

    • Stage files with a specific file extension: r add(repo, "*.txt")

    • Stage files with one of any specified file extension: r add(repo, c("*.txt", "*.csv", "*.html"))

    • Stage files within a specific folder: r add(repo, "/folderName/*)

    • Stage one specific file: r add(repo, "fileName.txt)

    • Stage multiple specific files: r add(repo, c("thisFile.txt", "thatFile.txt", "anotherFile.txt"))

  5. Commit the changes

    • Commit with a customized commit message: r commit(repo, "My commit message")

    • Commit with a generated message using system or environment variables:

      # example: include system date in commit message
date <- format(Sys.Date(), format = %Y-%m-%d)
message <- paste(date, "daily site update", sep = " ")

commit(repo, message)

  6. Push changes

    push(repo)

    Note: The code included above will prompt Git to authenticate your credentials by manually providing your username and password in a popup window. The push() function accepts a credentials = cred_user_pass("username", "password") argument that will “bypass” the need for user input by including the relevant credentials in the push() function call. One could provide their username and password directly in the script running this function, but other more-secure options include:

    • Using a Personal Access Token
    • Using an SSH key
    • Encrypting credential information and storing the encrypted credential file somewhere accessible for use

      • See here for an exmaple of encryption and key creation

      • Using the encrypted credential and encryption key:

        # Define key location
encryptionKeyLocation <- "path/to/key/location/myKey.RData"

# Load key into environment
load(encryptionKeyLocation)

# Read encrypted credential file using key
creds <- read.aes("path/to/encrypted/credentials/file.txt", key = key)

# Extract password from credential data
myPassword <- creds$password

# Push changes to git using credentials
push(repo, credentials = cred_user_pass("insertUsername", myPassword))

15 Using try() Statements

try() statements can be very useful in cases where you would like code to continue running even if a certain line errors out. If the code inside of the statement results in an error, the try() statement will allow R to simply jump to the next line of code, rather than halting the entire process.

It is best practice to ensure that the smallest possible “unit” of code is wrapped in the try() statement rather than a large section. This is because the try() statement will treat everything within it as a “single” operation. Thus, an error ocurring early in the sequence within a try() statement will cause the remainder of the sequence to be skipped, and R will skip to the next line of code outside of the present try() statement.

For example:

The following code does NOT have try() statements around the smallest possible unit. If file_b.R were to error out, file_c.R would not run. In other words, file_c.R would be skipped because it occurs after file_b.R in the same try() statement.

try({
source(path/to/file/file_a.R)
source(path/to/file/file_b.R)
source(path/to/file_c.R)    
})

On the other hand, the revised code below IS using try() statements around the smallest possible unit. If file_b.R were to error out, file_c.R would then begin to run. This is because each individual file being “sourced” is wrapped in its own try() statement.

try({source(path/to/file/file_a.R)})
try({source(path/to/file/file_b.R)})
try({source(path/to/file_c.R)})

16 Reading Password Protected Excel Databases

A helpful post can be found here:

https://stackoverflow.com/questions/35852722/how-do-you-read-a-password-protected-excel-file-into-r (archived at https://perma.cc/U32Z-22VE)

Code
install.packages("excel.link")

library("excel.link")

passwordProtectedBook <- xl.read.file(file.path("full path to workbook"), #Full path to workbook
password = "pass", #password
write.res.password="pass") #writing the reset password

17 Sending slacks with R

Occasionally, it can be helpful to send a Slack message using R. For example, if a script does not run, a Slack message can be sent to inform the appropriate team members. These instructions (archived at https://perma.cc/9CWJ-J5ZT) can largely be followed to set up R to send Slack messages. However, there are some differences:

  1. When setting up the configuration file, use the below template. The slack API token should be placed in the token category.
    • Note the token will need to be updated every 30 days. You can generate a new token by navigating to the Slack API and selecting Oauth & Permissions

    • slack picture

      slack picture
token: YOUR_FULL_API_TOKEN
channel: #general
username: slackr
incoming_webhook_url: https://hooks.slack.com/services/XXXXX/XXXXX/XXXXX

Once the configuration is complete, it is possible to send messages. For now, we have found it helpful to embed the slacks in the tryCatch function.

Code
tryCatch(
  CODE YOU WANT TO RUN,
  error = function(e)
{
  #message to send if the code doesn't run
  my_message <- paste( "example message")
  slackr_msg(my_message, channel = "#recruitment")
})

17.1 Slacking Specific Users

It is also possible to slack specific users with instructions found at this link (archived at https://perma.cc/59U5-V4GQ).

18 Replacing //n with a space

Many notes in projects that are exported from REDCap come with spaces denotes as //n. Use the below code to make these fields more readable in the future.

Code
gsub('\\n', ', ', df$notesField)

19 Working with R on a Network Drive

When working with R on a network drive, it may be helpful to configure the project to store .Rproj.user on the local C:/ drive rather than on the network drive, which results in slow execution times.

For more info:

20 Package Development

20.1 Working with renv for Package Management

renv is used for reproducibility, by helping with package management (tracking package versions, etc.):

https://rstudio.github.io/renv/articles/renv.html

Before updating a package locally, make sure that it is available in the Posit Package Manager (so it can be available to GitHub Actions):

https://packagemanager.posit.co

20.1.1 Updating the Package

  1. To update the package, run the following in R:
Code
# 1. Update packages in package environment
renv::upgrade()
renv::update()
renv::snapshot()

# 2. Add/edit code

# 3. Update documentation
roxygen2::roxygenise()

# 4. Update package version (or can do this manually)
usethis::use_version()

  1. Then, build the package: Ctrl-Shift-B

  2. Then, check the package: Ctrl-Shift-E

  3. Then, run R CMD check

  4. Then, install the package:

Code
renv::install("C:/R/Packages/petersenlab") #PC
renv::install("/Library/Frameworks/R.framework/Packages/petersenlab") #Mac

20.1.2 Installing Packages

To install new packages in the package environment, run the following in R:

Code
renv::install("NAME_OF_PACKAGE")

or:

Code
install.packages("NAME_OF_PACKAGE")

20.2 R CMD check

  1. Build the source package (.tar.gz file)
    • Click on the “Build” tab in the top-right pane of RStudio, and then click “Build Source Package”, or run the following code in the R console:
Code
devtools::build(pkg = "D:/Documents/GitHub/petersenlab")

  1. Open terminal in RStudio

    • After the package source (.tar.gz file) is built, open a terminal window directly in RStudio by clicking on the “Terminal” tab at the bottom of RStudio

  2. Run R CMD check --as-cran

    • In the terminal window, navigate to the directory where your package source (.tar.gz file) is located (commonly up one directory):
    cd ..

    Then, run R CMD check --as-cran followed by the name of your package tarball (making sure to update the package version in the filename). For example:

    R CMD check --as-cran petersenlab_1.0.0.tar.gz

20.2.1 Troubleshooting

20.2.1.1 If errors compiling the PDF manual

  1. In the terminal:

    cd ./petersenlab
R CMD Rd2pdf . --output=man/figures/manual.pdf --force --no-preview --no-clean

  2. Then, delete the created folder whose name begins with “.Rd2pdf…”

  3. In the R Console, build the source package in R (or using the instructions described above):

Code
devtools::build(pkg = "D:/Documents/GitHub/petersenlab")

  1. In the terminal (making sure to update the package version in the filename):

    cd ..
R CMD check --as-cran petersenlab_1.0.0.tar.gz

20.2.1.2 no visible binding for global variable; Undefined global functions or variables

For example:

no visible binding for global variable
    'moderatorVal_centered'
  Undefined global functions or variables:
    moderatorVal_centered predictorVal_centered

Solution: set each variable to NULL in the package function before it is mentioned. For example:

predictorVal_centered <- moderatorVal_centered <- NULL

20.3 R CMD check via GitHub Actions

Code
usethis::use_github_action("check-standard")

20.4 Useful keyboard shortcuts for package authoring:

Install Package: ‘Ctrl + Shift + B’

Check Package: ‘Ctrl + Shift + E’

Test Package: ‘Ctrl + Shift + T’

Code
renv::install("C:/R/Packages/petersenlab")
renv::snapshot()
renv::install()

20.5 pkgdown

Run once to configure your package to use pkgdown:

Code
usethis::use_pkgdown()

Then use pkgdown to build your website:

Code
pkgdown::build_site()

20.6 Steps to Add Functions

  1. Add .R file with the function
  2. Add the function to the _pkgdown.yml file
  3. Update version number
  4. renv::upgrade()
  5. renv::update()
  6. renv::snapshot()
  7. roxygen2::roxygenise()
  8. Install Package: ‘Ctrl + Shift + B’
  9. Check Package: ‘Ctrl + Shift + E’
  10. R CMD check
  11. Commit and push changes
  12. Update release version in GitHub

20.7 Add sub-packages

Code
devtools::build(pkg = "D:/Documents/GitHub/petersenlab/inst/extdata/testpackage1")
devtools::build(pkg = "D:/Documents/GitHub/petersenlab/inst/extdata/testpackage2")

install.packages("D:/Documents/GitHub/petersenlab/inst/extdata/testpackage1_0.1.0.tar.gz", repos = NULL, source = TRUE)
install.packages("D:/Documents/GitHub/petersenlab/inst/extdata/testpackage2_0.1.0.tar.gz", repos = NULL, source = TRUE)

remotes::install_local("D:/Documents/GitHub/petersenlab/inst/extdata/testpackage2_0.1.0.tar.gz")
remotes::install_local("D:/Documents/GitHub/petersenlab/inst/extdata/testpackage2_0.1.0.tar.gz")

20.8 Submit Package to CRAN

https://cran.r-project.org/submit.html

20.9 Resources

Official documentation for CRAN:

Unofficial documentation:

20.9.1 For Package Development Tasks

20.9.2 For Documentation

20.9.3 Creating Vignettes

20.9.4 For Licensing

21 Troubleshooting

To troubleshoot R issues, be resourceful. Try googling the error message or issue you are experiencing. See here for a list of places you can pose R-related questions for help. In addition, particular errors/warnings/issues are included below:

21.1 General Troubleshooting Tips

  1. Run code line-by-line to identify the source of the error
    • If you are using RStudio, a red line will often appear on the lefthand side of the screen to indicate the particular line(s) of code that result in an error
    • It may be useful to clear your working environment in R before trying to diagnose an error to be sure that you are not experiencing any interference from existing objects in the environment
    • Running code line-by-line is particularly useful because it allows you to inspect the data at each step of its processing
      • Data issues are commonly the culprit of code errors (see below)
  2. Check for typos
    • Are all brackets/parentheses/etc. closed?
    • Does the object/variable that you are referring to exist? (If the object does not exisit, you will likely get an error message indicating [object name] not found)
      • Has it been defined somewhere prior in the code?
      • Does it depend on something else to be created?
      • Is its name spelled correctly?
      • Highlighting the object or variable in question and using CTRL-F to search for it is a good way to check these things
    • Did you spell the function you want to use correctly?
    • Do you have commas separating items within a list/function/etc.?
  3. Does your working environment have what it needs?
    • Are all necessary packages/libraries installed? Do any require an update?
    • Are all expected objects (dataframes, lists, environment variables, etc) present? Are they correct?
  4. Investigate the structure of your data
    • Errors such as non-numeric argument to binary operator indicate that the function you are trying to use is expecting to recieve numeric data as an input but one or more of the inputs are not numeric
      • The function class(data$variable) (replace “data” and “variable” with whatever you are trying to invesitgate) is useful for determining how R is interpreting your data. Often, data that look like numbers can end up being stored as a character (text) variable. This can be due to import/export processes or due to an issue with data entry.
        • For example, when 00 is entered instead of 0 in a numeric field R is likely to interpret the variable as a character instead of a number when importing the data
    • Check to make sure that all expected rows/columns are present and that they look the way you expect them to
      • If your dataset has been created by joining/merging multiple dataframes, any duplicate columns not accounted for when joining may have a suffix appended to distinguish them (i.e., variable.x or variable.y)
      • To resolve this, either call the appended variable in subsequent manipulations (variable.x instead of variable) or deal with the duplicated columns before/during the joining process (e.g., include duplicate columns in the by argument of joining function or remove the redundant column from one of the datasets to be joined)
    • If you have been creating/computing variables in your dataset, ensure that they are being computed as expected
      • Check for NA (missing) or NaN (not a number) values. Such values may not be an issue or error in all cases, but if you are not expecting that as a result of your computations, this might suggest an issue with the code and/or data structure
      • Check whether the computed values are reasonable

21.2 A single error preventing a Wiki site from rendering

Code can be wrapped in try() statements so that if an error occurs, the script will simply “skip” to the next line of code. These try() statements are particularly useful when rendering a site; if they are not used, a single error will halt the entire process. try() statements allow the code to continue running in spite of a line or two erroring out.

If you have already incorporated try() statements and are still experiencing fatal errors in code, check to make sure that the smallest possible “unit” of code is wrapped in try() statements, rather than large sections of code. See here for more information.

21.3 Warning: PACKAGENAME package in FILEPATH library will not be updated

This warning might indicate that it cannot update the package because it is part of the base R installation. To fix this:

  • find and delete the package that is part of the base R installation in the library directory of the R installation (e.g., C:\R\R-4.3.1\library\PACKAGENAME\)
  • make sure the package is also not in any other package installation locations (e.g., C:\R\Packages\PACKAGENAME\); if it is, delete it from there as well
  • then, after deleting the package from these locations, restart R and run install.packages("PACKAGENAME") to reinstall the package
  • close R
  • if the package was part of the base R installation, move the installed package folder C:\R\Packages\PACKAGENAME\ to the library directory of the R installation (e.g., C:\R\R-4.3.1\library\PACKAGENAME\)

22 Session Info

Code
R version 4.5.2 (2025-10-31)
Platform: x86_64-pc-linux-gnu
Running under: Ubuntu 24.04.3 LTS

Matrix products: default
BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0

locale:
 [1] LC_CTYPE=C.UTF-8       LC_NUMERIC=C           LC_TIME=C.UTF-8       
 [4] LC_COLLATE=C.UTF-8     LC_MONETARY=C.UTF-8    LC_MESSAGES=C.UTF-8   
 [7] LC_PAPER=C.UTF-8       LC_NAME=C              LC_ADDRESS=C          
[10] LC_TELEPHONE=C         LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C   

time zone: UTC
tzcode source: system (glibc)

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

loaded via a namespace (and not attached):
 [1] htmlwidgets_1.6.4 compiler_4.5.2    fastmap_1.2.0     cli_3.6.5        
 [5] tools_4.5.2       htmltools_0.5.9   otel_0.2.0        yaml_2.3.12      
 [9] rmarkdown_2.30    knitr_1.51        jsonlite_2.0.0    xfun_0.55        
[13] digest_0.6.39     rlang_1.1.6       evaluate_1.0.5

Developmental Psychopathology Lab