# Visit and Period Variables

# Introduction

The derivation of visit variables like `AVISIT`, `AVISITN`, `AWLO`, `AWHI`, … or period, subperiod, or phase variables like `APERIOD`, `TRT01A`, `TRT02A`, `ASPER`, `PHSDTM`, `PHEDTM`, … is highly study-specific. Therefore `{admiral}` cannot provide functions which derive these variables. However, for common scenarios like visit assignments based on time windows or deriving BDS period variables from ADSL period variables, functions are provided which support those derivations.

## Required Packages

The examples of this vignette require the following packages.

    library(admiral)
    library(tibble)
    library(dplyr, warn.conflicts = FALSE)
    library(lubridate)

# Visit variables (`AVISIT`, `AVISITN`, `AWLO`, `AWHI`, …)

The most common ways of deriving `AVISIT` and `AVISITN` are:

- The variables are set to the collected visits (`VISIT` and `VISITNUM`).
- The variables are set based on time windows.

The former can be achieved simply by calling `mutate()`, like in the vignettes and the template scripts.

For the latter a (study-specific) reference dataset needs to be created which provides for each visit the start and end day (`AWLO` and `AWHI`) and the values of other visit related variables (`AVISIT`, `AVISITN`, `AWTARGET`, …).

    windows <- tribble(
      ~AVISIT,    ~AWLO, ~AWHI, ~AVISITN, ~AWTARGET,
      "BASELINE",   -30,     1,        0,         1,
      "WEEK 1",       2,     7,        1,         5,
      "WEEK 2",       8,    15,        2,        11,
      "WEEK 3",      16,    22,        3,        19,
      "WEEK 4",      23,    30,        4,        26
    )

Then the visits can be assigned based on the analysis day (`ADY`) by calling `derive_vars_joined()`:

    adbds <- tribble(
      ~USUBJID, ~ADY,
      "1",       -33,
      "1",        -2,
      "1",         3,
      "1",        24,
      "2",        NA,
    )

    adbds1 <- adbds %>%
      derive_vars_joined(
        dataset_add = windows,
        filter_join = AWLO <= ADY & ADY <= AWHI,
        join_type = "all",
      )

USUBJID | ADY | AVISIT | AWLO | AWHI | AVISITN | AWTARGET
--- | --- | --- | --- | --- | --- | ---
1 | -33 | NA | NA | NA | NA | NA
1 | -2 | BASELINE | -30 | 1 | 0 | 1
1 | 3 | WEEK 1 | 2 | 7 | 1 | 5
1 | 24 | WEEK 4 | 23 | 30 | 4 | 26
2 | NA | NA | NA | NA | NA | NA

# Period, Subperiod, and Phase Variables

If periods, subperiods, or phases are used, in the simpler of ADaM applications the corresponding variables have to be consistent across all datasets. This can be achieved by defining the periods, subperiods, or phases once and then using this definition for all datasets. The definition can be stored in ADSL or in a separate dataset. In this vignette’s examples, this separate dataset is called period/phase reference dataset depending what data it contains.

Note that periods, subperiods, or phases can be defined differently across datasets (for instance, they may be different across safety and efficacy analyses) in which case the start/stop dates should be defined in the individual datasets, instead of in ADSL. However, this vignette will not cover this scenario.

## A Note on Study Specific Code

The sections below showcase the available tools in `{admiral}` to work with period, subperiod and phase variables. However, at some point study specific code will always be required. There are two options:

- Study specific code is used to first derive the variables `PxxSwSDT` and `PxxSwEDT` in ADSL. Then `create_period_dataset()` and `derive_vars_joined()` can be used to derive period/subperiod variables like `ASPER` or `ASPRSDT` in BDS and OCCDS datasets. See an example dataset here.

- Study specific code is used to derive a dataset with one observation per patient, period, and subperiod (see period reference dataset). Then `derive_vars_period()` can be used to derive `PxxSwSDT` and `PxxSwEDT` in ADSL and `derive_vars_joined()` can be used to derive period/subperiod variables like `ASPER` or `ASPRSDT` in BDS and OCCDS datasets.

It depends on the specific definition of the periods/subperiods which option works best. If the definition is based on other ADSL variables, the first option would work best. If the definition is based on vertically structured data like exposure data (EX dataset), the second option should be used. This vignette contains examples for both workflows.

## The Period/Phase Reference Dataset

