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%"
)
```

# SANETPA Package Documentation

<!-- badges: start -->
[![Latest version DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18643254.svg)](https://doi.org/10.5281/zenodo.18643254)
[![](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/SANETPA)](https://CRAN.R-project.org/package=SANETPA)
<!-- badges: end -->

This package [@Pierce-RN8756] is a research compendium [@Marwick-RN3899] for a 
study examining attrition from a sexual assault nurse examiner (SANE) training 
program [@Campbell-RN8818]. The research team is led by Dr. Katherine Dontje 
(PI) and Dr. Rebecca Campbell (Co-I) at Michigan State University and was
supported by a grant [@Dontje-RN8757]. The training program had two major
components: didactic training (DT) followed by a clinical skills workshop (CSW).

The study addresses the following research questions:

* **RQ1.** What are the eligibility and enrollment rates for this program, and 
  do eligible vs. enrolled participants differ with respect to their background, 
  motivations, potential barriers, and emotional readiness for this kind of 
  work?
* **RQ2.** What are the attrition rates from enrollment to completion of the 
  CSW, and when (i.e., at which module[s]) did participants commonly attrit?  
* **RQ3.** Do participants’ background characteristics, motivations for seeking 
  training, potential barriers, and emotional readiness for this work predict 
  attrition rates? 
* **RQ4.** For the participants who completed DT and those who completed the 
  CSW, to what extent did they find each training component to be 
  useful/helpful?

## 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 *SANETPA* repository on GitHub. 
See @Bryan-RN3900 for a short introduction to why this is good practice. 

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/SANETPA. 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 was private until the associated manuscript was 
accepted for publication. After that, we made it 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 *SANETPA* 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 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
[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 before 4.5.0), 
you should plan to reinstall all your R packages from scratch. 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 *SANETPA* 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/SANETPA/releases/latest. Just unzip that 
to create a folder on your local computer such as 
`C:\Users\username\Documents\SANETPA`; 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 
*SANETPA* package from GitHub (the repository source is 
https://github.com/sjpierce/SANETPA.git) to a local folder on your computer 
such as `C:\Users\username\Documents\SANETPA`. 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 *SANETPA* 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\SANETPA` 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(SANETPA)` call in them may work without
the package being installed, but those containing that call depend on custom
functions found only in the *SANETPA* 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 *SANETPA*. 

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

devtools::install_github(repo = "sjpierce/SANETPA", 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 `SANETPA.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-SANETPA-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). 

