# Generate Multiple AE Tables via 1 Single Metadata

    library(forestly)
    #> Warning: package 'forestly' was built under R version 4.4.3
    library(metalite)
    library(metalite.ae)

## Overview

This vignette demonstrates how to define one metadata object and reuse it to generate multiple adverse event (AE) outputs.

In many reporting workflows, summary tables, AE-specific tables, listings, and visualizations are produced from the same analysis population and the same core AE definitions. Centralizing those definitions in one metadata object helps:

- reduce duplicated setup code,
- keep analysis assumptions consistent across outputs, and
- simplify maintenance when specifications change.

The outputs in this vignette include:

- a static AE summary table,
- a static AE-specific table,
- an interactive AE listing table, and
- an interactive AE forest plot.

## Define metadata

The example uses ADSL and ADAE data from the forestly package.

    adsl <- forestly_adsl
    adae <- forestly_adae

    adsl$TRTA <- factor(forestly_adsl$TRT01A,
      levels = c("Xanomeline Low Dose", "Placebo"),
      labels = c("Low Dose", "Placebo")
    )
    adae$TRTA <- factor(forestly_adae$TRTA,
      levels = c("Xanomeline Low Dose", "Placebo"),
      labels = c("Low Dose", "Placebo")
    )

## Define multiple analysis plans in one object

Use `plan()` and `add_plan()` to define a set of analysis plans in a single pipeline. Each plan references one analysis type and one parameter set, while sharing the same population and observation context.

This approach makes it easy to orchestrate multiple downstream outputs from one metadata object.

    # 1st analysis plan for AE summary
    # i.e., overall AE summary including any AEs, drug-related AEs, and serious AEs
    plan <- plan(
      analysis = "ae_summary",
      population = "apat",
      observation = "apat",
      parameter = "any;drug-related;serious"
    ) |>
      # 2nd analysis plan for AE specific
      # i.e., patients with drug-related AEs
      add_plan(
        analysis = "ae_specific",
        population = "apat",
        observation = "apat",
        parameter = "drug-related"
      ) |>
      # 3rd analysis plan for AE listing
      # i.e., listing of patients with serious AEs
      add_plan(
        analysis = "ae_listing",
        population = "apat",
        observation = "apat",
        parameter = "drug-related"
      ) |>
      # 4th analysis plan for AE forest plot
      # i.e., interactive forest plot for drug-related and serious AEs
      add_plan(
        analysis = "ae_forestly",
        population = "apat",
        observation = "apat",
        parameter = "drug-related;serious"
      )

## Build metadata once

After defining the plan set, create the full metadata object with population, observation, parameter, and analysis definitions.

The resulting `meta` object is the single source of truth for all outputs below.

    meta <- meta_adam(population = adsl, observation = adae) |>
      define_plan(plan) |>
      define_analysis(name = "ae_summary", label = "AE Summary Table") |>
      define_analysis(name = "ae_specific", label = "AE Specific Table") |>
      define_analysis(
        name = "ae_listing", label = "AE Listing Table",
        var_name = c("USUBJID", "ASTDY", "AEDECOD", "ADURN", "AESEV", "AESER", "AEREL", "AEOUT"),
        group_by = c("USUBJID", "ASTDY"), page_by = "TRTA"
      ) |>
      define_analysis(name = "ae_forestly", label = "Interactive Forest Plot") |>
      define_population(
        name = "apat", group = "TRTA", id = "USUBJID",
        subset = SAFFL == "Y", label = "All Patient as Treated"
      ) |>
      define_observation(
        name = "apat", group = "TRTA",
        subset = SAFFL == "Y", label = "All Patient as Treated"
      ) |>
      define_parameter(
        name = "any",
        subset = NULL,
        label = "Any AEs",
        var = "AEDECOD", soc = "AEBODSYS",
        term1 = "", term2 = ""
      ) |>
      define_parameter(
        name = "drug-related",
        subset = toupper(AREL) == "RELATED",
        label = "Drug-related AEs",
        var = "AEDECOD", soc = "AEBODSYS",
        term1 = "Drug Related", term2 = ""
      ) |>
      define_parameter(
        name = "serious",
        subset = toupper(AESER) == "Y",
        label = "Serious AEs",
        var = "AEDECOD", soc = "AEBODSYS",
        term1 = "Serious", term2 = ""
      ) |>
      meta_build()

## AE output 1: Static AE summary table

