# Collect Components

    library(metalite)

In this document, let’s explore how to collect components using metalite. The document is for developer who plan to create new tools.

Let’s first define a meta object by using the `meta_example()` function. It is an ad-hoc function to create a meta object same as in the `get started` page.

    meta <- meta_example()
    meta
    #> ADaM metadata:
    #>    .$data_population     Population data with 254 subjects
    #>    .$data_observation    Observation data with 1191 records
    #>    .$plan    Analysis plan with 10 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 'wk12' 'USUBJID' 'TRTA'        SAFFL == 'Y' 'Weeks 0 to 12'
    #> 2 'wk24' 'USUBJID' 'TRTA'     AOCC01FL == 'Y' 'Weeks 0 to 24'
    #>
    #>
    #>   Analysis parameter type:
    #>      name                                label
    #> 1   'rel'        'drug-related adverse events'
    #> 2 'aeosi' 'adverse events of special interest'
    #> 3   'any'                 'any adverse events'
    #> 4   'ser'             'serious adverse events'
    #>                                 subset
    #> 1 AEREL %in% c('POSSIBLE', 'PROBABLE')
    #> 2                         AEOSI == 'Y'
    #> 3
    #> 4                         AESER == 'Y'
    #>
    #>
    #>   Analysis function:
    #>            name                           label
    #> 1  'ae_summary'  'Table: adverse event summary'
    #> 2 'ae_specific' 'Table: specific adverse event'

## Collect ADaM mapping

The object in `meta` is organized as a list of ADaM mapping objects. For example, you can directly access an ADaM mapping object as a list.

    meta$population$apat
    #> ADaM mapping:
    #> * `name`   -> "apat"
    #> * `id`     -> "USUBJID"
    #> * `group`  -> "TRTA"
    #> * `var`    -> NULL
    #> * `subset` -> SAFFL == "Y"
    #> * `label`  -> "All Participants as Treated"

We created helper function to help you access components by component name. For example, we can collect the same `apat` component from `meta` by `name` using `collect_adam_mapping()`.

Collect ADaM mapping for all participants as treated.

    collect_adam_mapping(meta, name = "apat")
    #> ADaM mapping:
    #> * `name`      -> "apat"
    #> * `id`        -> "USUBJID"
    #> * `group`     -> "TRTA"
    #> * `var`       -> NULL
    #> * `subset`    -> SAFFL == "Y"
    #> * `label`     -> "All Participants as Treated"
    #> * `.location` -> "population"

We can collect ADaM mapping for serious adverse events parameter `meta$parameter$ser`.

    collect_adam_mapping(meta, name = "ser")
    #> ADaM mapping:
    #> * `name`      -> "ser"
    #> * `id`        -> NULL
    #> * `group`     -> NULL
    #> * `var`       -> "AEDECOD"
    #> * `subset`    -> AESER == "Y"
    #> * `label`     -> "serious adverse events"
    #> * `soc`       -> "AEBODSYS"
    #> * `seq`       -> 401
    #> * `term1`     -> "Serious"
    #> * `term2`     -> ""
    #> * `summ_row`  -> "with serious adverse events"
    #> * `.location` -> "parameter"

We can collect ADaM mapping for AE summary analysis method `meta$analysis$ae_summary`.

    collect_adam_mapping(meta, name = "ae_summary")
    #> ADaM mapping:
    #> * `name`      -> "ae_summary"
    #> * `id`        -> NULL
    #> * `group`     -> NULL
    #> * `var`       -> NULL
    #> * `subset`    -> NULL
    #> * `label`     -> "Table: adverse event summary"
    #> * `title`     -> "Summary of Adverse Events"
    #> * `.location` -> "analysis"

## Collect population

While developing tools, developer also need to access the subset condition of a population. We can access the information from the list as

    meta$population$apat$subset
    #> SAFFL == "Y"

Equivalently, we can also use `collect_population()` to collect the definition of a population. For example, we can collect subset condition for `apat` as

    collect_population(meta, population = "apat")
    #> $population
    #> [1] "SAFFL == 'Y'"

By using `collect_population()`, we can find subset condition from multiple levels. For example, we can collect analysis population definition for `apat` population, `wk12` observation and `ser` parameters.

    collect_population(meta,
      population = "apat",
      observation = "wk12",
      parameter = "ser"
    )
    #> $population
    #> [1] "SAFFL == 'Y'"
    #>
    #> $observation
    #> [1] "SAFFL == 'Y'"
    #>
    #> $parameter
    #> [1] "AESER == 'Y'"

## Collect population records

User may want to identify records belong to an analysis population. We can use `collect_population_index()` to show all population record index. In this example, user would get index from all population data set for `apat` or all participants as treated.

    population_index <- collect_population_index(meta, "apat")

    head(collect_population_index(meta, "apat"))
    #> [1] 1 2 3 4 5 6

