The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

CTNote Library: Abstinence Outcomes

Gabriel Odom, Laura Brandt, Sean Luo, and Ray Balise

2022-10-01

Introduction

This document contains the algorithms necessary to code all the outcomes which measure “abstinence from substance use” or “relapse to substance use”. We only include outcomes which result in a single value per subject. These outcomes are:

Group Endpoint Class Reference Definition Missing is
Abstinence Abstinence weeks integer Fiellin et al., 2006 Weeks of confirmed opioid abstinence Positive
Abstinence Continuous abstinence logical Kosten et al., 1993 attaining at least 3 weeks of consecutive negative UOS Missing/not imputed
Abstinence Complete Abstinence logical Krupitsky et al., 2011 Confirmed opioid abstinence during weeks 5‐24 based on UOS Positive
Abstinence Abstinence weeks integer Krupitsky et al., 2011 Weeks of confirmed opioid abstinence Positive
Abstinence Continuous abstinence logical Ling et al., 1998 % of participants who maintained 13 consecutive negative UOS (1 month) Missing/not imputed
Abstinence Complete Abstinence logical Lofwall et al., 2018 No evidence of opioid use based on UOS (NOTE: minimal evidence of opioid use from UOS, not none) Positive
Abstinence Length of Initial Abstinence survival Mokri, Chawarski, Taherinakhost, & Schottenfeld, 2016 Days to 1st positive UOS Positive
Abstinence Longest period of abstinence integer Schottenfeld et al., 2005 Max. number of consecutive weeks of negative UOS Missing
Abstinence Longest period of abstinence integer Schottenfeld et al., 2008 Longest period of negative UOS Positive
Abstinence Length of Initial Abstinence survival Schottenfeld, Chawarski, & Mazlan, 2008 Days to 1st positive UOS after randomization Positive
Abstinence Length of Initial Abstinence survival Shufman et al., 1994 Weeks between 1st day of NTX administration and 1st positive UOS Missing
Abstinence Abstinence period logical Weiss et al., 2011 CTN-0030 Negative UOS during the last week AND for at least 2 of the previous 3 weeks of the third month of BUP/NX treatment Positive

We will use the table of participant opioid use patterns from the ctn0094DataExtra package to calculate these endpoints (we have a copy of the endpoints in the dataset outcomesCTN0094). Importantly, if you wish to apply these algorithms to calculate endpoints for your data, the participants’ substance use patterns must be stored in the “substance use pattern word” format shown here. We also show a subset of the data to visualize a variety of different real substance use patterns.

We first define the following five-value legend:

Code
###  Full Data  ###
udsOutcomes_df <- 
    CTNote::outcomesCTN0094 %>% 
  select(who, usePatternUDS)

# Make a copy
outcomesAbs_df <- udsOutcomes_df


###  Examples  ###
examplePeople_int <- c(1, 163, 210, 242, 4, 17, 13, 1103, 233, 2089)
outcomesAbs_df %>% 
  filter(who %in% examplePeople_int)
## # A tibble: 10 × 2
##      who usePatternUDS                      
##    <dbl> <chr>                              
##  1     1 ooooooooooooooo                    
##  2     4 -------------------o-o-o           
##  3    13 ------------o-oooooooooo           
##  4    17 --++*++++++-++++++-+++-            
##  5   163 -o---o---o--o+----------           
##  6   210 -++++++++-+++-----------           
##  7   233 *+++++++++++o++++++++++o           
##  8   242 -----------------------            
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o
## 10  2089 ++++---+--------------o-

For example, participant 1 has a use pattern ooooooooooooooo (all missing UDS), which means that they dropped out of the study. In contrast, participant 233 has a use pattern *+++++++++++o++++++++++o (nearly all positive UDS): they did not drop out of the study, but the treatment was completely ineffective for them. Participant 2089 started the study in a rough patch, but greatly improved in treatment over time (++++---+--------------o-).



Abstinence from Substance Use Endpoints

Fiellin et al. (2006)

