Package 'CTNote' reference manual

Title:	CTN Outcomes, Treatments, and Endpoints
Description:	The Clinical Trials Network (CTN) of the U.S. National Institute of Drug Abuse sponsored the CTN-0094 research team to harmonize data sets from three nationally-representative clinical trials for opioid use disorder (OUD). The CTN-0094 team herein provides a coded collection of trial outcomes and endpoints used in various OUD clinical trials over the past 50 years. These coded outcome functions are used to contrast and cluster different clinical outcome functions based on daily or weekly patient urine screenings. Note that we abbreviate urine drug screen as "UDS" and urine opioid screen as "UOS". For the example data sets (based on clinical trials data harmonized by the CTN-0094 research team), UDS and UOS are largely interchangeable.
Authors:	Gabriel Odom [aut, cre] , Laura Brandt [aut] , Raymond Balise [aut] , Layla Bouzoubaa [ctb]
Maintainer:	Gabriel Odom <[email protected]>
License:	GPL-3
Version:	0.1.3
Built:	2024-11-16 05:22:28 UTC
Source:	https://github.com/ctn-0094/ctnote

Combine Multiple Simple Study Design "Lattices"

Description

Given a vector of simple study visits patterns, combine them into a more complex study visit lattice

Usage

collapse_lattice(lattice_patterns, times)
collapse_lattice(lattice_patterns, times)

Arguments

`lattice_patterns`	A character vector of simple study design lattices
`times`	An integer vector indicating the number of times to repeat each simple lattice. The length of the `times` argument should match the length of the `lattice_patterns` argument.

Details

This function was designed to handle outcomes where the clinical trial protocol has staggered or non-sequential visits. For example, if we observed the pattern "-ooo", in most cases we would interpret this to mean that the subject was present in the clinic for the first visit, but missed the next three visits. Some trial outcomes would then count the three missing visits as all positive or as a relapse. However, this use pattern could have been observed late during subject follow-up, during which time the protocol could be that the subject was only required to visit the clinic monthly (so long as the supplied UDS was negative).

This function is basically a wrapper around the paste0 function with collapse = "". We added support to repeat subpatterns.

Value

The combined lattice pattern, built up from combinations of the smaller lattices.

Examples

  
  # Example 1: a 16 week observation period with visits every 4 weeks:
  # "___o___o___o___o"
  collapse_lattice(
    lattice_patterns = "___o",
    times = 4
  )
  
  # Example 2: 24 week observation period with weekly visits for the first
  #   12 weeks, then monthly visits (during the second week) thereafter:
  # "oooooooooooo_o___o___o__"
  collapse_lattice(
    lattice_patterns = c("o", "_o__"),
    times = c(12, 3)
  )
  
  # Example 3: 6 week observation period with clinic visits on set days,
  #   M-W-F for the first 3 weeks, then Monday only for the next 3 weeks:
  # "o_o_o__o_o_o__o_o_o__o______o______o______"
  collapse_lattice(
    lattice_patterns = c("o_o_o__", "o______"),
    times = c(3, 3)
  )
  
  
# Example 1: a 16 week observation period with visits every 4 weeks:
  # "___o___o___o___o"
  collapse_lattice(
    lattice_patterns = "___o",
    times = 4
  )
  
  # Example 2: 24 week observation period with weekly visits for the first
  #   12 weeks, then monthly visits (during the second week) thereafter:
  # "oooooooooooo_o___o___o__"
  collapse_lattice(
    lattice_patterns = c("o", "_o__"),
    times = c(12, 3)
  )
  
  # Example 3: 6 week observation period with clinic visits on set days,
  #   M-W-F for the first 3 weeks, then Monday only for the next 3 weeks:
  # "o_o_o__o_o_o__o_o_o__o______o______o______"
  collapse_lattice(
    lattice_patterns = c("o_o_o__", "o______"),
    times = c(3, 3)
  )

Count Periods of Substance Use / Abstinence

Description

Given a use pattern string, count the number of times that pattern contains a certain substance use indicator

Usage

count_matches(
  use_pattern,
  match_is,
  start = 1,
  end = -1,
  mixed_results_are = NULL,
  mixed_weight = 0.5,
  proportion = FALSE
)
count_matches(
  use_pattern,
  match_is,
  start = 1,
  end = -1,
  mixed_results_are = NULL,
  mixed_weight = 0.5,
  proportion = FALSE
)

Arguments