The `{admiral}` functions expect separate reference datasets for periods, subperiods, and phases. For periods the numeric variable `APERIOD` is expected, for subperiods the numeric variables `APERIOD` and `ASPER`, and for phases the numeric variable `APHASEN`.

The period/phase reference dataset should be created according to the design and ADaM needs of the study in question. It should contain one observation per subject and period, subperiod, or phase. See the next section for an example dataset.

## Example Creation of the Period/Phase Reference Dataset

Consider a simple crossover study with the following design:

Given this design, an option could be to split the study into two periods:

- Period 1 (Day 1 to Week 16);
- Period 2 (Week 16 to End of Study).

Alternatively (or additionally) one could split into two phases:

- Phase 1 - Treatment (Day 1 to 28 days after Week 28);
- Phase 2 - Follow-up (29 days after Week 28 to End of Study).

Below, we present two example workflows: one where where a period reference dataset is created from the exposure dataset EX, and the other where a phase reference dataset is created using ADSL variables.

### Creating the Period/Phase Reference Dataset from EX

Below we create a period reference dataset starting from the exposure dataset EX. Consider the following exposure dataset:

    ex <- tribble(
      ~STUDYID, ~USUBJID,  ~VISIT,    ~EXTRT,   ~EXSTDTC,
      "xyz",    "1",       "Day 1",   "Drug X", "2022-01-02",
      "xyz",    "1",       "Week 4",  "Drug X", "2022-02-05",
      "xyz",    "1",       "Week 8",  "Drug X", "2022-03-01",
      "xyz",    "1",       "Week 12", "Drug X", "2022-04-03",
      "xyz",    "1",       "Week 16", "Drug Y", "2022-05-03",
      "xyz",    "1",       "Week 20", "Drug Y", "2022-06-02",
      "xyz",    "1",       "Week 24", "Drug Y", "2022-07-01",
      "xyz",    "1",       "Week 28", "Drug Y", "2022-08-04",
      "xyz",    "2",       "Day 1",   "Drug Y", "2023-10-20",
      "xyz",    "2",       "Week 4",  "Drug Y", "2023-11-21",
      "xyz",    "2",       "Week 8",  "Drug Y", "2023-12-19",
      "xyz",    "2",       "Week 12", "Drug Y", "2024-01-19",
      "xyz",    "2",       "Week 16", "Drug X", "2024-02-20",
      "xyz",    "2",       "Week 20", "Drug X", "2024-03-17",
      "xyz",    "2",       "Week 24", "Drug X", "2024-04-22",
      "xyz",    "2",       "Week 28", "Drug X", "2024-05-21"
    )

Then to create a period reference dataset, code like this (or similar) would suffice:

    period_ref <- ex %>%
      # Select visits marking the start of each period
      filter(VISIT %in% c("Day 1", "Week 16")) %>%
      # Create APERIOD, APERSDT, TRTA based on SDTM counterparts
      mutate(
        APERIOD = case_when(
          VISIT == "Day 1" ~ 1,
          VISIT == "Week 16" ~ 2
        ),
        TRTA = EXTRT,
        APERSDT = convert_dtc_to_dt(EXSTDTC)
      ) %>%
      # Create APEREDT based on start date of next period
      arrange(USUBJID, APERSDT) %>%
      group_by(USUBJID) %>%
      mutate(
        APEREDT = lead(APERSDT) - 1 # one day before start of next period
      ) %>%
      # Tidy up
      ungroup() %>%
      select(-starts_with("EX"), -VISIT)

STUDYID | USUBJID | APERIOD | TRTA | APERSDT | APEREDT
--- | --- | --- | --- | --- | ---
xyz | 1 | 1 | Drug X | 2022-01-02 | 2022-05-02
xyz | 1 | 2 | Drug Y | 2022-05-03 | NA
xyz | 2 | 1 | Drug Y | 2023-10-20 | 2024-02-19
xyz | 2 | 2 | Drug X | 2024-02-20 | NA

The workflow above populates the Period End Date `APEREDT` for all periods except the last one. The value of the last period could then be populated with the End of Study Date (`EOSDT`) from ADSL, to obtain:

    adsl <- tribble(
      ~STUDYID,  ~USUBJID,  ~TRTSDT,           ~TRTEDT,           ~EOSDT,
      "xyz",     "1",       ymd("2022-01-02"), ymd("2022-08-04"), ymd("2022-09-10"),
      "xyz",     "2",       ymd("2023-10-20"), ymd("2024-05-21"), ymd("2024-06-30")
    )

    period_ref <- period_ref %>%
      left_join(adsl, by = c("STUDYID", "USUBJID")) %>%
      mutate(APEREDT = case_when(
        APERIOD == "1" ~ APEREDT,
        APERIOD == "2" ~ EOSDT
      )) %>%
      select(-EOSDT, -TRTSDT, -TRTEDT)