Start with the summary output to review high-level AE incidence across parameters.

    meta |>
      prepare_ae_summary(
        population = "apat",
        observation = "apat",
        parameter = "any;drug-related"
      ) |>
      format_ae_summary() |>
      gt_ae_summary(
        source = "Source:  [CDISCpilot: adam-adsl; adae]",
        analysis = "ae_summary" # Provide analysis type defined in meta$analysis
      )
    #> any
    #> drug-related
    #> [1] "adverse event summary"  "All Patient as Treated" "All Patient as Treated"

adverse event summary All Patient as Treated All Patient as Treated
| Low Dose | Placebo | Total
--- | --- | --- | ---
n | (%) | n | (%) | n | (%)
Participants in population | 84 |  | 86 |  | 170 |
with one or more adverse events | 77 | (91.7) | 69 | (80.2) | 146 | (85.9)
with no adverse events | 7 | (8.3) | 17 | (19.8) | 24 | (14.1)
Drug-related AEs | 73 | (86.9) | 44 | (51.2) | 117 | (68.8)
Source: [CDISCpilot: adam-adsl; adae]

## AE output 2: Static AE-specific table

Next, generate a term-level AE-specific table. This output breaks results down by system organ class and preferred term, which supports more detailed clinical review.

    meta |>
      prepare_ae_specific(
        population = "apat",
        observation = "apat",
        parameter = "drug-related"
      ) |>
      format_ae_specific() |>
      gt_ae_specific(
        meddra_version = "24.0",
        source = "Source:  [CDISCpilot: adam-adsl; adae]",
        analysis = "ae_specific" # Provide analysis type defined in meta$analysis
      )