`use_pattern`	A character string showing the daily, by visit, or weekly substance use pattern for a single subject
`match_is`	A single character value of the use indicator of interest; e.g. `"+"` is use positive or `"-"` is use negative.
`start`	These two arguments give the integer range wherein to look for the use sub-pattern of interest. Usually, start should be the week of randomization. Defaults to 1.
`end`	The end of the detection range. This is often the end of followup (denoted by -1, the default value, which represents the last item in the string), or this could be a set number of weeks or visits, such as 12 weeks or 48 visits.
`mixed_results_are`	A single character value indicating a partial use week; e.g. `"*"` means that the subject had at least one positive and at least one negative test of the substance(s) of interest for that week. Defaults to `NULL`.
`mixed_weight`	A fraction showing the proportional use value for a mixed result week. For example, some studies state that a positive UDS counts as three days of use (3/7), while other studies regard a positive UDS as five days of use (5/7). This value should be substance-specific, but we default to 0.5.
`proportion`	Should this function return the count or proportion of matching use periods? Defaults to `FALSE`, signifying that the count of matches will be returned. Note that if the remaining string (after trimming to the values of `start` and `end`) has length 0, then this function will return 0 rather than NaN (0/0). When interpreting this value, 0 represents that the subject had no use periods matching the chosen outcome.

Details

At current, we allow for many symbols in the use pattern "word", such as "_" for missing by study design, "o" missing for protocol non-compliance (the most common form of missing), "+" for positive, "-" for negative, and "*" for mixed positive and negative results (this usually comes up when the visit represents multiple days and there are both positive and negative results in those days; for example, a subject is tested weekly; they provided a positive test on Tuesday but came back to provide a negative test the following day).

Value

A single integer (real) value measuring the count (proportion) of the use periods for which the subject had the substance use value of interest

Examples

  # This pattern represents 26 weeks of treatment UDS
  pattern_char <- "++++*o-------+--+-o-o-o+o+"
  
  # Replace any missing UDS ("o") with positive
  cleanPattern_char <- recode_missing_visits(pattern_char)
  
  # Example: find the proportion of the subject's negative use weeks after
  #   randomization but before the end of a 12-week observation
  #   period
  count_matches(
    cleanPattern_char,
    match_is = "-",
    end = 12,
    mixed_results_are = "*",
    mixed_weight = 0.5,
    proportion = TRUE
  )
  
  # Example: find the number of times the subject used non-study opioids
  #   after being clean at least one week
  count_matches(
    cleanPattern_char,
    match_is = "-+"
  )
  
# This pattern represents 26 weeks of treatment UDS
  pattern_char <- "++++*o-------+--+-o-o-o+o+"
  
  # Replace any missing UDS ("o") with positive
  cleanPattern_char <- recode_missing_visits(pattern_char)
  
  # Example: find the proportion of the subject's negative use weeks after
  #   randomization but before the end of a 12-week observation
  #   period
  count_matches(
    cleanPattern_char,
    match_is = "-",
    end = 12,
    mixed_results_are = "*",
    mixed_weight = 0.5,
    proportion = TRUE
  )
  
  # Example: find the number of times the subject used non-study opioids
  #   after being clean at least one week
  count_matches(
    cleanPattern_char,
    match_is = "-+"
  )

Detect Visits before Matching a Fuzzy Sub-Pattern

Description

Given a use pattern string, use fuzzy logic to detect if a sub-pattern of interest is present within a specified detection window and how many visits are required to find said match.

Usage

detect_in_window(
  use_pattern,
  window_width = 4L,
  threshold = 3L,
  offset = window_width - threshold,
  match_is = c("+", "o", "-")
)
detect_in_window(
  use_pattern,
  window_width = 4L,
  threshold = 3L,
  offset = window_width - threshold,
  match_is = c("+", "o", "-")
)

Arguments

`use_pattern`	A character string showing the daily, by visit, or weekly
`window_width`	How wide should the inspection window be? Defaults to four visits.
`threshold`	How many successes or failures are required within the specified window? Defaults to three.
`offset`	In the case of an event, where in the detection window should the event time be recorded? Defaults to `window_width - threshold`; that is, the start of the actual pattern. Another option would be 0, which indicates that the event should be recorded at the start of the window in which it was detected.
`match_is`	What constitutes the outcome of interest? `"+"` represents positive UDS as the visit event of interest, `"-"` is negative, and `"o"` means that the subject did not provide a valid UDS during the time period in question.

Details

This function can be used to calculate time-to-event (survival) metrics for the subjects in treatment. For example, the default arguments represent a definition of relapse ("three or more positive UDS within a four-week window"). Thus, the output of this function under default values would be time until first relapse and a relapse indicator.