STUDYID | USUBJID | APERIOD | TRTA | APERSDT | APEREDT
--- | --- | --- | --- | --- | ---
xyz | 1 | 1 | Drug X | 2022-01-02 | 2022-05-02
xyz | 1 | 2 | Drug Y | 2022-05-03 | 2022-09-10
xyz | 2 | 1 | Drug Y | 2023-10-20 | 2024-02-19
xyz | 2 | 2 | Drug X | 2024-02-20 | 2024-06-30

### Creating the Period/Phase Reference Dataset from ADSL

If the treatment start and end dates are already included in ADSL, we can derive the phase variables directly in ADSL and create a phase reference dataset by employing `create_period_dataset()`. Here is an example command to achieve this goal:

    adsl1 <- adsl %>%
      mutate(
        PH1SDT = TRTSDT,
        PH1EDT = TRTEDT + 28,
        APHASE1 = "TREATMENT",
        PH2SDT = TRTEDT + 29,
        PH2EDT = EOSDT,
        APHASE2 = "FUP"
      )

    phase_ref <- create_period_dataset(
      adsl1,
      new_vars = exprs(PHSDT = PHwSDT, PHEDT = PHwEDT, APHASE = APHASEw)
    )

STUDYID | USUBJID | APHASEN | PHSDT | PHEDT | APHASE
--- | --- | --- | --- | --- | ---
xyz | 1 | 1 | 2022-01-02 | 2022-09-01 | TREATMENT
xyz | 1 | 2 | 2022-09-02 | 2022-09-10 | FUP
xyz | 2 | 1 | 2023-10-20 | 2024-06-18 | TREATMENT
xyz | 2 | 2 | 2024-06-19 | 2024-06-30 | FUP

## Creating ADSL Period, Subperiod, or Phase Variables

If a period/phase reference dataset is available, the ADSL variables for periods, subperiods, or phases can be created from this dataset by calling `derive_vars_period()`.

For example the period reference dataset from the previous section can be used to add the period variables (`APxxSDT`, `APxxEDT`) to ADSL:

    adsl2 <- derive_vars_period(
      adsl,
      dataset_ref = period_ref,
      new_vars = exprs(APxxSDT = APERSDT, APxxEDT = APEREDT)
    )

STUDYID | USUBJID | AP01SDT | AP01EDT | AP02SDT | AP02EDT
--- | --- | --- | --- | --- | ---
xyz | 1 | 2022-01-02 | 2022-05-02 | 2022-05-03 | 2022-09-10
xyz | 2 | 2023-10-20 | 2024-02-19 | 2024-02-20 | 2024-06-30

## Creating BDS and OCCDS Period, Subperiod, or Phase Variables

If a period/phase reference dataset is available, BDS and OCCDS variables for periods, subperiods, or phases can be created by calling `derive_vars_joined()`.

For example the variables `APHASEN`, `PHSDT`, `PHEDT`, `APHASE` can be derived from the phase reference dataset defined above.

    adae <- tribble(
      ~STUDYID, ~USUBJID, ~ASTDT,
      "xyz",    "1",      "2022-01-31",
      "xyz",    "1",      "2022-05-02",
      "xyz",    "1",      "2022-09-03",
      "xyz",    "1",      "2022-09-09",
      "xyz",    "2",      "2023-12-25",
      "xyz",    "2",      "2024-06-19",
    ) %>%
      mutate(ASTDT = ymd(ASTDT))

    adae1 <- adae %>%
      derive_vars_joined(
        dataset_add = phase_ref,
        by_vars = exprs(STUDYID, USUBJID),
        filter_join = PHSDT <= ASTDT & ASTDT <= PHEDT,
        join_type = "all"
      )

STUDYID | USUBJID | ASTDT | APHASEN | PHSDT | PHEDT | APHASE
--- | --- | --- | --- | --- | --- | ---
xyz | 1 | 2022-01-31 | 1 | 2022-01-02 | 2022-09-01 | TREATMENT
xyz | 1 | 2022-05-02 | 1 | 2022-01-02 | 2022-09-01 | TREATMENT
xyz | 1 | 2022-09-03 | 2 | 2022-09-02 | 2022-09-10 | FUP
xyz | 1 | 2022-09-09 | 2 | 2022-09-02 | 2022-09-10 | FUP
xyz | 2 | 2023-12-25 | 1 | 2023-10-20 | 2024-06-18 | TREATMENT
xyz | 2 | 2024-06-19 | 2 | 2024-06-19 | 2024-06-30 | FUP