Definition: Weeks of confirmed opioid abstinence; missing is positive

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS,
        )
    ) %>% 
  # mixed results != abstinence
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = udsPattern,
            missing_is = "*"
        )
    ) %>% 
  # We did not code this definition with an "end", so participants with longer
  #   stays in treatment could have higher scores
    mutate(
        fiellin2006_abs = count_matches(
            use_pattern = udsPattern,
            match_is = "-"
        )
    ) %>% 
    select(who, fiellin2006_abs) %>% 
    left_join(outcomesAbs_df, ., by = "who")

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, fiellin2006_abs)
## # A tibble: 10 × 3
##      who usePatternUDS                       fiellin2006_abs
##    <dbl> <chr>                                         <int>
##  1     1 ooooooooooooooo                                   0
##  2     4 -------------------o-o-o                         21
##  3    13 ------------o-oooooooooo                         13
##  4    17 --++*++++++-++++++-+++-                           5
##  5   163 -o---o---o--o+----------                         19
##  6   210 -++++++++-+++-----------                         13
##  7   233 *+++++++++++o++++++++++o                          0
##  8   242 -----------------------                          23
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o              20
## 10  2089 ++++---+--------------o-                         18

Kosten et al. (1993)

Definition: attaining at least 3 weeks of consecutive negative UOS

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  mutate(
        kosten1993_isAbs = detect_subpattern(
            usePatternUDS,
            subpattern = "---" 
        )
    ) %>% 
    select(who, kosten1993_isAbs) %>% 
    left_join(outcomesAbs_df, ., by = "who")

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, kosten1993_isAbs)
## # A tibble: 10 × 3
##      who usePatternUDS                       kosten1993_isAbs
##    <dbl> <chr>                               <lgl>           
##  1     1 ooooooooooooooo                     FALSE           
##  2     4 -------------------o-o-o            TRUE            
##  3    13 ------------o-oooooooooo            TRUE            
##  4    17 --++*++++++-++++++-+++-             FALSE           
##  5   163 -o---o---o--o+----------            TRUE            
##  6   210 -++++++++-+++-----------            TRUE            
##  7   233 *+++++++++++o++++++++++o            FALSE           
##  8   242 -----------------------             TRUE            
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o TRUE            
## 10  2089 ++++---+--------------o-            TRUE

Krupitsky et al. (2011) (A) and (B)

There are two definitions from this paper which we include in the reduction section our library: Confirmed opioid abstinence during weeks 5‐24 based on UOS and Weeks of confirmed opioid abstinence.

Krupitsky et al., 2011 (A)

Definition: Confirmed opioid abstinence during weeks 5‐24 based on UOS

A comment on our algorithm: we do not know how long each protocol is exactly, so a pattern match approach (while intuitive at first) would not work. We will instead recode the use pattern as “negative” or “non-negative”, and then check that the proportion of non-negative UDS is 0%.

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS,
        )
    ) %>% 
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = udsPattern,
            missing_is = "*"
        )
    ) %>% 
    mutate(
        useProp = count_matches(
            use_pattern = udsPattern,
            match_is = "+",
            start = 5L,
            # Set this to the length of your protocol, or 24, whichever is shorter
            end = 15L,
            proportion = TRUE
        )
    ) %>% 
    mutate(krupitsky2011A_isAbs = useProp == 0) %>% 
    select(who, krupitsky2011A_isAbs) %>% 
    left_join(outcomesAbs_df, ., by = "who")

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, krupitsky2011A_isAbs)
## # A tibble: 10 × 3
##      who usePatternUDS                       krupitsky2011A_isAbs
##    <dbl> <chr>                               <lgl>               
##  1     1 ooooooooooooooo                     FALSE               
##  2     4 -------------------o-o-o            TRUE                
##  3    13 ------------o-oooooooooo            FALSE               
##  4    17 --++*++++++-++++++-+++-             FALSE               
##  5   163 -o---o---o--o+----------            FALSE               
##  6   210 -++++++++-+++-----------            FALSE               
##  7   233 *+++++++++++o++++++++++o            FALSE               
##  8   242 -----------------------             TRUE                
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o FALSE               
## 10  2089 ++++---+--------------o-            FALSE