Concerning the offset argument: take, for example, the use pattern "-------++++". The subject began to use the substance(s) of interest by week 8. If our relapse definition was to detect 4 weeks of use in a 4 week window, then the relapse time would be recorded at week 8. Similarly, we would expect that if our relapse definition was to detect 2 or 3 weeks of use in a 4 week window, that the relapse time would also be week 8. This is why the default value of the offset argument is what it is: we "shift" the detection of the use until the start of the use. However, if you see the pattern above and believe that the relapse should be recorded at week 7 for relapse defined as 3 weeks of use in a 4-week window or at week 6 for 2 weeks of use in a 4-week window, then set offset = 0.

Defining the use symbols: at current, we allow for many symbols in the use pattern "word", such as "_" for missing by study design, "o" missing for protocol non-compliance (the most common form of missing), "+" for positive, "-" for negative, and "*" for mixed positive and negative results (this usually comes up when the visit represents multiple days and there are both positive and negative results in those days; for example, a subject is tested weekly; they provided a positive test on Tuesday but came back to provide a negative test the following day).

Value

A two column data frame with (a) column time representing the number of visits until the first window with a match is detected and (b) column event indicating if the match occurs in any window of the use pattern.

Examples

  # Find the first relapse event
  detect_in_window("o-o+++")
  
  # Find the start of the window that contains the first relapse event
  detect_in_window("o-o+++", offset = 0)
  
  # Find the first positive UDS
  detect_in_window("o-o+++", window_width = 1L, threshold = 1L)
  
# Find the first relapse event
  detect_in_window("o-o+++")
  
  # Find the start of the window that contains the first relapse event
  detect_in_window("o-o+++", offset = 0)
  
  # Find the first positive UDS
  detect_in_window("o-o+++", window_width = 1L, threshold = 1L)

Detect a Consecutive Sub-Pattern

Description

Given a use pattern string, detect if that pattern contains a consecutive sub-pattern of interest

Usage

detect_subpattern(use_pattern, subpattern, start = 1, end = -1)
detect_subpattern(use_pattern, subpattern, start = 1, end = -1)

Arguments

`use_pattern`	A character string showing the daily, by visit, or weekly substance use pattern for a single subject
`subpattern`	A character string containing the sub-pattern of interest. For example, if study dropout is seven consecutive missing UDS, then the sub-pattern would be "ooooooo".
`start`	These two arguments give the integer range wherein to look for the use sub-pattern of interest. Usually, start should be the week of randomization. Defaults to 1.
`end`	The end of the detection range. This is often the end of followup (denoted by -1, the default value, which represents the last item in the string), or this could be a set number of weeks or visits, such as 12 weeks or 48 visits.

Details

This function can be used to detect consecutive periods of drug abstinence, drug use, or study non-compliance (as measured by failure to supply urine). For example, to detect if the subject had three consecutive use weeks, the sub-pattern would be set to "+++".

Value

A single logical value indicating if the use subpattern is present in the overall use pattern string

Examples

  # This pattern represents 26 weeks of treatment UDS
  pattern_char <- "+++++o-------+--+-o-o-o+o+"
  
  # Replace any missing UDS ("o") with positive
  cleanPattern_char <- recode_missing_visits(pattern_char)
  
  # Example: detect if the subject was able to stay clean for at least 4
  #   weeks after randomization but before the end of a 12-week observation
  #   period
  detect_subpattern(
    cleanPattern_char,
    subpattern = "----",
    end = 12
  )
  
  # Example: detect if the subject was abstinent during the last 3 weeks
  detect_subpattern(
    cleanPattern_char,
    subpattern = "---",
    start = -3, 
    end = -1
  )
  
# This pattern represents 26 weeks of treatment UDS
  pattern_char <- "+++++o-------+--+-o-o-o+o+"
  
  # Replace any missing UDS ("o") with positive
  cleanPattern_char <- recode_missing_visits(pattern_char)
  
  # Example: detect if the subject was able to stay clean for at least 4
  #   weeks after randomization but before the end of a 12-week observation
  #   period
  detect_subpattern(
    cleanPattern_char,
    subpattern = "----",
    end = 12
  )
  
  # Example: detect if the subject was abstinent during the last 3 weeks
  detect_subpattern(
    cleanPattern_char,
    subpattern = "---",
    start = -3, 
    end = -1
  )

Opioid Use by Study Day for Example CTN-0094 Participants

Description

This data set is a table with daily positive opioid use indicator for 10 participants from the CTN-0094 harmonized data sets. This subset is to be used as an example of timeline-style opioid use data.

Usage

data(egOpioidsCTN0094)
data(egOpioidsCTN0094)

Format

A tibble with 71 rows and 3 columns. These columns include