# Treatment Variables (`TRTxxP`, `TRTxxA`, `TRTP`, `TRTA`, …)

In studies with multiple periods the treatment can differ by period, e.g. for a crossover trial - see the previous section for an example design showcasing this. CDISC defines variables for planned and actual treatments in ADSL (`TRTxxP`, `TRTxxA`, `TRxxPGy`, `TRxxAGy`, …) and corresponding variables in BDS and OCCDS datasets (`TRTP`, `TRTA`, `TRTPGy`, `TRTAGy`, …). They can be derived in the same way (and same step) as the period, subperiod, and phase variables.

## Creating ADSL Treatment Variables

If the treatment information is included in the period/phase reference dataset, the treatment ADSL variables can be created by calling `derive_vars_period()`. This is showcased below using the period reference dataset from previous sections.

    adsl <- derive_vars_period(
      adsl,
      dataset_ref = period_ref,
      new_vars = exprs(
        APxxSDT = APERSDT,
        APxxEDT = APEREDT,
        TRTxxA = TRTA
      )
    )

STUDYID | USUBJID | TRT01A | TRT02A | AP01SDT | AP01EDT | AP02SDT | AP02EDT
--- | --- | --- | --- | --- | --- | --- | ---
xyz | 1 | Drug X | Drug Y | 2022-01-02 | 2022-05-02 | 2022-05-03 | 2022-09-10
xyz | 2 | Drug Y | Drug X | 2023-10-20 | 2024-02-19 | 2024-02-20 | 2024-06-30

## Creating BDS and OCCDS Treatment Variables

If a period/phase reference dataset is available, BDS and OCCDS variables for treatment can be created by calling `derive_vars_joined()`.

For example the variables `APERIOD` and `TRTA` can be derived from the period reference dataset defined above.

    adae <- tribble(
      ~STUDYID, ~USUBJID, ~ASTDT,
      "xyz",    "1",      "2022-01-31",
      "xyz",    "1",      "2022-05-02",
      "xyz",    "1",      "2022-08-24",
      "xyz",    "1",      "2022-09-09",
      "xyz",    "2",      "2023-12-25",
      "xyz",    "2",      "2024-06-07",
    ) %>%
      mutate(ASTDT = ymd(ASTDT))

    adae2 <- adae %>%
      derive_vars_joined(
        dataset_add = period_ref,
        by_vars = exprs(STUDYID, USUBJID),
        new_vars = exprs(APERIOD, TRTA),
        join_vars = exprs(APERSDT, APEREDT),
        join_type = "all",
        filter_join = APERSDT <= ASTDT & ASTDT <= APEREDT
      )

STUDYID | USUBJID | ASTDT | APERIOD | TRTA
--- | --- | --- | --- | ---
xyz | 1 | 2022-01-31 | 1 | Drug X
xyz | 1 | 2022-05-02 | 1 | Drug X
xyz | 1 | 2022-08-24 | 2 | Drug Y
xyz | 1 | 2022-09-09 | 2 | Drug Y
xyz | 2 | 2023-12-25 | 1 | Drug Y
xyz | 2 | 2024-06-07 | 2 | Drug X

If no period/phase reference dataset is available but period/phase variables are in ADSL, then the former can again be created from ADSL by calling `create_period_dataset()`, as was showcased here.

This time, when calling `create_period_dataset()` we just need to make sure we include `TRTA = TRTxxA` as part of the `new_vars` argument to create the treatment variables as well.

    period_ref1 <- adsl %>%
      create_period_dataset(
        new_vars = exprs(APERSDT = APxxSDT, APEREDT = APxxEDT, TRTA = TRTxxA)
      )

STUDYID | USUBJID | APERIOD | APERSDT | APEREDT | TRTA
--- | --- | --- | --- | --- | ---
xyz | 1 | 1 | 2022-01-02 | 2022-05-02 | Drug X
xyz | 1 | 2 | 2022-05-03 | 2022-09-10 | Drug Y
xyz | 2 | 1 | 2023-10-20 | 2024-02-19 | Drug Y
xyz | 2 | 2 | 2024-02-20 | 2024-06-30 | Drug X