Steven J. Pierce
This package (Pierce, 2026) is a research compendium for a study examining the prevalence of bandemia in canine patients undergoing chemotherapy treatment (Eliason et al., 2026). The research team is led by Dr. Alison Masyr (PI) at Michigan State University.
For an overview of how I approach creating a research compendium, see materials for my most recent CSTAT webinar on reproducible research at https://sjpierce.github.io/presentations.html.
We eventually expect two different types of users of this package: collaborators and readers. Collaborators include members of the research team working on the project prior to publication who may contribute to the code. Readers include members of the public who simply want to reproduce the computations and analyses after reading the paper. These instructions include some steps that are more relevant to collaborators than to readers.
To collaborate on the code for this package, you must have a GitHub account. You can request such access by emailing the package maintainer your GitHub username and ask to be added as a collaborator on this repository. You will need to use Git (Torvalds et al., 2025) for version control on files associated with this package and to synchronize changes between your local copy of the repository and GitHub, with RStudio (RStudio Team, 2026) as the primary editor. There is a lot of useful information about using these tools at the Happy Git and GitHub for the userR website (Bryan et al., n.d.). Other useful resources on using Git and GitHub include Bryan (2018) and Perez-Riverol et al. (2016). Meanwhile, Wickham & Bryan (2021) provides extensive guidance on creating R packages. Chacon & Straub (2014) is a full book on using Git for version control.
Changes made to files in a local copy of the repository should be committed and pushed to the main branch of the remote CHOPStudy repository on GitHub. See Bryan (2018) for a short introduction to why this is good practice.
Unless otherwise directed below, we assume you are using the most recent stable release versions of the software packages discussed below and also frequently updating your installed R packages.
This package is only available from a public repository available on the GitHub server at https://github.com/sjpierce/CHOPStudy. Public repositories are visible to everyone but can only be edited by GitHub users who are logged in and have been registered by the repository owner as a collaborator on the project.
This package’s repository will remain private until the associated manuscript has been accepted for publication. Once that happens, the repository may be made public to enable readers to reproduce the analyses.
The package can be installed with the information shown below. The overall goal here is to set you up for using a suite of software tools and practices that works well for reproducible research. That will facilitate using this package.
You should create a GitHub user account before proceeding further. After you have the GitHub account, send the CHOPStudy package maintainer your GitHub username and ask to be added as a collaborator on the repository. This is necessary because the main branch of the package repository is stored on GitHub. You will need to be able to use Git and GitHub to synchronize changes between your local copy of the repository and GitHub.
You can get the most recent version of R (R Development Core Team, 2025) from the Comprehensive R Archive Network (CRAN).
Install any tools required for compiling packages (they will be specific to your operating system). These will be necessary for the devtools package to work.
- On Windows, see https://cran.r-project.org/bin/windows/Rtools/.
- On Mac OS X, see https://cran.r-project.org/bin/macosx/tools and https://mac.R-project.org/tools/.
Install RStudio Desktop version 2026.01.0+392 (or later). We recommend using RStudio to interact with the files for this package. RStudio is both a good interface to R and has built-in support for using some of the other software discussed below.
We rely on Quarto (Allaire et al., 2026) scripts to enhance reproducibility because they provide excellent support for generating dynamic reports (Mair, 2016). Install Quarto version 1.8.27 or later. Although RStudio bundles a version of Quarto, we want the most recent stable release instead. Quarto also includes a copy of Pandoc.
- To download Quarto, visit https://quarto.org/docs/get-started/
This step is required for collaborators, but optional for readers. Readers can just skip to the “Install devtools package section”.
Install Git. We use this for version control on the package code. Get the most recent version available for your operating system. See instructions at https://happygitwithr.com/install-git.html.
- On Windows, download from https://git-scm.com/download/win
- On MacOS, download from https://git-scm.com/download/mac
This step is required for collaborators, but optional for readers. Readers can just skip to the “Install devtools package” section.
Configure Git using the instructions at https://happygitwithr.com/hello-git.html. RStudio can be your main interface to the Git client most of the time, but occasionally using a Git Bash command window instead is more useful. You can open that by clicking Start > All Programs > Git > Git Bash on your own computer.
You will need to configure RStudio to use Git and GitHub. Use the instructions at https://happygitwithr.com/connect-intro.html. The reason for that is that because RStudio is both a good interface to R and has built-in support for Git.
Read Section 9 of the Happy Git with R website (https://happygitwithr.com/https-pat.html) to learn more about what a PAT is, how to get one, and why it is useful. The following subsections may be particularly useful.
- https://happygitwithr.com/https-pat.html#valid-pat-gets-stored-but-later-told-the-pat-is-invalid
- https://happygitwithr.com/https-pat.html#pat-doesnt-persist-on-macos-or-windows
- https://happygitwithr.com/https-pat.html#pat-doesnt-persist-on-linux
You may also want to read GitHub documentation about managing PATs (https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
Visit https://github.com/settings/tokens to create a PAT that has the
gist, repo, user, and workflow scopes. Once you have it, you’ll
need to store it so your computer can find your PAT automatically.
We also want to store your PAT in the Git Credential Manager because that allows RStudio and Git to easily connect to GitHub for pushing and pulling commits.
We can use the credentials package for R to facilitate this task.
# If you don't already have it installed.
install.packages("credentials")Then, run the following function call.
credentials::git_credential_ask("https://github.com")If this prompts you for username and password, use the PAT as the password. If that just displays a result but the password does not match your PAT, run the code below then enter your GitHub username and use your PAT as the password.
credentials::git_credential_update("https://github.com")Install the devtools package for R. The most recent CRAN release will likely be more stable but sometimes you may instead need the development version at GitHub. This package provides developer tools/functions that simplify creating, quality-checking, and installing custom R packages. You can use the following command at the R console.
install.packages("devtools")Install the piercer package for R. Instructions for doing that are at the link. Please read and follow them before trying to install or use this package.
This sectional is optional because this package does not use scripts that generate PDF output (some of my other projects use PDF output).
TinyTex is a specific distribution of
LaTeX, which is document preparation software that allows high-quality
typesetting. It takes plain text LaTeX files (*.tex files) that
describe the structure of a document and compiles them into
fully-formatted PDF files with nice fonts and layout. We can actually
use the R package called
tinytex to install TinyTeX
via the following commands inside R.
# If you don't already have it installed.
install.packages("tinytex")tinytex::install_tinytex()You can use alternative LaTeX distributions and tools (e.g., MiKTeX) instead, but TinyTeX is very convenient because of how well it integrates with the other tools we’re using.
Major versions of TinyTex are released at least annually. If it has been a long time since you last installed TinyTeX, you may want to update it using the code below. This should refresh both the base TinyTex and the LaTeX packages you have previously installed by using it.
tinytex::reinstall_tinytex()It is a good idea to update all your R packages. You may be prompted with a dialog box asking “Do you want to install from sources the packages which need compilation?” It usually works fine if I choose “no”. Occasionally, it appears necessary to choose “yes”, but I am more likely to run into problems when doing that.
update.packages(ask='graphics', checkBuilt=TRUE)If you previously were using an older version of R (any version in the
4.4.x series or earlier), you should plan to reinstall all your R
packages from scratch under R 4.5.0 or later. The best way to do that is
to use a script such as scripts/Reinstall_Packages.R under the older
version to save a data file containing the names of installed packages,
then remove the older version of R and replace it with the newest
version of R, and use the remainder of that script to read in that list
of packages and install them. That will take several minutes if you have
a lot of packages.
Once the repository is made public, readers should be able to download a
ZIP file containing the latest released version of the repository
contents from https://github.com/sjpierce/CHOPStudy/releases/latest.
Just unzip that to create a folder on your local computer such as
C:\Users\username\Documents\CHOPStudy; that will be your local copy of
the repository.
If you want to work with the package on your laptop, use RStudio to
clone the CHOPStudy package from GitHub (the repository source is
https://github.com/sjpierce/CHOPStudy.git) to a local folder on your
computer such as C:\Users\username\Documents\CHOPStudy. This is the
folder where you would edit scripts and files and that you would
synchronize with the GitHub main branch via Git’s pull and push
operations.
Ideally, only one person should be using a given local repository at a time. The beauty of Git is that it allows us all synchronize with the main repository on GitHub regardless of where our local copies are stored.
You have to install the package to your personal R package library
before some of the scripts will work because they may depend on
functions defined in the package. This personal R package library would
usually be in a location such as
C:\Users\username\AppData\Local\R\win-library\4.5\CHOPStudy on your
laptop, desktop, or on the server. Note that this is distinct from the
local repository folder!
Scripts that do not have a library(CHOPStudy) call in them may work
without the package being installed, but those containing that call
depend on custom functions found only in the CHOPStudy package. When
you use that call, R loads the copy of the package found in your
personal R package library, not from the local Git repository.
Now you should be ready to actually install the package. There are two main ways to do that: from GitHub and from the local repository. Both are explained below.
You should be ready to actually install the package from the main branch on GitHub. This is the recommended default method for installing CHOPStudy.
devtools::install_github(repo = "sjpierce/CHOPStudy", dependencies = TRUE)If you can use Git pull and push successfully but the installation command above does not work, the problem may be that you need to store your Git credentials in the Git credential manager or to update them there.
You may sometimes want to build and install the package from the local repository directly to your personal R package library instead of pulling the copy from GitHub. This can be useful when testing new code before you commit it to the main branch or if you do not use Git and GitHub.
Double-click the CHOPStudy.Rproj file from Windows Explorer. That
should open the project in RStudio. Then run the following code in a
fresh R session.
library(devtools)
document()
check()
install()The structure for the package is shown in the outline below, where
folder names and file names are highlighted like this and comments are
in normal text. The folder structure is largely determined by the
conventions governing the structure of R packages. It deviates a bit
from the example research compendium folder structures discussed by
Marwick et al. (2018). The repository is also set up as an RStudio
project.
CHOPStudy/: This is the root folder for the repository..git/: This hidden folder is used by Git. Leave it alone!.Rproj.user/: This hidden folder is used by Rstudio. Leave it alone!data/: This folder is where the data file produced by our scripts will be stored. This is a standard folder for R package structures.Imported_CHOP_Data.RData: This is the data file produced by running thescripts/Import_Data.qmdscript.Placeholder.textThis text file is just present to ensure that thedatasubfolder will be created when you clone the repository or extract files from ZIP file copy of the repository obtained from GitHub.
man/: This folder contains R documentation help files (*.Rd) for the package and its custom functions. It is required by R package building conventions. You should not edit these files manually and you really only access them through R’s normal help system.R/: This folder contains the source code for the package’s custom functions in a set of*.Rscript files. It is required by R package building conventions.CHOPStudy-package.R: This script file is used to automate creating package level help files. Do not edit it manually.
scripts/The folder is configured as a Quarto project. It holds meta-data files,.qmdscripts, and files used by the scripts..quarto/: This hidden folder may be created by Quarto to hold temporary files. Do not edit or delete any of these files unless you know what you are doing! This folder is not tracked by Git.extdata/: This subfolder contains the raw data file mentioned in the Obtaining Data Files section below.Vinc_Cases_2025-03-26.xlsx: This is the current raw data set.
output/: This subfolder holds rendered output files created by the Quarto scripts inscripts/.Descriptive_Analysis_2026-01-29.htmlis final output we used in the manuscript.Figure_1.pngis used in the manuscript.Figure_2.pngis used in the manuscript.Figure_3.pngis used in the manuscript.GLMM_Analysis_2026-01-29.htmlis final output we used in the manuscript.Import_Data_2026-01-29.htmlis final output we used in the manuscript.Render_Scripts_2026-01-29.htmlis final output we used in the manuscript.
.gitignore: This was auto-created by Quarto. Don’t edit or delete it._brand.yml: This file specifies color, font, and logo settings for using an MSU/CSTAT branding scheme for HTML output._quarto.yml: This is a Quarto metadata file containing project-level YAML code that will be inherited by Quarto scripts in this folder or its subfolders.apa.csl: This is a citation style language file for the Publication Manual of the American Psychological Association, 7th ed. It is used by Quarto to format reference sections.Delete_nul_file.bat: This is a Windows batch file that automates removing a nuisance file sometimes left over when rendering a Quarto or R Markdown script doesn’t work right.Descriptive_Analysis.qmd: This file runs some descriptive analyses we used in our manuscript (plus others that we omitted due to space constraints).Development_Tools.R: This contains some examples of R commands I use interactively when working on the package.GLMM_Analysis.qmd: This file runs some the actual GLMM model used
in our manuscript.Import_Data.qmd: This script imports the raw data from Excel, prepares it for use, and saves an R data file that will be used by other scripts. Re-running this script will overwrite thedata/Imported_CHOP_Data.RDatafile.references.bib: This is a BibTeX file containing the citation data for references mentioned in various scripts. Quarto uses it to get the data needed to insert reference lists.Reinstall_Packages.R: This script contains R code that stores a data file containing a list of all your installed packages, plus code for reading that file and re-installing all of those packages from scratch. It automates an otherwise tedious process. You would use this before and after upgrading to a new version of R (e.g., when going from version 4.3.x to 4.4.x).Render_Scripts.qmd: This file will eventually automate rendering other scripts in the correct order.Setup_as_Package.qmd: This is a script I used to remind myself of how to rapidly do various parts of turning a new repository into an R package. It’s only really used once.
.gitignore: This file tells Git what files to ignore and omit from synchronizing with the main repository on GitHub..Rbuildignore: This file tells R what files to ignore when building the package from the source code.CHOPStudy.Rproj: This is an RStudio project file. It contains some settings for working with the project in that software.DESCRIPTION: This file is a brief, structured description of the package that is required by R package building conventions. It holds essential meta-data.LICENSE: This file contains the terms of the license that applies to all source code in this repository.NAMESPACE: This file is created automatically by R when building the package. You should not edit it manually. It is required by R package building conventions.NEWS.md: This file contains an list of comments about the changes made with each version of this package. It is required by R package building conventionsREADME.md: This file is obtained by rendering theREADME.qmdfile and is used by GitHub to display information about the package. Do not edit it manually: just renderREADME.qmdto update it. In R Studio, you can read the formatted version by opening the file and clicking the Preview button.README.qmd: This file gives an introduction to the package. Rendering it produces theREADME.mdfile and opens the preview automatically.
Scripts in this R package may depend on having a number of other R
packages installed. Those packages are listed in the DESCRIPTION
file’s Depends, Suggests, and Imports fields. They are mostly available
from CRAN and should be installed automatically when you install the
CHOPStudy package itself if you use dependencies = TRUE option.
Many software packages are updated periodically, so it is a good idea to update to the newest stable version of them occasionally. Most of us accumulate a large number of installed R packages. There is a good chance that at least one of them will have been updated every week, so updating R packages regularly is a good idea. User-contributed packages collectively change more often than base R.
Staying reasonably current on software versions for the whole suite of tools we are using here will keep things working smoothly most of the time. It also helps if we are using the same versions wherever possible because version differences can introduce discrepancies in the results we each obtain.
The data required to use this package are available in this GitHub repository. They do not contain any data about humans (only about dogs), so there should be no problem with freely distributing them. Dr. Masyr (the principal investigator) authorized release of the data along with the package. This reduces the number of servers where the data files may be stored and thereby increases data security.
To obtain the data files, you can contact the package author Steven J.
Pierce at pierces1@msu.edu. If you are a CSTAT employee assigned to the
project team, you can find the data files on CSTAT’s secure network
drive at P:\Consulting\Cases_1200-1399\C1358\Data. When you get the
files, you will need to put them all in the scripts/extdata subfolder
of your local repository.
Members of our research team should not distribute the data files to other parties outside the research team without Dr. Masyr’s approval. They should not put them on servers not controlled or approved for use by MSU without her approval either.
The PI will decide later whether to add the data to the repository or archive them separately for reproducibility purposes.
Once you have completed this step and all the others listed above, you should be ready to use this package to reproduce our results.
After it has been installed to your package library as described above, you can load CHOPStudy via the following R console command. That provides access to the custom R functions we have included in the package.
Loading the package will also mean that we can use functions like
devtools::session_info() to show the package version number in our
output. That facilitates reproducibility by making it easier to see the
software environment required to obtain a particular result.
You can see information about the package by using the following command in the R console. The resulting help page has an Index link at the bottom that will show you a list of all the custom functions in the package.
One of the main uses of the package is to run scripts that import,
manage, and analyze data for the manuscript it supports. For example, if
you want to just reproduce the results, you can double-click the
CHOPStudy.Rproj file from Windows Explorer to open the project in
RStudio. Then, use RStudio to open the file scripts/Render_Scripts.qmd
and click the “Render” button in RStudio.
If you have everything set up correctly, that will start generating
files in the scripts/output folder, including
scripts/output/Render_Scripts.html, which is the log of running that
rendering script that contains information on how long it took to render
each report called by that file.
If you want to get a date-stamped output for
scripts/Render_Scripts.qmd, use commands similar to the ones shown
below in the Terminal to render that script. The first line changes to
the scripts/ subfolder and the second one does a custom render of that
script, setting matching custom values for the output file name and the
LogFile parameter.
cd scripts
quarto render Render_Scripts.qmd --output Render_Scripts_2026-01-29.html -P LogFile:Render_Scripts_2026-01-29.html
Make sure you change the date part of file names if you want to avoid
overwriting scripts/output/Render_Scripts_2026-01-29.html, which is
the final output I produced to accompany the manuscript.
Allaire, J. J., Dervieux, C., Scheidegger, C., Teague, C., & Xie, Y. (2026). Quarto (Version 1.8.27) [Computer Program]. Posit Software, PBC. https://quarto.org
Bryan, J. (2018). Excuse me, do you have a moment to talk about version control? The American Statistician, 72(1), 20–27. https://doi.org/10.1080/00031305.2017.1399928
Bryan, J., TAs, T. S. 545., & Hester, J. (n.d.). Happy Git and GitHub for the useR [Web Page]. https://happygitwithr.com
Chacon, S., & Straub, B. (2014). Pro Git. Apress Media. https://git-scm.com/book/en/v2
Eliason, C. N., Pierce, S. J., & Masyr, A. (2026). Band neutrophils are observed in dogs undergoing multiagent chemotherapy including vincristine. Animals, 16(3), Article 434. https://doi.org/10.3390/ani16030434
Mair, P. (2016). Thou shalt be reproducible! A technology perspective. Frontiers in Psychology, 7(1079), 1–17. https://doi.org/10.3389/fpsyg.2016.01079
Marwick, B., Boettiger, C., & Mullen, L. (2018). Packaging data analytical work reproducibly using R (and friends). The American Statistician, 72(1), 80–88. https://doi.org/10.1080/00031305.2017.1375986
Perez-Riverol, Y., Gatto, L., Wang, R., Sachsenberg, T., Uszkoreit, J., Leprevost, F. da V., Fufezan, C., Ternent, T., Eglen, S. J., Katz, D. S., Pollard, T. J., Konovalov, A., Flight, R. M., Blin, K., & Vizcaíno, J. A. (2016). Ten simple rules for taking advantage of Git and GitHub. PLOS Computational Biology, 12(7), e1004947. https://doi.org/10.1371/journal.pcbi.1004947
Pierce, S. J. (2026). CHOPStudy: Research compendium for the CHOP study (Version 1.0.4) [Reproducible Research Materials, Computer Program, R package, Public Repository]. GitHub. https://github.com/sjpierce/CHOPStudy. Zenodo. https://doi.org/10.5281/zenodo.18381003
R Development Core Team. (2025). R: A language and environment for statistical computing (Version 4.5.2) [Computer Program]. R Foundation for Statistical Computing. http://www.R-project.org.
RStudio Team. (2026). RStudio Desktop: Integrated development environment for R (Version 2026.01.0+392) [Computer Program]. Posit Software, PBC. https://posit.co
Torvalds, L., Hamano, J. C., & other contributors to the Git Project. (2025). Git for Windows (Version 2.52.0(1)) [Computer Program]. Software Freedom Conservancy. https://git-scm.com
Wickham, H., & Bryan, J. (2021). R packages: Organize, test, document, and share your code. O’Reilly Media. https://r-pkgs.org
Please cite the package itself (Pierce, 2026), which includes the necessary data file.
The opinions or points of view expressed in this document (or any other document included in this R package and repository) are solely those of the authors and do not reflect the official positions of any organization.