who: Patient ID
what: A factor indicating what substance(s) were present in the urine on day when; trivially, all substances are "opioids" for this example data.
when: The number of days since signed study consent

Details

This data is created in the script inst/scripts/create_allDrugs_opioid_subset_20220916.R. The "when" column measures the number of days after signed consent for the participant that the opioid-positive urine screen was collected.

Naively Impute Missing Visits

Description

Given a use pattern string with missing visits, make naive imputations for each missing visit

Usage

impute_missing_visits(
  use_pattern,
  method = c("locf", "locfD", "mode", "kNV"),
  missing_is = "o",
  mixed_is = "*",
  tiebreaker = "+",
  k = 1,
  knvWeights_num = c(o = NA, `+` = 1, `*` = 0.5, `-` = 0),
  quietly = FALSE
)
impute_missing_visits(
  use_pattern,
  method = c("locf", "locfD", "mode", "kNV"),
  missing_is = "o",
  mixed_is = "*",
  tiebreaker = "+",
  k = 1,
  knvWeights_num = c(o = NA, `+` = 1, `*` = 0.5, `-` = 0),
  quietly = FALSE
)

Arguments

`use_pattern`	A character string showing the daily, by visit, or weekly substance use pattern for a single subject
`method`	Which naive imputation method should be used? Current supported options are `"locf"` (last observation carried forward), `"locfD"` (last observation carried forward until dropout), `"mode"` (most common non-missing value), and `"kNV"` (k nearest visits).
`missing_is`	Which single character is used to mark missing UDS in a use pattern string? Defaults to `"o"`.
`mixed_is`	Which single character is used to mark mixed UDS (both positive and negative UDS for the visit block) in a use pattern string? Defaults to `"*"`. When imputing by the mode, all mixed result UDS will be assigned the `tiebreaker` value in order to calculate the mode but will remain unchanged in the returned use pattern string.
`tiebreaker`	In the event of ties between two modes, should positive or negative UDS be the mode? Defaults to positive (`"+"`).
`k`	The number of nearest visits to use in kNV imputation. This defaults to 1; we recommend that this parameter stays at 1 unless the use patterns in your data have extraordinarily few missing values.
`knvWeights_num`	A named vector matching the use pattern word "letters" to their numerical use values. The names of this vector should match the "letters" of the use pattern word exactly; use backticks to escape special characters. For example, if the study protocol counts a mixed result (one positive and one negative UDS in a single observation period [week]) as worth three "use days", then mixed results should have a weight of 3/7. Additionally, a study protocol may count missing values as five "use days" out of a week. The defaults for this function are to leave `"o"` as missing (`NA`), and give weights of 1, 1/2, and 0 for visits with `"+"`, `"*"`, and `"-"` UDS, respectively.
`quietly`	Should warning messages be muted? Defaults to `FALSE`

Details

If you would like to replace all UDS for missing visits with a single, pre-specified value (such as positive), please use recode_missing_visits instead. Furthermore, there will most likely still be missing values in the use pattern even after imputation. This would occur if all the values are missing, if the first values of the use pattern are missing (if LOCF is used), if the first and/or last values of the use pattern are missing (if LOCF-D is used), or if there are back to back missing visits (if kNV with k = 1 is used). Because of this, you may need to call recode_missing_visits in a pipeline after this function to replace or remove the remaining non-imputable missing visits.

If you are using the kNV imputation option, there are some caveats to consider. Due to rounding rules, any rounding ties are broken by order of the values to the knvWeights_num vector. For instance, consider a subject who had a negative UDS in one week, then a missing UDS for the next week, and then two UDS in the following week (of which one was positive and the other was negative). This is represented by the use pattern "-o*". The default behavior of the kNV method is to impute this to "-**" because the order of the knvWeights_num vector has "+", then "*", then "-" UDS values. In this order, a positive result trumps a mixed result, and a mixed result trumps a negative result. Similarly, the use pattern "+o*" will be imputed to "++*" by default.

Value

A use pattern string the same length as use_pattern with missing values imputed according to the chosen imputation method.

Examples

  pattern_char <- "__++++*o-------+--+-o-o-o+o+oooooo"
  impute_missing_visits(pattern_char)
  impute_missing_visits(pattern_char, method = "locfD")
  impute_missing_visits(pattern_char, method = "mode")
  
  pattern2_char <- "ooooooooooo"
  impute_missing_visits(pattern2_char)
  
pattern_char <- "__++++*o-------+--+-o-o-o+o+oooooo"
  impute_missing_visits(pattern_char)
  impute_missing_visits(pattern_char, method = "locfD")
  impute_missing_visits(pattern_char, method = "mode")
  
  pattern2_char <- "ooooooooooo"
  impute_missing_visits(pattern2_char)

