# Disposition Table

    library(metalite.sl)
    library(metalite)
    library(dplyr)

# Create Disposition Table

The objective of this tutorial is to generate a production-ready Disposition table specification analyses.

This report produces a table that contains counts and percentage of disposition for the participants in population for overall study. To accomplish this using metalite.sl, four essential functions are required:

- `prepare_disposition ()`:subset data for disposition analysis.

- `format_disposition()`: prepare analysis outdata with proper format.

- `rtf_disposition ()`: transfer output dataset to RTF table.

An example output:

## Example data

Within metalite.sl, we utilized the ADSL datasets from the metalite package to create an illustrative dataset. The metadata structure remains consistent across all analysis examples within metalite.sl. Additional information can be accessed on the metalite package website.

## Build a metadata

    adsl <- r2rtf::r2rtf_adsl
    adsl$TRTA <- adsl$TRT01A
    adsl$TRTA <- factor(adsl$TRTA,
      levels = c("Placebo", "Xanomeline Low Dose", "Xanomeline High Dose"),
      labels = c("Placebo", "Low Dose", "High Dose")
    )

    # Create a variable EOSSTT indicating the end of end of study status
    adsl$EOSSTT <- sample(
      x = c("Participants Ongoing", "Discontinued"),
      size = length(adsl$USUBJID),
      prob = c(0.8, 0.2), replace = TRUE
    )
    adsl[adsl[["EOSSTT"]] == "Discontinued", "DCSREAS"] <- sample(
      x = c("Adverse Event", "I/E Not Met", "Withdrew Consent", "Lack of Efficacy"),
      size = length(adsl[adsl[["EOSSTT"]] == "Discontinued", "USUBJID"]),
      prob = c(0.7, 0.1, 0.1, 0.1), replace = TRUE
    )

    # Create a variable EOTSTT1 indicating the end of treatment status part 1
    adsl$EOTSTT1 <- ifelse(adsl$DISCONFL == "Y", "Discontinued", "Completed")
    adsl$DCTREAS <- ifelse(adsl$EOTSTT1 == "Discontinued", adsl$DCREASCD, NA)
    head(adsl)
    #>        STUDYID     USUBJID SUBJID SITEID SITEGR1                  ARM
    #> 1 CDISCPILOT01 01-701-1015   1015    701     701              Placebo
    #> 2 CDISCPILOT01 01-701-1023   1023    701     701              Placebo
    #> 3 CDISCPILOT01 01-701-1028   1028    701     701 Xanomeline High Dose
    #> 4 CDISCPILOT01 01-701-1033   1033    701     701  Xanomeline Low Dose
    #> 5 CDISCPILOT01 01-701-1034   1034    701     701 Xanomeline High Dose
    #> 6 CDISCPILOT01 01-701-1047   1047    701     701              Placebo
    #>                 TRT01P TRT01PN               TRT01A TRT01AN     TRTSDT
    #> 1              Placebo       0              Placebo       0 2014-01-02
    #> 2              Placebo       0              Placebo       0 2012-08-05
    #> 3 Xanomeline High Dose      81 Xanomeline High Dose      81 2013-07-19
    #> 4  Xanomeline Low Dose      54  Xanomeline Low Dose      54 2014-03-18
    #> 5 Xanomeline High Dose      81 Xanomeline High Dose      81 2014-07-01
    #> 6              Placebo       0              Placebo       0 2013-02-12
    #>       TRTEDT TRTDUR AVGDD CUMDOSE AGE AGEGR1 AGEGR1N  AGEU  RACE RACEN SEX
    #> 1 2014-07-02    182   0.0       0  63    <65       1 YEARS WHITE     1   F
    #> 2 2012-09-01     28   0.0       0  64    <65       1 YEARS WHITE     1   M
    #> 3 2014-01-14    180  77.7   13986  71  65-80       2 YEARS WHITE     1   M
    #> 4 2014-03-31     14  54.0     756  74  65-80       2 YEARS WHITE     1   M
    #> 5 2014-12-30    183  76.9   14067  77  65-80       2 YEARS WHITE     1   F
    #> 6 2013-03-09     26   0.0       0  85    >80       3 YEARS WHITE     1   F
    #>                   ETHNIC SAFFL ITTFL EFFFL COMP8FL COMP16FL COMP24FL DISCONFL
    #> 1     HISPANIC OR LATINO     Y     Y     Y       Y        Y        Y
    #> 2     HISPANIC OR LATINO     Y     Y     Y       N        N        N        Y
    #> 3 NOT HISPANIC OR LATINO     Y     Y     Y       Y        Y        Y
    #> 4 NOT HISPANIC OR LATINO     Y     Y     Y       N        N        N        Y
    #> 5 NOT HISPANIC OR LATINO     Y     Y     Y       Y        Y        Y
    #> 6 NOT HISPANIC OR LATINO     Y     Y     Y       N        N        N        Y
    #>   DSRAEFL DTHFL BMIBL BMIBLGR1 HEIGHTBL WEIGHTBL EDUCLVL   DISONSDT DURDIS
    #> 1                25.1   25-<30    147.3     54.4      16 2010-04-30   43.9
    #> 2       Y        30.4     >=30    162.6     80.3      14 2006-03-11   76.4
    #> 3                31.4     >=30    177.8     99.3      16 2009-12-16   42.8
    #> 4                28.8   25-<30    175.3     88.5      12 2009-08-02   55.3
    #> 5                26.1   25-<30    154.9     62.6       9 2011-09-29   32.9
    #> 6       Y        30.4     >=30    148.6     67.1       8 2009-07-26   42.0
    #>   DURDSGR1   VISIT1DT    RFSTDTC    RFENDTC VISNUMEN     RFENDT
    #> 1     >=12 2013-12-26 2014-01-02 2014-07-02       12 2014-07-02
    #> 2     >=12 2012-07-22 2012-08-05 2012-09-02        5 2012-09-02
    #> 3     >=12 2013-07-11 2013-07-19 2014-01-14       12 2014-01-14
    #> 4     >=12 2014-03-10 2014-03-18 2014-04-14        5 2014-04-14
    #> 5     >=12 2014-06-24 2014-07-01 2014-12-30       12 2014-12-30
    #> 6     >=12 2013-01-22 2013-02-12 2013-03-29        6 2013-03-29
    #>                       DCDECOD         DCREASCD MMSETOT      TRTA
    #> 1                   COMPLETED        Completed      23   Placebo
    #> 2               ADVERSE EVENT    Adverse Event      23   Placebo
    #> 3                   COMPLETED        Completed      23 High Dose
    #> 4 STUDY TERMINATED BY SPONSOR Sponsor Decision      23  Low Dose
    #> 5                   COMPLETED        Completed      21 High Dose
    #> 6               ADVERSE EVENT    Adverse Event      23   Placebo
    #>                 EOSSTT          DCSREAS      EOTSTT1          DCTREAS
    #> 1 Participants Ongoing             <NA>    Completed             <NA>
    #> 2 Participants Ongoing             <NA> Discontinued    Adverse Event
    #> 3 Participants Ongoing             <NA>    Completed             <NA>
    #> 4 Participants Ongoing             <NA> Discontinued Sponsor Decision
    #> 5 Participants Ongoing             <NA>    Completed             <NA>
    #> 6         Discontinued Lack of Efficacy Discontinued    Adverse Event

    plan <- plan(
      analysis = "disp", population = "apat",
      observation = "apat", parameter = "disposition;medical-disposition"
    )

    meta <- meta_adam(
      population = adsl,
      observation = adsl
    ) |>
      define_plan(plan = plan) |>
      define_population(
        name = "apat",
        group = "TRTA",
        subset = quote(SAFFL == "Y")
      ) |>
      define_parameter(
        name = "disposition",
        var = "EOSSTT",
        label = "Trial Disposition",
        var_lower = "DCSREAS"
      ) |>
      define_parameter(
        name = "medical-disposition",
        var = "EOTSTT1",
        label = "Participant Study Medication Disposition",
        var_lower = "DCTREAS"
      ) |>
      define_analysis(
        name = "disp",
        title = "Disposition of Participant",
        label = "disposition table"
      ) |>
      meta_build()

