title
CTNote

Introduction to CTNote: The CTN Outcomes, Treatments, and Endpoints Library

The package CTNote exists as a comprehensive implementation of outcomes, treatments, and endpoints used in clinical trials to evaluate the efficacy of medication-assisted treatment of substance use disorders (SUDs).

• The functions in this package are programmatic building blocks with which to construct algorithms which calculate single-value summaries of clinical trial participants' substance use patterns.
• We assume that these person-specific substance use patterns over time are symbolized as a "word" (see below).
• The vignettes for this package include a standard and code-based library of algorithms for treatment outcome definitions useful to evaluate medication-based treatments for SUDs. We envision these vignettes as a "library", in the sense that someone interested in using the endpoint from a previously-published study can simply "borrow" (i.e., copy and paste) the code from these vignettes into their own analysis scripts. In these cases, we simply ask that you cite the original paper for the endpoint of your choice and this package.

Installation

You can install the released version of CTNote from CRAN with:

install.packages("CTNote")

Citing this Package

We expect the paper corresponding to this package will be published shortly in PLOS One. The expected citation would be

Odom GJ/Brandt L, Castro C, Luo SX, Feaster DJ, Balise, RR, and the CTN-0094 Team. (Under Review, expected 2023). Capturing drug use patterns at a glance: An n-ary word sufficient statistic for repeated univariate categorical values. PLOS One.

To find citation information for this package, call the following code:

citation("CTNote")

---

Use Pattern "Words"

If you wish to apply the functions in this package to create algorithms to calculate endpoints for your data, the participants' substance use patterns must be stored in the "substance use pattern word" format shown below.

We define the following five-value legend:

• +: positive for the substance(s) in a specified window of time (a day, week, month, etc.) by urine screen (or participant self report, if such data are of interest)
• –: negative for the substance(s)
• o: subject failed to provide a urine sample
• *: inconclusive results or mixed results (e.g. subject provided more than one urine sample in the time interval and they did not agree)
• _: no specimens required (weekends, holidays, pre-randomization period, alternating visit days/weeks)

For example, a participant who attended the clinic for three consecutive weeks on Mondays, Wednesdays, and Fridays, and was abstinent from the substance of interest on all days but the first two, would have their substance use pattern recorded as (assuming the week starts on Sunday):

"_+_+_-__-_-_-__-_-_-_"

As another example, consider a clinical trial with urine samples submitted weekly over a 12 week protocol. If a trial participant submitted positive urine samples for the first 3 weeks, but then did not return to the clinic for the remainder of the trial (they were lost to follow-up), then their substance use pattern would be recorded in a "word" as:

"+++ooooooooo"

---

Example

This is a basic example which shows how to measure a participant's duration in the study:

library(CTNote)

usePattern_char <- "__++++*o-------+--+-o-o-o+o+oooooo"

measure_retention(usePattern_char)

This function will count the number of visits (weeks in this case) until the last non-missing symbol is observed---in this case, 28 weeks, including the first two weeks before the randomization period (shown as __).