Participants With Drug Related Adverse Events (Incidence > 0 % in One or More Treatment Groups) All Patient as Treated All Patient as Treated
| Low Dose | Placebo | Total
--- | --- | --- | ---
n | (%) | n | (%) | n | (%)
Participants in population | 84 |  | 86 |  | 170 |
with one or more drug related adverse events | 73 | (86.9) | 44 | (51.2) | 117 | (68.8)
with no drug related adverse events | 11 | (13.1) | 42 | (48.8) | 53 | (31.2)
Cardiac disorders | 7 | (8.3) | 6 | (7.0) | 13 | (7.6)
Atrial fibrillation | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Atrial flutter | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Atrioventricular block first degree | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Atrioventricular block second degree | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Bradycardia | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Bundle branch block right | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Cardiac failure congestive | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Myocardial infarction | 1 | (1.2) | 2 | (2.3) | 3 | (1.8)
Palpitations | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Sinus arrhythmia | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Sinus bradycardia | 2 | (2.4) | 2 | (2.3) | 4 | (2.4)
Supraventricular extrasystoles | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Ventricular extrasystoles | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Wolff-parkinson-white syndrome | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Congenital, familial and genetic disorders | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Ventricular septal defect | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Ear and labyrinth disorders | 2 | (2.4) | 0 | (0.0) | 2 | (1.2)
Tinnitus | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Vertigo | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Eye disorders | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Vision blurred | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Gastrointestinal disorders | 8 | (9.5) | 4 | (4.7) | 12 | (7.1)
Abdominal pain | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Diarrhoea | 3 | (3.6) | 3 | (3.5) | 6 | (3.5)
Dyspepsia | 1 | (1.2) | 1 | (1.2) | 2 | (1.2)
Gastrooesophageal reflux disease | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Nausea | 3 | (3.6) | 0 | (0.0) | 3 | (1.8)
Vomiting | 2 | (2.4) | 0 | (0.0) | 2 | (1.2)
General disorders and administration site conditions | 43 | (51.2) | 18 | (20.9) | 61 | (35.9)
Application site bleeding | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Application site dermatitis | 9 | (10.7) | 5 | (5.8) | 14 | (8.2)
Application site desquamation | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Application site discolouration | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Application site erythema | 12 | (14.3) | 3 | (3.5) | 15 | (8.8)
Application site induration | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Application site irritation | 9 | (10.7) | 3 | (3.5) | 12 | (7.1)
Application site pruritus | 22 | (26.2) | 6 | (7.0) | 28 | (16.5)
Application site reaction | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Application site swelling | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Application site urticaria | 2 | (2.4) | 0 | (0.0) | 2 | (1.2)
Application site vesicles | 4 | (4.8) | 1 | (1.2) | 5 | (2.9)
Application site warmth | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Asthenia | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Chills | 1 | (1.2) | 1 | (1.2) | 2 | (1.2)
Fatigue | 2 | (2.4) | 1 | (1.2) | 3 | (1.8)
Malaise | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Oedema | 2 | (2.4) | 0 | (0.0) | 2 | (1.2)
Pain | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Injury, poisoning and procedural complications | 2 | (2.4) | 0 | (0.0) | 2 | (1.2)
Fall | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Skin laceration | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Wound | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Investigations | 2 | (2.4) | 4 | (4.7) | 6 | (3.5)
Blood creatine phosphokinase increased | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Body temperature increased | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Electrocardiogram st segment depression | 1 | (1.2) | 1 | (1.2) | 2 | (1.2)
Heart rate increased | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Heart rate irregular | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Metabolism and nutrition disorders | 0 | (0.0) | 3 | (3.5) | 3 | (1.8)
Decreased appetite | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Food craving | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Increased appetite | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Musculoskeletal and connective tissue disorders | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Shoulder pain | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Nervous system disorders | 12 | (14.3) | 5 | (5.8) | 17 | (10.0)
Balance disorder | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Complex partial seizures | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Coordination abnormal | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Dizziness | 6 | (7.1) | 2 | (2.3) | 8 | (4.7)
Headache | 1 | (1.2) | 2 | (2.3) | 3 | (1.8)
Lethargy | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Paraesthesia oral | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Somnolence | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Stupor | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Syncope | 4 | (4.8) | 0 | (0.0) | 4 | (2.4)
Transient ischaemic attack | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Psychiatric disorders | 9 | (10.7) | 2 | (2.3) | 11 | (6.5)
Agitation | 2 | (2.4) | 0 | (0.0) | 2 | (1.2)
Anxiety | 3 | (3.6) | 0 | (0.0) | 3 | (1.8)
Confusional state | 2 | (2.4) | 1 | (1.2) | 3 | (1.8)
Depressed mood | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Irritability | 1 | (1.2) | 1 | (1.2) | 2 | (1.2)
Restlessness | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Renal and urinary disorders | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Enuresis | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Reproductive system and breast disorders | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Pelvic pain | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Respiratory, thoracic and mediastinal disorders | 0 | (0.0) | 2 | (2.3) | 2 | (1.2)
Dyspnoea | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Emphysema | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Skin and subcutaneous tissue disorders | 39 | (46.4) | 17 | (19.8) | 56 | (32.9)
Blister | 5 | (6.0) | 0 | (0.0) | 5 | (2.9)
Cold sweat | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Dermatitis contact | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Erythema | 13 | (15.5) | 9 | (10.5) | 22 | (12.9)
Hyperhidrosis | 4 | (4.8) | 1 | (1.2) | 5 | (2.9)
Pruritus | 21 | (25.0) | 7 | (8.1) | 28 | (16.5)
Pruritus generalised | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Rash | 11 | (13.1) | 3 | (3.5) | 14 | (8.2)
Rash erythematous | 2 | (2.4) | 0 | (0.0) | 2 | (1.2)
Rash pruritic | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Skin exfoliation | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Skin irritation | 6 | (7.1) | 2 | (2.3) | 8 | (4.7)
Skin ulcer | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Urticaria | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Vascular disorders | 2 | (2.4) | 1 | (1.2) | 3 | (1.8)
Hypertension | 1 | (1.2) | 0 | (0.0) | 1 | (0.6)
Hypotension | 1 | (1.2) | 1 | (1.2) | 2 | (1.2)
Orthostatic hypotension | 0 | (0.0) | 1 | (1.2) | 1 | (0.6)
Every participant is counted a single time for each applicable row and column.
A system organ class or specific adverse event appears on this report only if its incidence in one or more of the columns meets the incidence criterion in the report title, after rounding.
Adverse event terms are from MedDRA Version 24.0.
Source: [CDISCpilot: adam-adsl; adae]

## AE output 3: Interactive AE listing table

The listing workflow uses `prepare_ae_listing()` followed by `format_ae_listing()` and `react_ae_listing()`.

Compared with a static listing, the interactive output supports on-screen inspection with pagination and a compact review experience.

    meta |>
      prepare_ae_listing(
        population = "apat",
        observation = "apat",
        parameter = "drug-related",
        analysis = "ae_listing" # Provide analysis type defined in meta$analysis
      ) |>
      format_ae_listing() |>
      react_ae_listing(
        default_page_size = 15
      )

## AE output 4: Interactive AE forest plot

Finally, create an interactive AE forest plot from the same metadata object. This visualization helps compare treatment effects across terms and complements the tabular outputs.

    meta |>
      prepare_ae_forestly() |>
      format_ae_forestly() |>
      ae_forestly()
    #> Warning in prepare_ae_forestly(meta): There is no record for the parameter
    #> "serious" to display.

AE Criteria
Incidence (%) in One or More Treatment Groups

## Summary

This workflow shows that one metadata definition can drive multiple AE report types consistently. In practice, this pattern improves reproducibility and makes it easier to evolve analysis specifications without reworking each output independently.