Measure the Length of the Longest Abstinent Period

Description

Find the longest number of sequential visits in the pattern with negative UDS

Usage

measure_abstinence_period(use_pattern_binary, use_is = "+")
measure_abstinence_period(use_pattern_binary, use_is = "+")

Arguments

`use_pattern_binary`	A character string showing the daily, by visit, or weekly substance use pattern for a single subject, recoded to binary use or abstinence indicators.
`use_is`	Which single character is used to mark positive UDS in the use pattern string? Defaults to `"+"`.

Details

The use pattern MUST be in binary code for this function to work. For use patterns coded in our default language (see the "dictionary" in the Details section for measure_retention), the binary form would have all "_" (missing by study protocol) visits replaced with "-" and all "o" (missing for non-compliance) and "*" (mixed positive and negative) visits replaced with "+". See the example below.

Value

An integer measuring the longest number of sequential visits for which the subject was abstinent from the substance(s) of interest. If the subject's entire use pattern is missing, then this will be 0.

Examples

  pattern_char <- "__++++*o-------+--+-o-o-o+o+oooooo"
  
  # replace "_" with "-"
  pattern2_char <- recode_missing_visits(
    pattern_char,
    missing_is = "_",
    missing_becomes = "-"
  )
  # replace "o" with "+"
  pattern3_char <- recode_missing_visits(pattern2_char)
  # replace "*" with "+"
  pattern4_char <- recode_missing_visits(pattern3_char, missing_is = "*")
  
  measure_abstinence_period(pattern4_char)
  
pattern_char <- "__++++*o-------+--+-o-o-o+o+oooooo"
  
  # replace "_" with "-"
  pattern2_char <- recode_missing_visits(
    pattern_char,
    missing_is = "_",
    missing_becomes = "-"
  )
  # replace "o" with "+"
  pattern3_char <- recode_missing_visits(pattern2_char)
  # replace "*" with "+"
  pattern4_char <- recode_missing_visits(pattern3_char, missing_is = "*")
  
  measure_abstinence_period(pattern4_char)

Measure Length of Use Pattern before Dropout

Description

Find the number of visits in the pattern until the last subject contact

Usage

measure_retention(use_pattern, missing_is = "o")
measure_retention(use_pattern, missing_is = "o")

Arguments

`use_pattern`	A character string showing the daily, by visit, or weekly substance use pattern for a single subject
`missing_is`	Which single character is used to mark missing UDS in a use pattern string? Defaults to `"o"`.

Details

Value

An integer measuring the number of visits before the subject was lost to follow-up. If the subject's entire use pattern is missing, then this will be 0.

Examples

  pattern_char <- "__++++*o-------+--+-o-o-o+o+oooooo"
  measure_retention(pattern_char)
  
  pattern2_char <- "ooooooooooo"
  measure_retention(pattern2_char)
  
pattern_char <- "__++++*o-------+--+-o-o-o+o+oooooo"
  measure_retention(pattern_char)
  
  pattern2_char <- "ooooooooooo"
  measure_retention(pattern2_char)

All Treatment Outcomes for CTN-0094 Participants

Description

This data set is a table of 53 treatment outcomes calculated on 3560 participants from three clinical trials to assess the efficacy of medication-assisted treatment for opioid use disorder.

Usage

data(outcomesCTN0094)
data(outcomesCTN0094)

Format

A tibble with 3,560 rows and 64 columns. These columns include

who: Patient ID
usePatternUDS: A character string containing the "use pattern word", which represents the weekly opioid use for each participant after their day of randomization. For more information, see link[ctn0094DataExtra]{derived_weeklyOpioidPattern}
...: The calculated treatment outcomes for 53 endpoints. Some endpoints are composites of "time to event" and an "event" indicator, but these are included as two separate columns and are named ⁠*_time⁠ and ⁠*_event⁠, respectively.

Details

These outcomes are based on a harmonized set of data from three clinical trials. The harmonized data from these trials are contained in the packages ctn0094data and ctn0094DataExtra. These outcomes are calculated in the three abstinence, relapse, and reduction "library" vignettes of this package. The data dictionary is currently stored as an Excel spreadsheet in inst/suppl_docs/definitions_20221123.xlsx.

Recode Missing or Ambiguous UDS in a Subject Use Pattern

Description

Replace all missing UDS "o" in a use pattern string

Usage

recode_missing_visits(
  use_pattern,
  missing_is = "o",
  missing_becomes = c("+", "", "-")
)
recode_missing_visits(
  use_pattern,
  missing_is = "o",
  missing_becomes = c("+", "", "-")
)

