Documentation: Enhance documentation for derive_var_joined_exist_flag()

[bms63]

Background

derive_var_joined_exist_flag() can be a challenging function to use - more simple examples will help show its power and ease of use. The example below is a nice showcase. The SAS code can be included as that is our user base (for now!) to bring in more understanding.

library(tibble)

ex <- tribble(
  ~STUDYID, ~USUBJID, ~EXDOSE, ~EXSTDTM,
  
  "STUDY001", "SUBJ001", 2, "2024-01-01T08:00",
  "STUDY001", "SUBJ001", 4, "2024-01-02T08:00",
  
  "STUDY001", "SUBJ002", 2, "2024-01-01T08:30",
  "STUDY001", "SUBJ002", 4, "2024-01-02T08:30",
  "STUDY001", "SUBJ002", 2, "2024-01-03T08:30",   # Down-titration
  "STUDY001", "SUBJ002", 2, "2024-01-04T08:30",
  
  "STUDY001", "SUBJ003", 2, "2024-01-01T09:00",
  "STUDY001", "SUBJ003", 4, "2024-01-03T09:00",
  "STUDY001", "SUBJ003", 4, "2024-01-04T09:00",
  "STUDY001", "SUBJ003", 8, "2024-01-05T09:00",
  "STUDY001", "SUBJ003", 4, "2024-01-06T09:00",   # Down-titration
  
  "STUDY001", "SUBJ004", 2, "2024-01-01T10:00",
  "STUDY001", "SUBJ004", 4, "2024-01-02T10:00",
  "STUDY001", "SUBJ004", 4, "2024-01-03T10:00"
)

ex_flag <- ex %>%
  # Flag each EXDOSE which is lower than previous per patient
  derive_var_joined_exist_flag(
    dataset_add = ex,
    by_vars = exprs(STUDYID, USUBJID),
    order = exprs(EXSTDTM),
    new_var = DOSE_REDUCED,
    tmp_obs_nr_var = tmp_dose_nr,
    join_vars = exprs(EXDOSE),
    join_type = "before",
    first_cond_lower = NULL,
    first_cond_upper = NULL,
    filter_add = NULL,
    filter_join = (
      tmp_dose_nr == tmp_dose_nr.join + 1   # Look only at adjacent doses (i.e. next to each other)
      & EXDOSE > 0 & EXDOSE.join > 0        # Both doses are valid
      & EXDOSE < EXDOSE.join                # Dose is lower than previous
    )
  )

data ex_flag (drop = prev_dose);
    set ex;
    by USUBJID EXSTDTM;
    
    if first.USUBJID then call missing(prev_dose);
    else prev_dose = lag(EXDOSE);
    
    if 0 < EXDOSE < prev_dose < 0 then DOSE_REDUCED = "Y";
run;

Originally posted by @yurovska in pharmaverse/admiralmetabolic#31 (comment)

Definition of Done

• Documentation for this function is updated with this example.
• SAS pseudo Code is also provided in example
• The arguments with NULL can be removed to increase brevity.