Click to show the output

    meta
    #> ADaM metadata:
    #>    .$data_population     Population data with 254 subjects
    #>    .$data_observation    Observation data with 254 records
    #>    .$plan    Analysis plan with 1 plans
    #>
    #>
    #>   Analysis population type:
    #>     name        id  group var       subset                         label
    #> 1 'apat' 'USUBJID' 'TRTA'     SAFFL == 'Y' 'All Participants as Treated'
    #>
    #>
    #>   Analysis observation type:
    #>     name        id  group var subset                         label
    #> 1 'apat' 'USUBJID' 'TRTA'            'All Participants as Treated'
    #>
    #>
    #>   Analysis parameter type:
    #>                    name                                      label subset
    #> 1         'disposition'                        'Trial Disposition'
    #> 2 'medical-disposition' 'Participant Study Medication Disposition'
    #>
    #>
    #>   Analysis function:
    #>     name               label
    #> 1 'disp' 'disposition table'

## Analysis preparation

The function `prepare_disposition()` is written to prepare data for subject disposition analysis.The function takes four arguments:

Meta is metadata object created by metalite and it contains data from ADSL. Analysis, Population, and Parameter arguments are used to subset and process the meta data. They have default values, which rely on the meta data object.

The function assign default value Analysis to `prepare_disposition`, Population to the population value associated with the `prepare_disposition` analysis in meta plan, and parameter to the parameter(s) associated with the `prepare_disposition` analysis in meta$plan.