Krupitsky et al., 2011 (B)

Definition: Weeks of confirmed opioid abstinence

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS,
        )
    ) %>% 
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = udsPattern,
            missing_is = "*"
        )
    ) %>% 
    mutate(
        krupitsky2011B_abs = count_matches(
            use_pattern = udsPattern,
            match_is = "-",
            start = 5L,
            # This trial protocol has a clear end date; we adjust it to our data
            end = 15L
        )
    ) %>% 
    select(who, krupitsky2011B_abs) %>% 
    left_join(outcomesAbs_df, ., by = "who")

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, krupitsky2011B_abs)
## # A tibble: 10 × 3
##      who usePatternUDS                       krupitsky2011B_abs
##    <dbl> <chr>                                            <int>
##  1     1 ooooooooooooooo                                      0
##  2     4 -------------------o-o-o                            11
##  3    13 ------------o-oooooooooo                             9
##  4    17 --++*++++++-++++++-+++-                              1
##  5   163 -o---o---o--o+----------                             7
##  6   210 -++++++++-+++-----------                             3
##  7   233 *+++++++++++o++++++++++o                             0
##  8   242 -----------------------                             11
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o                  6
## 10  2089 ++++---+--------------o-                            10

Ling et al. (1998)

Definition: % of participants who maintained 13 consecutive negative UOS (1 month); urine was screened 3 times per week

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  mutate(
        ling1998_isAbs = detect_subpattern(
            use_pattern = usePatternUDS,
            # 13 consecutive UDS at 3x per week is 4.3 weeks
            subpattern = "----"
        )
    ) %>% 
    select(who, ling1998_isAbs) %>% 
    left_join(outcomesAbs_df, ., by = "who")
  

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, ling1998_isAbs)
## # A tibble: 10 × 3
##      who usePatternUDS                       ling1998_isAbs
##    <dbl> <chr>                               <lgl>         
##  1     1 ooooooooooooooo                     FALSE         
##  2     4 -------------------o-o-o            TRUE          
##  3    13 ------------o-oooooooooo            TRUE          
##  4    17 --++*++++++-++++++-+++-             FALSE         
##  5   163 -o---o---o--o+----------            TRUE          
##  6   210 -++++++++-+++-----------            TRUE          
##  7   233 *+++++++++++o++++++++++o            FALSE         
##  8   242 -----------------------             TRUE          
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o TRUE          
## 10  2089 ++++---+--------------o-            TRUE

Lofwall et al. (2018)

Definition: No evidence of opioid use based on UOS (NOTE: minimal evidence of opioid use from UOS, not none)

In their paper, abstinence was defined as 2 of 3 negative UDS for weeks 9, 10, and 11; negative UDS in week 12; and 5 or 6 UDS negative during weeks 13-24 (with alternating week visits, yielding 6 visits in this Phase II period). Because we have 15 weeks of data guaranteed, we scale this window and lattice. Their definition of abstinence is quite complex. Because we only have 15 weeks of data for most subjects, we shift their 12-week Phase I endpoint to week 7, and treat weeks 8-15 as Phase II. Also, we calculate these as proportions and not counts; this is so that these rules can be applied to windows of other sizes. The proportions would be the same—only the window of observation would change.