Alternatively, people may want to know the ID of those subjects in a population. In this case, `collect_population_id()` can be used to collect `ID - > USUBJID` from the `apat` population.

    population_id <- collect_population_id(meta, "apat")

    head(collect_population_id(meta, "apat"))
    #> [1] "01-701-1015" "01-701-1023" "01-701-1028" "01-701-1033" "01-701-1034"
    #> [6] "01-701-1047"

We can further directly collect observations using `collect_population_record()`. By default, key variables used in `id`, `group`, and `subset` are displayed.

This example shows how to collect population record from population data set for all participants as treated and only display default variables.

    head(collect_population_record(meta, "apat"))
    #>       USUBJID                 TRTA SAFFL
    #> 1 01-701-1015              Placebo     Y
    #> 2 01-701-1023              Placebo     Y
    #> 3 01-701-1028 Xanomeline High Dose     Y
    #> 4 01-701-1033  Xanomeline Low Dose     Y
    #> 5 01-701-1034 Xanomeline High Dose     Y
    #> 6 01-701-1047              Placebo     Y

This example show how to add variables in population data set to display.

    head(collect_population_record(meta, "apat", var = "AGE"))
    #>       USUBJID                 TRTA SAFFL AGE
    #> 1 01-701-1015              Placebo     Y  63
    #> 2 01-701-1023              Placebo     Y  64
    #> 3 01-701-1028 Xanomeline High Dose     Y  71
    #> 4 01-701-1033  Xanomeline Low Dose     Y  74
    #> 5 01-701-1034 Xanomeline High Dose     Y  77
    #> 6 01-701-1047              Placebo     Y  85

We can also add add multiple additional variable to display

    head(collect_population_record(meta, "apat", var = c("AGE", "TRT01P")))
    #>       USUBJID                 TRTA SAFFL AGE               TRT01P
    #> 1 01-701-1015              Placebo     Y  63              Placebo
    #> 2 01-701-1023              Placebo     Y  64              Placebo
    #> 3 01-701-1028 Xanomeline High Dose     Y  71 Xanomeline High Dose
    #> 4 01-701-1033  Xanomeline Low Dose     Y  74  Xanomeline Low Dose
    #> 5 01-701-1034 Xanomeline High Dose     Y  77 Xanomeline High Dose
    #> 6 01-701-1047              Placebo     Y  85              Placebo

## Collect observation record

Similarly we can collect observation records with examples below. This example shows how to collect observation record index from observation data set for serious AE from weeks 0 to 12 using `collect_observation_index()`

    collect_observation_index(meta, "apat", "wk12", "ser")
    #> [1]  689 1131 1173

We can also directly collect records using `collect_observation_record()`. By default, key variables used in `id`, `group`, and `subset` are displayed.

This example shows how to collect observation record from observation data set for all participants as treated from 0 to 12 week with serious AE and only display default variables.

    collect_observation_record(meta, "apat", "wk12", "ser")
    #>          USUBJID                 TRTA
    #> 689  01-709-1424 Xanomeline High Dose
    #> 1131 01-718-1170  Xanomeline Low Dose
    #> 1173 01-718-1371 Xanomeline High Dose
    #>                                             AEDECOD SAFFL AESER
    #> 689                                         SYNCOPE     Y     Y
    #> 1131                                        SYNCOPE     Y     Y
    #> 1173 PARTIAL SEIZURES WITH SECONDARY GENERALISATION     Y     Y

This example show how to add variables in observation data set to display.

    collect_observation_record(meta, "apat", "wk12", "ser", var = "AEDECOD")
    #>          USUBJID                 TRTA
    #> 689  01-709-1424 Xanomeline High Dose
    #> 1131 01-718-1170  Xanomeline Low Dose
    #> 1173 01-718-1371 Xanomeline High Dose
    #>                                             AEDECOD SAFFL AESER
    #> 689                                         SYNCOPE     Y     Y
    #> 1131                                        SYNCOPE     Y     Y
    #> 1173 PARTIAL SEIZURES WITH SECONDARY GENERALISATION     Y     Y

## Collect specifications

We also provided helper functions to collect commonly used items

Developer can collect table title for analysis function meta information using `collect_title()`.

    collect_title(meta, "apat", "wk12", "ser", "ae_summary")
    #> [1] "Summary of Adverse Events"   "Weeks 0 to 12"
    #> [3] "All Participants as Treated"

Developer can collect specification for data set name using `collect_dataname()`. It will show the data set name for population and observation.

    collect_dataname(meta)
    #>  population observation
    #>      "adsl"      "adae"