However, the user can also manually specify the analysis, population, and parameter values when calling the function, if they want to override the default values.

In the body of the function, it calls another function `prepare_sl_summary` with the same meta, analysis, population, and parameter arguments. `prepare_sl_summary` takes the meta data, subsets it based on the analysis, population, and parameter values, and then calculates and returns a summary of the relevant data.

The result of `prepare_sl_summary` is then returned as the result of `prepare_disposition`.

The resulting output of the function `prepare_disposition()` comprises a collection of raw datasets for analysis and reporting.

    outdata <- prepare_disposition(meta)

Click to show the output

    outdata
    #> List of 14
    #>  $ meta           :List of 7
    #>  $ population     : chr "apat"
    #>  $ observation    : chr "apat"
    #>  $ parameter      : chr "disposition;medical-disposition"
    #>  $ n              :'data.frame': 1 obs. of  6 variables:
    #>  $ order          : NULL
    #>  $ group          : chr "TRTA"
    #>  $ reference_group: NULL
    #>  $ char_n         :List of 2
    #>  $ char_var       : chr [1:2] "EOSSTT" "EOTSTT1"
    #>  $ char_prop      :List of 2
    #>  $ var_type       :List of 2
    #>  $ group_label    : Factor w/ 3 levels "Placebo","Low Dose",..: 1 3 2
    #>  $ analysis       : chr "disp"

- `parameter`: parameter name

    outdata$parameter
    #> [1] "disposition;medical-disposition"

- `n`: number of participants in population

    outdata$n
    #>                         name n_1 n_2 n_3 n_9999 var_label
    #> 1 Participants in population  86  84  84    254     -----

The resulting dataset contains frequently used statistics, with variables indexed according to the order specified in `outdata$group`.

    outdata$group
    #> [1] "TRTA"