Code
###  Define 15-week Lattice  ###
lofwallLattice_char <- collapse_lattice(
    lattice_patterns = c("o", "_o"),
    # For the lattice as defined over 24 weeks, you need 12 weeks of weekly visits
    #   and 6 sets of alternating "no visit" and "visit" week pairs, or c(12, 6).
    #   For us, we want 7 weeks straight of weekly visits followed by 4 pairs of
    #   alternating visits (8 weeks) for a total of 15 weeks.
    times = c(7, 4)
)
lofwallLattice_char
## [1] "ooooooo_o_o_o_o"
Code
###  Calculate Weighted Abstinence  ###
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  # Change mixed and missing results to positive
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS,
            missing_is = "*"
        )
    ) %>% 
  mutate(
    udsPattern = recode_missing_visits(udsPattern)
  ) %>% 
  # "observe" only the UDS that would have been caught by the protocol
    mutate(
        udsLattice = view_by_lattice(
            use_pattern = udsPattern,
            lattice_pattern = str_sub(lofwallLattice_char, end = 15) # first 15 weeks
        )
    ) %>% 
    # Impute the visits that were not "observed"
    mutate(
        udsLatticeLOCF = impute_missing_visits(
            use_pattern = udsLattice,
            method = "locf",
            missing_is = "_",
            quietly = TRUE
        )
    ) %>% 
  # Count for Weeks 5-7; Week 8; and Weeks 9-15
    mutate(
        prop57 = count_matches(
            udsLatticeLOCF,
            match_is = "-",
            start = 5L,
            end = 7L,
            proportion = TRUE
        ),
        clean8 = count_matches(
            udsLatticeLOCF,
            match_is = "-",
            start = 8L,
            end = 8L
        ),
        prop915 = count_matches(
            udsLatticeLOCF,
            match_is = "-",
            start = 9L,
            end = 15L,
            proportion = TRUE
        ),
    ) %>% 
  # Check interval counts/proportions
    mutate(
        lofwall2018_isAbs = (prop57 >= 2/3) & (clean8 == 1) & (prop915 >= 5/6)
    ) %>% 
    select(who, lofwall2018_isAbs) %>% 
    left_join(outcomesAbs_df, ., by = "who")

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, lofwall2018_isAbs)
## # A tibble: 10 × 3
##      who usePatternUDS                       lofwall2018_isAbs
##    <dbl> <chr>                               <lgl>            
##  1     1 ooooooooooooooo                     FALSE            
##  2     4 -------------------o-o-o            TRUE             
##  3    13 ------------o-oooooooooo            FALSE            
##  4    17 --++*++++++-++++++-+++-             FALSE            
##  5   163 -o---o---o--o+----------            FALSE            
##  6   210 -++++++++-+++-----------            FALSE            
##  7   233 *+++++++++++o++++++++++o            FALSE            
##  8   242 -----------------------             TRUE             
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o FALSE            
## 10  2089 ++++---+--------------o-            TRUE

Mokri et al. (2016)

Definition: Days to 1st positive UOS; missing is positive

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS
        )
    ) %>%
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = udsPattern,
            missing_is = "*"
        )
    ) %>%
  # Find the number of weeks until the first "+"
    mutate(
        mokri2016_abs = detect_in_window(
            use_pattern = udsPattern,
            window_width = 1L,
            threshold = 1L
        )
    ) %>%
    unnest(cols = "mokri2016_abs", names_sep = "_") %>%
    select(who, starts_with("mokri2016_abs")) %>%
    left_join(outcomesAbs_df, ., by = "who")
  
outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, starts_with("mokri2016_abs"))
## # A tibble: 10 × 4
##      who usePatternUDS                       mokri2016_abs_time mokri2016_abs_…¹
##    <dbl> <chr>                                            <int>            <int>
##  1     1 ooooooooooooooo                                      1                1
##  2     4 -------------------o-o-o                            20                1
##  3    13 ------------o-oooooooooo                            13                1
##  4    17 --++*++++++-++++++-+++-                              3                1
##  5   163 -o---o---o--o+----------                             2                1
##  6   210 -++++++++-+++-----------                             2                1
##  7   233 *+++++++++++o++++++++++o                             1                1
##  8   242 -----------------------                             23                0
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o                  1                1
## 10  2089 ++++---+--------------o-                             1                1
## # … with abbreviated variable name ¹​mokri2016_abs_event

If you are more comfortable using “survival” or “time-to-event” data structures, then the above definition can be modified by the following code:

Code
outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  mutate(
    mokri2016_wksAbst = survival::Surv(
      time = mokri2016_abs_time,
      event = mokri2016_abs_event
    )
  ) %>% 
  # FOR PRINTING THE TABLE ONLY. DO NOT USE NEXT LINE IN PRACTICE!!!
  mutate(mokri2016_wksAbst = as.character(mokri2016_wksAbst)) %>% 
  select(who, usePatternUDS, mokri2016_wksAbst)
