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.

[rossfarrugia]

@bms63 funny enough i had to implement something internally using this function for a BDS and i had an idea to extend the examples with the following scenario which i didn't find easy to figure out:

# check if a "non-event" occurs after a record for each parameter

Is it OK that I take this function examples update on? Or from the label are we leaving this open for new contributors from R/Pharma?

p.s. I don't ever agree with the suggestion of including SAS pseudo code in our R package function examples though. You can explain enough what you're doing in plain english comments, and up to certain users if they prefer to first translate that into SAS language for comparison. Imagine all our users who don't "speak SAS" who would only find this confusing.

[bms63]

Yes please take on!! Makes sense on not providing the SAS code :)

[yurovska]

Everyone "speaks every language" in the ChatGPT era.

Although, of course the SAS code should not be included in the R package :)

[rossfarrugia]

thanks both - will make a PR next week 🫡