README.qmd

---
title: README 
author: 
  - name: Steven J. Pierce
    orcid: 0000-0002-0679-3019
    email: pierces1@msu.edu
    affiliations: 
      - name: Michigan State University, Center for Statistical Training and Consulting
bibliography: scripts/references.bib
csl: scripts/apa.csl
format: gfm
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r}
#| label: knitr-options
#| include: FALSE

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# CHOPStudy Package Documentation 

<!-- badges: start -->
[![Latest version DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18381003.svg)](https://doi.org/10.5281/zenodo.18381003)
[![](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![Project Status: Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.](https://www.repostatus.org/badges/latest/inactive.svg)](https://www.repostatus.org/#inactive)
[![CRAN status](https://www.r-pkg.org/badges/version/CHOPStudy)](https://CRAN.R-project.org/package=CHOPStudy)
<!-- badges: end -->

This package [@Pierce-RN8714] is a research compendium for a study examining the
prevalence of bandemia in canine patients undergoing chemotherapy treatment 
[@Eliason-RN8603]. 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. 

## Assumptions
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](https:/git-scm.com) [@Torvalds-RN3929] for version control on files
associated with this package and to synchronize changes between your local copy
of the repository and [GitHub](https://github.com), with
[RStudio](https://posit.co/products/open-source/rstudio/) [@RStudio-Team-RN8351]
as the primary editor. There is a lot of useful information about using these
tools at the [Happy Git and GitHub for the userR](https://happygitwithr.com)
website [@Bryan-RN3908]. Other useful resources on using Git and GitHub
include @Bryan-RN3900 and @Perez-Riverol-RN3924. Meanwhile, @Wickham-RN3898 
provides extensive guidance on creating R packages. @Chacon-RN3480 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-RN3900 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.

## Installation
This package is only available from a *public* repository available on the 
[GitHub server](https://github.com) 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.

### Create a GitHub Account (Optional for Readers)
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. 

### Install R 4.5.2 or later. 
You can get the most recent version of R [@R-Devel-Core-RN8182] from the 
[Comprehensive R Archive Network (CRAN)](https://cran.r-project.org/). 

### Install tools for compiling packages
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 
Install [RStudio Desktop](https://posit.co/products/open-source/rstudio/)
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.

### Install Quarto
We rely on [Quarto](https://quarto.org) [@Allaire-RN8427] scripts to enhance 
reproducibility because they provide excellent support for generating dynamic 
reports [@Mair-RN3387]. 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](https://pandoc.org/).

* To download Quarto, visit https://quarto.org/docs/get-started/

### Install Git (Optional for Readers)
This step is required for collaborators, but optional for readers. Readers can 
just skip to the "Install *devtools* package section". 

Install [Git](https://git-scm.com/). 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

### Configure Git (Optional for Readers)
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.

### Connect Git, GitHub, and RStudio (Optional for Readers)
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.

#### Obtain a GitHub personal access token (PAT)
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.

#### Store your GitHub PAT in the Git Credential Manager 
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*](https://cran.r-project.org/package=credentials) 
package for R to facilitate this task. 

```{r}
#| label: install-credentials
#| eval: false

# If you don't already have it installed.
install.packages("credentials")
```

Then, run the following function call. 

```{r}
#| label: ask-git-credentials
#| eval: false

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.
      
```{r}
#| label: update-git-credentials
#| eval: false

credentials::git_credential_update("https://github.com")
``` 

### Install *devtools* Package 
Install the [*devtools*](https://devtools.r-lib.org/) package for R. The most
recent [CRAN release](https://cran.r-project.org/package=devtools) will likely
be more stable but sometimes you may instead need the [development version at
GitHub](https://github.com/r-lib/devtools). 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.
  
```{r}
#| label: install-devtools-from-CRAN
#| eval: false

install.packages("devtools")
```

### Install *piercer* Package 
Install the [*piercer*](https://github.com/sjpierce/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.

### Install TinyTex (Optional)
This sectional is optional because this package does not use scripts that 
generate PDF output (some of my other projects use PDF output). 

[TinyTex](https://yihui.org/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](https://cran.r-project.org/package=tinytex) to install TinyTeX via the
following commands inside R.

```{r}
#| label: install-tinytex
#| eval: false

# If you don't already have it installed.
install.packages("tinytex")
```

```{r}
#| label: install-TinyTex
#| eval: false

tinytex::install_tinytex()
```

You can use alternative LaTeX distributions and tools (e.g., 
[MiKTeX](https://miktex.org/)) 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.  

```{r}
#| label: reinstall-TinyTex
#| eval: false

tinytex::reinstall_tinytex()
```

### Update Your R packages
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.

```{r}
#| label: update-packages
#| eval: false

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.

### Clone the *CHOPStudy* Repository from GitHub to your Local Computer

#### Instructions for readers not using Git & GitHub
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. 

#### Instructions for collaborators and readers using Git & GitHub
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. 

### Install *CHOPStudy* to your personal package library
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. 

#### Install from GitHub (recommended for collaborators and readers using Git & GitHub)
You should be ready to actually install the package from the main branch on 
GitHub. This is the recommended default method for installing *CHOPStudy*. 

```{r}
#| label: install-CHOPStudy-from-GitHub
#| eval: false

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. 

#### Install from the local respository (recommended for readers not using Git & GitHub)
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.

```{r}
#| label: install-CHOPStudy-from-local-repo
#| eval: false

library(devtools)
document()
check()
install()
```

## Repository Structure and Contents
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-RN3899. The repository is also set up as 
an 
[RStudio project](https://support.rstudio.com/hc/en-us/articles/200526207-Using-RStudio-Projects). 

* `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 
          the `scripts/Import_Data.qmd` script. 
        * `Placeholder.text` This text file is just present to ensure that the
              `data` subfolder 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 `*.R` script 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, `.qmd` scripts, 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 in `scripts/`. 
            * `Descriptive_Analysis_2026-01-29.html` is final output we used in 
              the manuscript. 
            * `Figure_1.png` is used in the manuscript. 
            * `Figure_2.png` is used in the manuscript. 
            * `Figure_3.png` is used in the manuscript. 
            * `GLMM_Analysis_2026-01-29.html` is final output we used in the 
              manuscript.
            * `Import_Data_2026-01-29.html` is final output we used in the 
              manuscript.
            * `Render_Scripts_2026-01-29.html` is 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 the 
          `data/Imported_CHOP_Data.RData` file. 
        * `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
      conventions
    * `README.md`: This file is obtained by rendering the `README.qmd` file and 
      is used by GitHub to display information about the package. Do not edit it 
      manually: just render `README.qmd` to 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 the `README.md` file and opens the preview automatically. 

## Software Dependencies
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. 

## Software Maintenance 
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. 

## Obtaining Data Files
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. 

## Loading the *CHOPStudy* Package in R
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.  

```{r}
#| label: load-CHOPStudy
#| echo: false
#| eval: false

library(CHOPStudy)
```

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.

## Get Help on *CHOPStudy* Custom Functions
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. 

```{r}
#| label: help-CHOPStudy
#| echo: false
#| eval: false

?CHOPStudy
```

## Use Case: Reproducing Our Results
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. 

## References
::: {#refs}
:::

# Citing This Package
Please cite the package itself [@Pierce-RN8714], which includes the necessary 
data file. 

## Disclaimer
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.