## # A tibble: 10 × 3
##      who usePatternUDS                       mokri2016_wksAbst
##    <dbl> <chr>                               <chr>            
##  1     1 ooooooooooooooo                     " 1"             
##  2     4 -------------------o-o-o            "20"             
##  3    13 ------------o-oooooooooo            "13"             
##  4    17 --++*++++++-++++++-+++-             " 3"             
##  5   163 -o---o---o--o+----------            " 2"             
##  6   210 -++++++++-+++-----------            " 2"             
##  7   233 *+++++++++++o++++++++++o            " 1"             
##  8   242 -----------------------             "23+"            
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o " 1"             
## 10  2089 ++++---+--------------o-            " 1"

Richard S. Schottenfeld et al. (2005)

Definition: Max. number of consecutive weeks of negative UOS, missing is ignored

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  # Ignore missing visits
  mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS,
            missing_becomes = ""
        )
    ) %>% 
  # Mixed are positive
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = udsPattern,
            missing_is = "*"
        )
    ) %>% 
  # Measure the length of the longest period of continuous abstinence
    mutate(
        schottenfeld2005_abs = measure_abstinence_period(
            use_pattern_binary = udsPattern
        )
    ) %>% 
    select(who, schottenfeld2005_abs) %>% 
    left_join(outcomesAbs_df, ., by = "who")
  

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, schottenfeld2005_abs)
## # A tibble: 10 × 3
##      who usePatternUDS                       schottenfeld2005_abs
##    <dbl> <chr>                                              <int>
##  1     1 ooooooooooooooo                                        0
##  2     4 -------------------o-o-o                              21
##  3    13 ------------o-oooooooooo                              13
##  4    17 --++*++++++-++++++-+++-                                2
##  5   163 -o---o---o--o+----------                              10
##  6   210 -++++++++-+++-----------                              11
##  7   233 *+++++++++++o++++++++++o                               0
##  8   242 -----------------------                               23
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o                   14
## 10  2089 ++++---+--------------o-                              15

Richard S. Schottenfeld, Chawarski, and Mazlan (2008) (A) and (B)

There are two definitions from this paper which we include in the reduction section our library: Longest period of negative UOS and Days to 1st positive UOS after randomization.

Schottenfeld, Chawarski, & Mazlan, 2008 (A)

Definition: Days to 1st positive UOS after randomization, missing is positive

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS
        )
    ) %>% 
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = udsPattern,
            missing_is = "*"
        )
    ) %>% 
    mutate(
        schottenfeld2008A_abs = detect_in_window(
            use_pattern = udsPattern,
            window_width = 1L,
            threshold = 1L
        )
    ) %>% 
    unnest(cols = "schottenfeld2008A_abs", names_sep = "_") %>% 
    select(who, starts_with("schottenfeld2008A_abs")) %>% 
    left_join(outcomesAbs_df, ., by = "who")
  
outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, starts_with("schottenfeld2008A_abs"))
## # A tibble: 10 × 4
##      who usePatternUDS                       schottenfeld2008A_abs_time schott…¹
##    <dbl> <chr>                                                    <int>    <int>
##  1     1 ooooooooooooooo                                              1        1
##  2     4 -------------------o-o-o                                    20        1
##  3    13 ------------o-oooooooooo                                    13        1
##  4    17 --++*++++++-++++++-+++-                                      3        1
##  5   163 -o---o---o--o+----------                                     2        1
##  6   210 -++++++++-+++-----------                                     2        1
##  7   233 *+++++++++++o++++++++++o                                     1        1
##  8   242 -----------------------                                     23        0
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o                          1        1
## 10  2089 ++++---+--------------o-                                     1        1
## # … with abbreviated variable name ¹​schottenfeld2008A_abs_event

Schottenfeld et al., 2008 (B)