* `SANETPA/`: 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 `.RData` file produced by our scripts 
      will be stored. This is a standard folder for R package structures. 
        * `Imported_SANETP_Data.RData`: This file is created by rendering the 
          `scripts/Import_Data.qmd` script. Re-running the script will overwrite
          it. 
        * `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.
    * `graphics/`: This folder stores `.eps`, `.pdf`, and `.png` graphics files 
      for CSTAT and MSU logos and/or wordmarks used in my scripts for branding 
      purposes.
    * `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.
        * `SANETPA-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 raw data used by my scripts. 
            * `All_group_1_2025-11-19.sav`: This SPSS data file holds all the 
              de-identified raw data. 
        * `output/`: This subfolder holds rendered output files. 
            * `Campbell_Figure_1_yyyy-mm-dd.png`: This image file is a temporary
              file that gets converted to a `.tif` file. It is created by the 
              `scripts/Export_Diagram.qmd` script.
            * `Campbell_Figure_1_yyyy-mm-dd.tif`: This image file is suitable
              for submission to a journal. It is created by the 
              `scripts/Export_Diagram.qmd` script.
            * `Campbell_Figure_2_yyyy-mm-dd.tif`: This image file is suitable
              for submission to a journal. It is created by the 
              `scripts/RQ2_RQ3_Analyses.qmd` script.
            * `Descriptive_Analyses_Draft.pdf`: This is temporary draft output 
              obtained by rendering the `scripts/Descriptive_Analyses.qmd` 
              script directly. 
            * `Descriptive_Analyses_yyyy-mm-dd.pdf`: Production output obtained 
              by using `scripts/Production_Run.qmd` to render the 
              `scripts/Descriptive_Analyses.qmd` script will have names 
              following this date-stamped naming convention. An actual rendering 
              date will replace the `yyyy-mm-dd` notation. 
            * `Import_Data_Draft.pdf`: This is temporary draft output obtained 
              by rendering the `scripts/Import_Data.qmd` script directly. 
            * `Import_Data_yyyy-mm-dd.pdf`: Production output obtained by using 
              `scripts/Production_Run.qmd` to render the 
              `scripts/Import_Data.qmd` script will have names following this 
              date-stamped naming convention. An actual rendering date will 
              replace the `yyyy-mm-dd` notation. 
            * `RQ1_Analyses_Draft.pdf`: This is temporary draft output obtained 
              by rendering the `scripts/RQ1_Analyses.qmd` script directly. 
            * `RQ1_Analyses_yyyy-mm-dd.pdf`: Production output obtained by using 
              `scripts/Production_Run.qmd` to render the 
              `scripts/RQ1_Analyses.qmd` script will have names following this 
              date-stamped naming convention. An actual rendering date will 
              replace the `yyyy-mm-dd` notation. 
            * `RQ2_RQ3_Analyses_Draft.pdf`: This is temporary draft output 
              obtained by rendering the `scripts/RQ2_RQ3_Analyses.qmd` script 
              directly. 
            * `RQ2_RQ3_Analyses_yyyy-mm-dd.pdf`: Production output obtained by 
              using `scripts/Production_Run.qmd` to render the 
              `scripts/RQ2_RQ3_Analyses.qmd` script will have names following 
              this date-stamped naming convention. An actual rendering date will 
              replace the `yyyy-mm-dd` notation. 
            * `RQ4_Analyses_Draft.pdf`: This is temporary draft output obtained 
              by rendering the `scripts/RQ4_Analyses.qmd` script directly. 
            * `RQ4_Analyses_yyyy-mm-dd.pdf`: Production output obtained by using 
              `scripts/Production_Run.qmd` to render the 
              `scripts/RQ4_Analyses.qmd` script will have names following this 
              date-stamped naming convention. An actual rendering date will 
              replace the `yyyy-mm-dd` notation.
            * `Production_Run.html`: This is the log resulting from rendering 
              `scripts/Production_Run.qmd` directly with the Render button. This 
              documents when the production process was run and the result of 
              each step.
            * `Production_Run_yyyy-mm-dd.html`: This is the log resulting from 
              rendering `scripts/Production_Run.qmd` with a Terminal command as
              shown below in the Reproducing Our Results section of this 
              document. It documents when the production process was run and the 
              result of each step. An actual rendering date will replace the 
              `yyyy-mm-dd` notation.  
        * `.gitignore`: This was auto-created by Quarto. Don't edit or delete 
          it. 
        * `.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.
        * `_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. 
        * `compact-title.tex`: This LaTeX file can be called from an .qmd file's
           YAML header via the in_header option. It just formats the title of 
           the rendered PDF file so it uses less vertical white space. It is 
           used by multiple other scripts.
        * `CSTAT_style.css`:  This custom style sheet provides logo and title 
           banner formatting settings and classes for my HTML outputs. It 
           supplements `_brand.yml` and `CSTAT_theme.scss`.
        * `CSTAT_theme.scss`: This is a Sassy custom style sheet file to provide 
          formatting settings and classes for my slides and other HTML outputs. 
          It supplements `_brand.yml` and `CSTAT_style.css`.
        * `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_Analyses.qmd`: This script runs some supplemental 
          analyses that don;t directly address the research questions. 
          Methodology notes, references, and results interpretation are built 
          into this script and its output. Rendering this directly 
          generates draft output named `output/Descriptive_Analyses_Draft.pdf`; 
          you can get date-stamped production output (e.g., 
          `output/Descriptive_Analyses_yyyy-mm-dd.pdf`) by using 
          `scripts/Production_Run.qmd` to render this script. 
        * `Development_Tools.R`: This contains some examples of R commands I use 
          interactively when working on the package. 
        * `Export_Diagram.qmd`: This script runs exports Figure 1 for the . 
          manuscript. Rendering this directly 
          generates draft output named `output/Export_Diagram_Draft.pdf`; 
          you can get date-stamped production output (e.g., 
          `output/Export_Diagram_yyyy-mm-dd.pdf`) by using 
          `scripts/Production_Run.qmd` to render this script. 
        * `Import_Data.qmd`: This script imports the raw data from SPSS and 
          saves it in an `.RData` file for use by other scripts here. Rendering 
          this directly generates draft output named 
          `output/Import_Data_Draft.pdf`; you can get date-stamped production 
          output (e.g., `output/Import_Data_yyyy-mm-dd.pdf`) by using 
          `scripts/Production_Run.qmd` to render this script. 
        * `Production_Run.qmd`: This script is used to automate rendering other 
          scripts in the proper order to generate date-stamped production 
          outputs (e.g., `output/Import_Data_yyyy-mm-dd.pdf`). It also produces 
          `scripts/output/Production_Run.html`. 
        * `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.4.x to 4.5.x). 
        * `RQ1_Analyses.qmd`: This script runs the analyses for Research 
          Question 1. Methodology notes, references, and results interpretation 
          are built into this script and its output. Rendering this directly 
          generates draft output named `output/RQ1_Analyses_Draft.pdf`; you 
          can get date-stamped production output (e.g., 
          `output/RQ1_Analyses_yyyy-mm-dd.pdf`) by using 
          `scripts/Production_Run.qmd` to render this script. 
        * `RQ2_RQ3_Analyses.qmd`: This script runs the stopping-ratio model(s) 
          that comprise the analyses for Research Questions 2 and 3. Methodology 
          notes, references, and results interpretation are built into this 
          script and its output. Rendering this directly generates draft output 
          named `output/RQ2_RQ3_Analyses_Draft.pdf`; you can get date-stamped 
          production output (e.g., `output/RQ2_RQ3_Analyses_yyyy-mm-dd.pdf`) by 
          using `scripts/Production_Run.qmd` to render this script. 
        * `RQ4_Analyses.qmd`: This script runs the analyses for Research 
          Question 4. Methodology notes, references, and results interpretation 
          are built into this script and its output. Rendering this directly 
          generates draft output named `output/RQ4_Analyses_Draft.pdf`; you 
          can get date-stamped production output (e.g., 
          `output/RQ4_Analyses_yyyy-mm-dd.pdf`) by using 
          `scripts/Production_Run.qmd` to render this script. 
        * `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. 
        * `title.tex`: This LaTeX file enables better handling of author 
          affiliations in PDF outputs. It is used by multiple other scripts.
    * `.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.
    * `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 
      content other than source code in this repository.
    * `LICENSE.md`: This file contains the terms of the license that applies to 
      all source code in this repository.
    * `LICENSE.note`: This file describes which license applies to different 
      kinds of content 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. 
    * `SANETPA.Rproj`: This is an RStudio project file. It contains some 
      settings for working with the project in that software. 

## 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 *SANETPA* 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. 

## Data Files
The final raw data required to use this package are available in the GitHub 
repository's `scripts/extdata/` folder. They have been de-identified to protect 
participant privacy and confidentiality. 

The SPSS data file `script/extdata/All_group_1_2025-11-19.sav` has variable and 
value labels defined. The `scripts/Import_Data.qmd` script reads that file into 
R, produces a list of all the variables in the raw data, does a fair bit of data 
management, then writes out the `data/Imported_SANETP_Data.RData` file that is 
used by the analysis scripts. That imported data file contains multiple R data
frames derived from the raw data. Read the output of the script that produces it
to see exactly what happens with the data and get additional information about
the data.

The file `data/Imported_SANETP_Data.RData` included in the repository is the 
result I obtained with the final production run of the import script. 

## Loading the *SANETPA* Package in R
After it has been installed to your package library as described above, you can 
load *SANETPA* via the following R console command. That provides access to 
the custom R functions we have included in the package.  

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

library(SANETPA)
```

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 *SANETPA* 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-SANETPA
#| eval: false

