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", "-")
)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.
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.
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).
Examples
# Find the first relapse event
detect_in_window("o-o+++")
#> time event
#> 1 4 1
# Find the start of the window that contains the first relapse event
detect_in_window("o-o+++", offset = 0)
#> time event
#> 1 3 1
# Find the first positive UDS
detect_in_window("o-o+++", window_width = 1L, threshold = 1L)
#> time event
#> 1 4 1