detect_in_window {CTNote} | R Documentation |
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", "-")
)
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 |
match_is |
What constitutes the outcome of interest? |
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)