?SANETPA
```

## 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. If you want to reproduce the 
results, you can double-click the `SANETPA.Rproj` file from Windows Explorer to 
open the project in RStudio. Rendering a Quarto script: 

* May read external data files from the `scripts/extdata/` folder.
* May write R data files to the `data/` folder. 
* Will generate output files in the `scripts/output/` folder.

Scripts in this package can generate either draft or production output. I wrote 
a [blog post](https://sjpierce.github.io/posts/output/draft_vs_production.html) 
describing a rationale for, and approach to, separating draft and production 
output. That approach has been implemented in this compendium.

### Draft Output
You can get draft output by rendering a script with its default parameters. Just 
use RStudio to open the relevant Quarto script (e.g., `scripts/Import_Data.qmd`) 
and then click the "Render" button in RStudio. This is most useful to
collaborators on our research team while we're developing the compendium before
publication of the associated paper. This allows us to focus on one script at a
time. We tend to edit and render draft output frequently as we do so,
overwriting the draft output each time to avoid creating too much file clutter.

### Production Output
Our final results for publication will be generated as production output. The 
production process requires rendering each of the main scripts in a specific 
order. We automated that process via the `scripts/Production_Run.qmd` script. 
Use RStudio to open that file and then click the "Render" button. If you have 
everything set up correctly, that will create date-stamped output files in the 
`scripts/output/` folder, plus the file `scripts/output/Production_Run.html`. 
The latter file contains a data flow diagram showing all the inputs and outputs
of the production process, how long it took to render each script called by the
production script, and information about the software environment used.

If you want to get a date-stamped output for the production run script itself, 
you can use something like the following command in the Terminal to change into
the `scripts/` folder and render that output. Just update the date in the output
filename to match the current date (a new output file will overwrite an existing
output file if they have the same file name).

```
cd scripts
quarto render Production_Run.qmd --output Production_Run_2026-02-14.html
```

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

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

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