Arguments

`use_pattern`	A character string showing the daily, by visit, or weekly substance use pattern for a single subject
`missing_is`	Which single character is used to mark missing UDS in a use pattern string? Defaults to `"o"`.
`missing_becomes`	How should missing UDS be treated? Defaults to marking the subject as positive for that missing period. Options are `"+"` for positive, `""` for ignore, or `"-"` for negative (note that this last option should only be used in case where the "missing" UDS is a regular and expected artefact of the study design and the preceding and following UDS are both negative).

Details

Value

A character string with all missing UDS values (marked as "o" unless a different value is supplied to missing_is) replaces by the value supplied to missing_becomes.

Examples

  pattern_char <- "__++++*o-------+--+-o-o-o+o+"
  
  # Default: change all missing weeks to positive
  recode_missing_visits(pattern_char)
  
  # Other example: remove all weeks with no UDS by design
  recode_missing_visits(pattern_char, missing_is = "_", missing_becomes = "")
  
pattern_char <- "__++++*o-------+--+-o-o-o+o+"
  
  # Default: change all missing weeks to positive
  recode_missing_visits(pattern_char)
  
  # Other example: remove all weeks with no UDS by design
  recode_missing_visits(pattern_char, missing_is = "_", missing_becomes = "")

View a Pattern through a Study Design "Lattice"

Description

Given a use pattern string and the pattern of study visits, view only the use pattern string components which are congruent with the study design

Usage

view_by_lattice(
  use_pattern,
  lattice_pattern,
  visit_is = "o",
  no_visit_is = "_"
)
view_by_lattice(
  use_pattern,
  lattice_pattern,
  visit_is = "o",
  no_visit_is = "_"
)

Arguments

`use_pattern`	A character string showing the daily, by visit, or weekly substance use pattern for a single subject
`lattice_pattern`	A character string containing the study design for subject visits. For example, a study design with required visits on Monday, Wednesday, and Friday would have the lattice pattern `"o_o_o__"`, where `"o"` represents a day wherein the subject should visit the clinic (per study protocol) and `"_"` represents the other non-visit days. These symbols are set by `visit_is` and `no_visit_is`, respectively.
`visit_is`	Symbol indicating that the subject should appear in the clinic for that time period, as dictated by the study protocol. Defaults to `"o"` (because the outcome of the UDS will be unknown before the study has been designed).
`no_visit_is`	Symbol indicating that the subject is not required to appear in the clinic for that time period, as dictated by the study protocol. Defaults to `"_"`.

Details

Many lattice patterns can be easily constructed by using the function collapse_lattice. For example, to repeat the "Monday-Wednesday-Friday" visit pattern noted above 4 times, you can use collapse_lattice("o_o_o__", 4) to create a vector of weekly visit patterns, then collapse (concatenate) them all together. More complex visit patterns can be constructed in a similar manner: first create a vector of simple repeating visit patterns, then collapse them all together, setting the number of repeats with the times argument.

At current, this package allows for many symbols in the use pattern "word", such as "_" for missing by study design, "o" missing for protocol non-compliance (the most common form of missing), "+" for positive, "-" for negative, and "*" for mixed positive and negative results (this usually comes up when the visit represents multiple days and there are both positive and negative results in those days; for example, a subject is tested weekly; they provided a positive test on Tuesday but came back to provide a negative test the following day).

Value

A variant of use_pattern, but with all non-protocol visits set to "_". In most cases, this use pattern vector would be then passed to impute_missing_visits so that the "_" visits could be replaced with the last observed UDS. See the Examples below.

Examples

  # This pattern represents 26 weeks of treatment UDS
  pattern_char  <- "+++++o-------+--+-o-o-o+o+"
  pattern2_char <- recode_missing_visits(pattern_char)
  
  # Example 1: a 16 week observation period with visits every 4 weeks
  lattice1_char <- "___o___o___o___o"
  useLattice1_char <- view_by_lattice(
    use_pattern = pattern2_char,
    lattice_pattern = lattice1_char
  )
  useLattice1_char
  impute_missing_visits(useLattice1_char, method = "locf", missing_is = "_")
  
  # Example 2: 24 week observation period with weekly visits for the first
  #   12 weeks, then monthly visits (during the second week) thereafter
  lattice2_char <- "oooooooooooo_o___o___o__"
  useLattice2_char <- view_by_lattice(
    use_pattern = pattern2_char,
    lattice_pattern = lattice2_char
  )
  useLattice2_char
  impute_missing_visits(useLattice2_char, method = "locf", missing_is = "_")
     