Definition: Longest period of negative UOS, missing is positive

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS
        )
    ) %>% 
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = udsPattern,
            missing_is = "*"
        )
    ) %>%
    mutate(
        schottenfeld2008B_abs = measure_abstinence_period(
            use_pattern_binary = udsPattern
        )
    ) %>% 
    select(who, schottenfeld2008B_abs) %>% 
    left_join(outcomesAbs_df, ., by = "who")
  

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, schottenfeld2008B_abs)
## # A tibble: 10 × 3
##      who usePatternUDS                       schottenfeld2008B_abs
##    <dbl> <chr>                                               <int>
##  1     1 ooooooooooooooo                                         0
##  2     4 -------------------o-o-o                               19
##  3    13 ------------o-oooooooooo                               12
##  4    17 --++*++++++-++++++-+++-                                 2
##  5   163 -o---o---o--o+----------                               10
##  6   210 -++++++++-+++-----------                               11
##  7   233 *+++++++++++o++++++++++o                                0
##  8   242 -----------------------                                23
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o                    10
## 10  2089 ++++---+--------------o-                               14

Shufman et al. (1994)

Definition: Weeks between 1st day of NTX administration and 1st positive UOS, missing is ignored (but treated as negative in order to count the weeks properly)

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  # Set "o" to "-"
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS,
            missing_becomes = "-"
        )
    ) %>% 
    # Set "*" to "+"
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = udsPattern,
            missing_is = "*"
        )
    ) %>% 
    mutate(
        shufman1994_absN = detect_in_window(
            use_pattern = udsPattern,
            window_width = 1L,
            threshold = 1L
        )
    ) %>% 
    unnest(cols = "shufman1994_absN", names_sep = "_") %>% 
    select(who, starts_with("shufman1994_absN")) %>% 
    left_join(outcomesAbs_df, ., by = "who")
  

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, starts_with("shufman1994_absN"))
## # A tibble: 10 × 4
##      who usePatternUDS                       shufman1994_absN_time shufman1994…¹
##    <dbl> <chr>                                               <int>         <int>
##  1     1 ooooooooooooooo                                        15             0
##  2     4 -------------------o-o-o                               24             0
##  3    13 ------------o-oooooooooo                               24             0
##  4    17 --++*++++++-++++++-+++-                                 3             1
##  5   163 -o---o---o--o+----------                               14             1
##  6   210 -++++++++-+++-----------                                2             1
##  7   233 *+++++++++++o++++++++++o                                1             1
##  8   242 -----------------------                                23             0
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o                     1             1
## 10  2089 ++++---+--------------o-                                1             1
## # … with abbreviated variable name ¹​shufman1994_absN_event

Weiss et al. (2011, CTN–0030)

Definition: Negative UOS during the last week AND for at least 2 of the previous 3 weeks of the third month of BUP/NX treatment, missing is positive.

Note: this definition is looking for one of the following four abstinence patterns in last 4 weeks: "----", "+---", "-+--", or "--+-". This definition is just an insanely strict measure of study retention. The first part of the definition (“negative in the last week”) already fails anyone who didn’t stay in the study for the entire protocol period (because their last week UDS will automatically be "o").

Code
outcomesAbs_df <- 
    outcomesAbs_df %>%
  rowwise() %>% 
  mutate(
        udsPattern = recode_missing_visits(
            use_pattern = usePatternUDS,
        )
    ) %>% 
    mutate(
        udsPattern = recode_missing_visits(
            use_pattern = udsPattern,
            missing_is = "*"
        )
    ) %>% 
    mutate(
        cleanLastWeek = detect_subpattern(
            use_pattern = udsPattern,
            subpattern = "-",
            start = -1,
            end = -1
        )
    ) %>% 
    mutate(
        finalUseCount = count_matches(
            use_pattern = udsPattern,
            match_is = "+",
            # 3 weeks leading up to the last week
            start = -4L,
            end = -2L
        )
    ) %>% 
    mutate(weissLingCTN0030_isAbs = cleanLastWeek & (finalUseCount <= 1)) %>% 
    select(who, weissLingCTN0030_isAbs) %>% 
    left_join(outcomesAbs_df, ., by = "who")
  