- `char_n`: number of participants completed vs not completed in each parameter

    outdata$char_n
    #> [[1]]
    #>                   name Placebo Low Dose High Dose Total         var_label
    #> 1         Discontinued      14       16        19    49 Trial Disposition
    #> 2        Adverse Event      10       11        12    33 Trial Disposition
    #> 3          I/E Not Met       1        4         2     7 Trial Disposition
    #> 4     Lack of Efficacy       2        1         2     5 Trial Disposition
    #> 5     Withdrew Consent       1        0         3     4 Trial Disposition
    #> 6 Participants Ongoing      72       68        65   205 Trial Disposition
    #>
    #> [[2]]
    #>                      name Placebo Low Dose High Dose Total
    #> 1               Completed      58       25        27   110
    #> 2            Discontinued      28       59        57   144
    #> 3           Adverse Event       8       44        40    92
    #> 4                   Death       2        1         0     3
    #> 5             I/E Not Met       1        0         2     3
    #> 6        Lack of Efficacy       3        0         1     4
    #> 7       Lost to Follow-up       1        1         0     2
    #> 8      Physician Decision       1        0         2     3
    #> 9      Protocol Violation       1        1         1     3
    #> 10       Sponsor Decision       2        2         3     7
    #> 11       Withdrew Consent       9       10         8    27
    #>                                   var_label
    #> 1  Participant Study Medication Disposition
    #> 2  Participant Study Medication Disposition
    #> 3  Participant Study Medication Disposition
    #> 4  Participant Study Medication Disposition
    #> 5  Participant Study Medication Disposition
    #> 6  Participant Study Medication Disposition
    #> 7  Participant Study Medication Disposition
    #> 8  Participant Study Medication Disposition
    #> 9  Participant Study Medication Disposition
    #> 10 Participant Study Medication Disposition
    #> 11 Participant Study Medication Disposition

- `char_var` : name of parameter

    outdata$char_var
    #> [1] "EOSSTT"  "EOTSTT1"

- `char_prop` : proportion of subject with disposition

    outdata$char_prop
    #> [[1]]
    #>                   name          Placebo         Low Dose        High Dose
    #> 1         Discontinued         16.27907         19.04762         22.61905
    #> 2        Adverse Event 11.6279069767442 13.0952380952381 14.2857142857143
    #> 3          I/E Not Met 1.16279069767442 4.76190476190476 2.38095238095238
    #> 4     Lack of Efficacy 2.32558139534884 1.19047619047619 2.38095238095238
    #> 5     Withdrew Consent 1.16279069767442                0 3.57142857142857
    #> 6 Participants Ongoing         83.72093         80.95238         77.38095
    #>              Total         var_label
    #> 1         19.29134 Trial Disposition
    #> 2  12.992125984252 Trial Disposition
    #> 3 2.75590551181102 Trial Disposition
    #> 4 1.96850393700787 Trial Disposition
    #> 5  1.5748031496063 Trial Disposition
    #> 6         80.70866 Trial Disposition
    #>
    #> [[2]]
    #>                      name          Placebo         Low Dose        High Dose
    #> 1               Completed         67.44186          29.7619         32.14286
    #> 2            Discontinued         32.55814          70.2381         67.85714
    #> 3           Adverse Event 9.30232558139535 52.3809523809524 47.6190476190476
    #> 4                   Death 2.32558139534884 1.19047619047619                0
    #> 5             I/E Not Met 1.16279069767442                0 2.38095238095238
    #> 6        Lack of Efficacy 3.48837209302326                0 1.19047619047619
    #> 7       Lost to Follow-up 1.16279069767442 1.19047619047619                0
    #> 8      Physician Decision 1.16279069767442                0 2.38095238095238
    #> 9      Protocol Violation 1.16279069767442 1.19047619047619 1.19047619047619
    #> 10       Sponsor Decision 2.32558139534884 2.38095238095238 3.57142857142857
    #> 11       Withdrew Consent 10.4651162790698 11.9047619047619 9.52380952380952
    #>               Total                                var_label
    #> 1          43.30709 Participant Study Medication Disposition
    #> 2          56.69291 Participant Study Medication Disposition
    #> 3  36.2204724409449 Participant Study Medication Disposition
    #> 4  1.18110236220472 Participant Study Medication Disposition
    #> 5  1.18110236220472 Participant Study Medication Disposition
    #> 6   1.5748031496063 Participant Study Medication Disposition
    #> 7  0.78740157480315 Participant Study Medication Disposition
    #> 8  1.18110236220472 Participant Study Medication Disposition
    #> 9  1.18110236220472 Participant Study Medication Disposition
    #> 10 2.75590551181102 Participant Study Medication Disposition
    #> 11 10.6299212598425 Participant Study Medication Disposition