# This pattern represents 26 weeks of treatment UDS
  pattern_char  <- "+++++o-------+--+-o-o-o+o+"
  pattern2_char <- recode_missing_visits(pattern_char)
  
  # Example 1: a 16 week observation period with visits every 4 weeks
  lattice1_char <- "___o___o___o___o"
  useLattice1_char <- view_by_lattice(
    use_pattern = pattern2_char,
    lattice_pattern = lattice1_char
  )
  useLattice1_char
  impute_missing_visits(useLattice1_char, method = "locf", missing_is = "_")
  
  # Example 2: 24 week observation period with weekly visits for the first
  #   12 weeks, then monthly visits (during the second week) thereafter
  lattice2_char <- "oooooooooooo_o___o___o__"
  useLattice2_char <- view_by_lattice(
    use_pattern = pattern2_char,
    lattice_pattern = lattice2_char
  )
  useLattice2_char
  impute_missing_visits(useLattice2_char, method = "locf", missing_is = "_")

Weight Visits in a Subject Use Pattern

Description

Add numeric weights to a use pattern string

Usage

weight_positive_visits(
  use_pattern,
  weights_num = c(`+` = 1, `*` = 0.5, o = 0.22, `-` = 0),
  posPenalty_num = NULL,
  missPenalty_num = NULL,
  scaleMax = 120L,
  scale = TRUE
)
weight_positive_visits(
  use_pattern,
  weights_num = c(`+` = 1, `*` = 0.5, o = 0.22, `-` = 0),
  posPenalty_num = NULL,
  missPenalty_num = NULL,
  scaleMax = 120L,
  scale = TRUE
)

Arguments

`use_pattern`	A character string showing the daily, by visit, or weekly substance use pattern for a single subject
`weights_num`	A named numeric vector mapping the symbols in the use pattern to non-negative numeric values. The default values, 1 for positive UDS (`"+"`), 0.22 for missing UDS (`"o"`), and 0 for negative UDS (`"-"`), are the values set in Ling et al. (1976); see the "Details" section for more information. The default value for a mixed weekly result (`"*"`: at least one positive and at least one negative UDS in a single week) is the average of a positive and negative weight (0.5 by default).
`posPenalty_num`	A numeric vector showing the penalty for having a positive or mixed UDS (`"+"` or `"*"`) at each week in the use pattern. Defaults to `NULL`, implying that a positive UDS should have the same weight at any week in the pattern. One other useful option would be to set the weights to increase along the length of the study protocol, so that the penalty for having a positive UDS is grows larger the longer a participant is in treatment. See the Examples for more information.
`missPenalty_num`	A numeric vector showing the penalty for having a missing UDS (`"o"`) at each week in the use pattern. Defaults to `NULL`, implying that a missing UDS should have the same weight at any week in the pattern. One other useful option would be to set the weights to decrease along the length of the study protocol, so that the penalty for missing a clinic visit grows smaller the longer a participant has continued in treatment.
`scaleMax`	Standardize the score to which maximum? Defaults to 120 to match the scoring scale in Ling et al. (1976). See "Details" for more.
`scale`	Scale the resulting score to a standard maximum (given by the `scaleMax` argument). This defaults to `TRUE`; this should not be changed unless you are a developer and you are trying to debug your code.

Details

This function exists to code the treatment outcome defined in Ling et al. (1976): doi:10.1001/archpsyc.1976.01770060043007. This definition requires other CTNote:: functions as well, but this function was written specifically for that definition.

The weights_num argument is the static "penalty" for positive and missing UDS values; this will not change over the protocol weeks. These values are then multiplied by the penalty vectors (posPenalty_num and missPenalty_num).

Value

A numeric value: the results of the sum of all the visit weight values for the use pattern