outcomesAbs_df %>% 
  filter(who %in% examplePeople_int) %>% 
  select(who, usePatternUDS, weissLingCTN0030_isAbs)
## # A tibble: 10 × 3
##      who usePatternUDS                       weissLingCTN0030_isAbs
##    <dbl> <chr>                               <lgl>                 
##  1     1 ooooooooooooooo                     FALSE                 
##  2     4 -------------------o-o-o            FALSE                 
##  3    13 ------------o-oooooooooo            FALSE                 
##  4    17 --++*++++++-++++++-+++-             FALSE                 
##  5   163 -o---o---o--o+----------            TRUE                  
##  6   210 -++++++++-+++-----------            TRUE                  
##  7   233 *+++++++++++o++++++++++o            FALSE                 
##  8   242 -----------------------             TRUE                  
##  9  1103 ++--oo--o-+-+--o----------o-o-oo++o FALSE                 
## 10  2089 ++++---+--------------o-            TRUE


Computing Environment

Here is the information concerning the system configuration, packages, and their versions used in this computation:

Code
sessionInfo()
## R version 4.2.0 (2022-04-22)
## Platform: x86_64-apple-darwin17.0 (64-bit)
## Running under: macOS Big Sur/Monterey 10.16
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/4.2/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
##  [1] forcats_0.5.1    stringr_1.4.0    dplyr_1.0.9      purrr_0.3.4     
##  [5] readr_2.1.2      tidyr_1.2.0      tibble_3.1.8     ggplot2_3.3.6   
##  [9] tidyverse_1.3.2  kableExtra_1.3.4 readxl_1.4.0     CTNote_0.1.0    
## 
## loaded via a namespace (and not attached):
##  [1] lattice_0.20-45     svglite_2.1.0       lubridate_1.8.0    
##  [4] assertthat_0.2.1    digest_0.6.29       utf8_1.2.2         
##  [7] R6_2.5.1            cellranger_1.1.0    backports_1.4.1    
## [10] reprex_2.0.1        evaluate_0.16       highr_0.9          
## [13] httr_1.4.3          pillar_1.8.0        rlang_1.0.4        
## [16] googlesheets4_1.0.0 rstudioapi_0.13     jquerylib_0.1.4    
## [19] Matrix_1.4-1        rmarkdown_2.14      splines_4.2.0      
## [22] webshot_0.5.3       googledrive_2.0.0   munsell_0.5.0      
## [25] broom_1.0.0         compiler_4.2.0      modelr_0.1.8       
## [28] xfun_0.32           pkgconfig_2.0.3     systemfonts_1.0.4  
## [31] htmltools_0.5.3     tidyselect_1.1.2    fansi_1.0.3        
## [34] viridisLite_0.4.0   crayon_1.5.1        withr_2.5.0        
## [37] tzdb_0.3.0          dbplyr_2.2.1        grid_4.2.0         
## [40] jsonlite_1.8.0      gtable_0.3.0        lifecycle_1.0.1    
## [43] DBI_1.1.3           magrittr_2.0.3      scales_1.2.0       
## [46] cli_3.3.0           stringi_1.7.8       cachem_1.0.6       
## [49] fs_1.5.2            xml2_1.3.3          bslib_0.4.0        
## [52] ellipsis_0.3.2      generics_0.1.3      vctrs_0.4.1        
## [55] tools_4.2.0         glue_1.6.2          hms_1.1.1          
## [58] survival_3.3-1      fastmap_1.1.0       yaml_2.3.5         
## [61] colorspace_2.0-3    gargle_1.2.0        rvest_1.0.2        
## [64] knitr_1.39          haven_2.5.0         sass_0.4.2

References