## Format output

Once the raw analysis results are obtained, the `format_disposition()` function can be employed to prepare the outdata,ensuring its compatibility with production-ready RTF tables.

    outdata <- outdata |> format_disposition()

Click to show the output

    outdata$tbl
    #>                          name n_1    p_1 n_2    p_2 n_3    p_3 n_9999 p_9999
    #> 1  Participants in population  86   <NA>  84   <NA>  84   <NA>    254   <NA>
    #> 2                Discontinued  14 (16.3)  16 (19.0)  19 (22.6)     49 (19.3)
    #> 3               Adverse Event  10 (11.6)  11 (13.1)  12 (14.3)     33 (13.0)
    #> 4                 I/E Not Met   1  (1.2)   4  (4.8)   2  (2.4)      7  (2.8)
    #> 5            Lack of Efficacy   2  (2.3)   1  (1.2)   2  (2.4)      5  (2.0)
    #> 6            Withdrew Consent   1  (1.2)   0  (0.0)   3  (3.6)      4  (1.6)
    #> 7        Participants Ongoing  72 (83.7)  68 (81.0)  65 (77.4)    205 (80.7)
    #> 8                   Completed  58 (67.4)  25 (29.8)  27 (32.1)    110 (43.3)
    #> 9                Discontinued  28 (32.6)  59 (70.2)  57 (67.9)    144 (56.7)
    #> 10              Adverse Event   8  (9.3)  44 (52.4)  40 (47.6)     92 (36.2)
    #> 11                      Death   2  (2.3)   1  (1.2)   0  (0.0)      3  (1.2)
    #> 12                I/E Not Met   1  (1.2)   0  (0.0)   2  (2.4)      3  (1.2)
    #> 13           Lack of Efficacy   3  (3.5)   0  (0.0)   1  (1.2)      4  (1.6)
    #> 14          Lost to Follow-up   1  (1.2)   1  (1.2)   0  (0.0)      2  (0.8)
    #> 15         Physician Decision   1  (1.2)   0  (0.0)   2  (2.4)      3  (1.2)
    #> 16         Protocol Violation   1  (1.2)   1  (1.2)   1  (1.2)      3  (1.2)
    #> 17           Sponsor Decision   2  (2.3)   2  (2.4)   3  (3.6)      7  (2.8)
    #> 18           Withdrew Consent   9 (10.5)  10 (11.9)   8  (9.5)     27 (10.6)
    #>                                   var_label
    #> 1                                     -----
    #> 2                         Trial Disposition
    #> 3                         Trial Disposition
    #> 4                         Trial Disposition
    #> 5                         Trial Disposition
    #> 6                         Trial Disposition
    #> 7                         Trial Disposition
    #> 8  Participant Study Medication Disposition
    #> 9  Participant Study Medication Disposition
    #> 10 Participant Study Medication Disposition
    #> 11 Participant Study Medication Disposition
    #> 12 Participant Study Medication Disposition
    #> 13 Participant Study Medication Disposition
    #> 14 Participant Study Medication Disposition
    #> 15 Participant Study Medication Disposition
    #> 16 Participant Study Medication Disposition
    #> 17 Participant Study Medication Disposition
    #> 18 Participant Study Medication Disposition

## RTF tables

The last step is to prepare the RTF table using `rtf_trt_compliance`.

    outdata$tbl <- outdata$tbl %>%
      mutate(name = ifelse(trimws(name) == "Status Not Recorded", "    Status Not Recorded", name))

    outdata |>
      rtf_disposition(
        "Source: [CDISCpilot: adam-adsl]",
        path_outdata = tempfile(fileext = ".Rdata"),
        path_outtable = "outtable/disposition.rtf"
      )
    #> The outdata is saved in/rtmp/RtmpRzGgqz/file2a3c752dbbcbb.Rdata
    #> The output is saved in/rtmp/RtmpCbyWWZ/Rbuild2a3c395ee5a52a/metalite.sl/vignettes/outtable/disposition.rtf