Examples

  pattern_char <- "++o+*-------+--+-o-o-o+o+"
  
  
  ###  Defaults  ###
  # See how the weights map to the symbols (DO NOT use in practice)
  weight_positive_visits(pattern_char, scale = FALSE)
  
  # Score this use pattern via default settings
  weight_positive_visits(pattern_char)
  
  
  ###  Increase Static Weight of Missing UDS  ###
  # Because the score for a missing UDS from the Ling et al. (1976) paper was
  #   an estimated value from their data, other weights may better represent
  #   modern addiction behavior patterns. For instance, we believe that 
  #   missing UDS values may be worse than a positive UDS in some instances,
  #   because they indicate that the subject is no longer participating in 
  #   treatment at all. We then should change the static weights to reflect
  #   this.
  weight_positive_visits(
    pattern_char,
    weights_num = c(`+` = 0.8, `*` = 0.4, `o` = 1, `-` = 0)
  )
  
  
  ###  Increasing Positive UDS Penalty  ###
  # Score this use pattern using an increasing positive UDS penalty (similar
  #   to that shown in Lint et al. (1976))
  newPosPenal_num <- seq(
    from = 1, to  = 5, 
    length = stringr::str_length(pattern_char)
  )
  weight_positive_visits(pattern_char, posPenalty_num = newPosPenal_num)
  
  
  ###  Variable Missing UDS Penalty  ###
  # Score this use pattern using a step-down missing UDS penalty (based on
  #   the idea that missing values during the treatment induction period are
  #   much worse than missing any other time in the study)
  newMissPenal_num <- rep(1, stringr::str_length(pattern_char))
  newMissPenal_num[1:4] <- 3
  weight_positive_visits(pattern_char, missPenalty_num = newMissPenal_num)
  
  
  ###  Composite Penalties  ###
  # Score this use pattern with both increasing positive UDS and step-down
  #   missing UDS penalties, while adjusting the weights.
  weight_positive_visits(
    pattern_char,
    weights_num = c(`+` = 0.8, `*` = 0.4, `o` = 1, `-` = 0),
    posPenalty_num = newPosPenal_num,
    missPenalty_num = newMissPenal_num
  )
  
pattern_char <- "++o+*-------+--+-o-o-o+o+"
  
  
  ###  Defaults  ###
  # See how the weights map to the symbols (DO NOT use in practice)
  weight_positive_visits(pattern_char, scale = FALSE)
  
  # Score this use pattern via default settings
  weight_positive_visits(pattern_char)
  
  
  ###  Increase Static Weight of Missing UDS  ###
  # Because the score for a missing UDS from the Ling et al. (1976) paper was
  #   an estimated value from their data, other weights may better represent
  #   modern addiction behavior patterns. For instance, we believe that 
  #   missing UDS values may be worse than a positive UDS in some instances,
  #   because they indicate that the subject is no longer participating in 
  #   treatment at all. We then should change the static weights to reflect
  #   this.
  weight_positive_visits(
    pattern_char,
    weights_num = c(`+` = 0.8, `*` = 0.4, `o` = 1, `-` = 0)
  )
  
  
  ###  Increasing Positive UDS Penalty  ###
  # Score this use pattern using an increasing positive UDS penalty (similar
  #   to that shown in Lint et al. (1976))
  newPosPenal_num <- seq(
    from = 1, to  = 5, 
    length = stringr::str_length(pattern_char)
  )
  weight_positive_visits(pattern_char, posPenalty_num = newPosPenal_num)
  
  
  ###  Variable Missing UDS Penalty  ###
  # Score this use pattern using a step-down missing UDS penalty (based on
  #   the idea that missing values during the treatment induction period are
  #   much worse than missing any other time in the study)
  newMissPenal_num <- rep(1, stringr::str_length(pattern_char))
  newMissPenal_num[1:4] <- 3
  weight_positive_visits(pattern_char, missPenalty_num = newMissPenal_num)
  
  
  ###  Composite Penalties  ###
  # Score this use pattern with both increasing positive UDS and step-down
  #   missing UDS penalties, while adjusting the weights.
  weight_positive_visits(
    pattern_char,
    weights_num = c(`+` = 0.8, `*` = 0.4, `o` = 1, `-` = 0),
    posPenalty_num = newPosPenal_num,
    missPenalty_num = newMissPenal_num
  )

Package 'CTNote'

Help Index

Combine Multiple Simple Study Design "Lattices"

Description

Usage

Arguments

Details

Value

Examples

Count Periods of Substance Use / Abstinence

Description

Usage

Arguments

Details

Value

Examples

Detect Visits before Matching a Fuzzy Sub-Pattern

Description

Usage

Arguments

Details

Value

Examples

Detect a Consecutive Sub-Pattern

Description

Usage

Arguments

Details

Value

Examples

Opioid Use by Study Day for Example CTN-0094 Participants

Description

Usage

Format

Details

Naively Impute Missing Visits

Description

Usage

Arguments

Details

Value

Examples

Measure the Length of the Longest Abstinent Period

Description

Usage

Arguments

Details

Value

Examples

Measure Length of Use Pattern before Dropout

Description

Usage

Arguments

Details

Value

Examples

All Treatment Outcomes for CTN-0094 Participants

Description

Usage

Format

Details

Recode Missing or Ambiguous UDS in a Subject Use Pattern

Description

Usage

Arguments

Details

Value

Examples

View a Pattern through a Study Design "Lattice"

Description

Usage

Arguments

Details

Value

Examples

Weight Visits in a Subject Use Pattern

Description

Usage

Arguments

Details