Fiellin, David A., Michael V. Pantalon, Marek C. Chawarski, Brent A. Moore, Lynn E. Sullivan, Patrick G. O’Connor, and Richard S. Schottenfeld. 2006. “Counseling Plus BuprenorphineNaloxone Maintenance Therapy for Opioid Dependence.” New England Journal of Medicine 355 (4): 365–74. https://doi.org/10.1056/NEJMoa055255.
Kosten, Thomas R., Richard Schottenfeld, Douglas Ziedonis, and Jean Falcioni. 1993. “Buprenorphine Versus Methadone Maintenance for Opioid Dependence.” The Journal of Nervous and Mental Disease 181 (6): 358–64. https://doi.org/10.1097/00005053-199306000-00004.
Krupitsky, Evgeny, Edward V Nunes, Walter Ling, Ari Illeperuma, David R Gastfriend, and Bernard L Silverman. 2011. “Injectable Extended-Release Naltrexone for Opioid Dependence: A Double-Blind, Placebo-Controlled, Multicentre Randomised Trial.” The Lancet 377 (9776): 1506–13. https://doi.org/10.1016/S0140-6736(11)60358-9.
Ling, Walter, Charles Charuvastra, Joseph F. Collins, Steve Batki, Lawrence S. Brown Jr, Prudencia Kintaudi, Donald R. Wesson, et al. 1998. “Buprenorphine Maintenance Treatment of Opiate Dependence: A Multicenter, Randomized Clinical Trial.” Addiction 93 (4): 475–86. https://doi.org/10.1046/j.1360-0443.1998.9344753.x.
Lofwall, Michelle R., Sharon L. Walsh, Edward V. Nunes, Genie L. Bailey, Stacey C. Sigmon, Kyle M. Kampman, Michael Frost, et al. 2018. “Weekly and Monthly Subcutaneous Buprenorphine Depot Formulations Vs Daily Sublingual Buprenorphine With Naloxone for Treatment of Opioid Use Disorder: A Randomized Clinical Trial.” Journal of the American Medical Association: Internal Medicine 178 (6): 764–73. https://doi.org/10.1001/jamainternmed.2018.1052.
Mokri, Azarakhsh, Marek C. Chawarski, Hamidreza Taherinakhost, and Richard S. Schottenfeld. 2016. “Medical Treatments for Opioid Use Disorder in Iran: A Randomized, Double-Blind Placebo-Controlled Comparison of Buprenorphine/Naloxone and Naltrexone Maintenance Treatment.” Addiction 111 (5): 874–82. https://doi.org/10.1111/add.13259.
Schottenfeld, Richard S., Marek C. Chawarski, Juliana R. Pakes, Michael V. Pantalon, Kathleen M. Carroll, and Thomas R. Kosten. 2005. “Methadone Versus Buprenorphine With Contingency Management or Performance Feedback for Cocaine and Opioid Dependence.” American Journal of Psychiatry 162 (2): 340–49. https://doi.org/10.1176/appi.ajp.162.2.340.
Schottenfeld, Richard S, Marek C Chawarski, and Mahmud Mazlan. 2008. “Maintenance Treatment with Buprenorphine and Naltrexone for Heroin Dependence in Malaysia: A Randomised, Double-Blind, Placebo-Controlled Trial.” The Lancet 371 (9631): 2192–2200. https://doi.org/10.1016/S0140-6736(08)60954-X.
Shufman, Emi N., Shai Porat, Eliezer Witztum, Dan Gandacu, Rachel Bar-Hamburger, and Yigal Ginath. 1994. “The Efficacy of Naltrexone in Preventing Reabuse of Heroin After Detoxification.” Biological Psychiatry 35 (12): 935–45. https://doi.org/10.1016/0006-3223(94)91240-8.
Weiss, Roger D., Jennifer Sharpe Potter, David A. Fiellin, Marilyn Byrne, Hilary S. Connery, William Dickinson, John Gardin, et al. 2011. “Adjunctive Counseling During Brief and Extended Buprenorphine-Naloxone Treatment for Prescription Opioid Dependence: A 2-Phase Randomized Controlled Trial.” Archives of General Psychiatry 68 (12): 1238–46. https://doi.org/10.1001/archgenpsychiatry.2011.121.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.