# Getting Started with sunburstShinyWidget

## What is sunburstShinyWidget?

sunburstShinyWidget provides an interactive D3.js sunburst chart as a Shiny htmlwidget. It is designed for visualizing OHDSI ATLAS pathway analysis data — treatment sequences patients follow over time.

The chart renders pathways as concentric rings where each ring is a treatment step and arc widths reflect patient counts. Clicking an arc shows the full pathway with drop-off statistics.

## Basic Usage

The simplest way to use the package is through its Shiny module:

    library(shiny)
    library(bslib)
    library(sunburstShinyWidget)

    chartData <- jsonlite::read_json("path/to/chartData.json")
    design <- jsonlite::read_json("path/to/design.json")

    ui <- page_sidebar(
      title = "Sunburst plot",
      sidebar = sidebar(open = FALSE),
      sunburstUI("my_plot")
    )

    server <- function(input, output) {
      sunburstServer("my_plot", chartData, design)
    }

    shinyApp(ui, server)

`sunburstUI` creates a 4-panel layout:

- Legend (left) — target cohort info and color-coded event cohort buttons
- Sunburst chart (center) — the interactive D3.js visualization
- Path details (right) — populates when you click a sunburst arc, showing Remain and Diff counts
- Steps table (bottom) — aggregated pathway steps with a CSV download button

## Module Parameters

`sunburstServer` accepts several optional parameters to customize behavior:

    sunburstServer(
      id = "my_plot",
      chartData = chartData,
      design = design,
      btn_font_size = "14px",                    # Font size for colored cohort buttons
      show_colors_in_table = FALSE,              # TRUE = colored buttons in steps table
      steps_table_export_name = reactive(NULL),  # Custom CSV export filename
      n_steps = reactive(5L)                     # Number of steps shown in the table
    )

### Controlling the Number of Steps

The `n_steps` parameter controls how many Step columns appear in the bottom table. It accepts a reactive, so you can make it dynamic:

    server <- function(input, output) {
      sunburstServer(
        "my_plot", chartData, design,
        n_steps = reactive(input$step_slider)
      )
    }

Note: the sunburst chart itself always renders all steps up to `design$maxDepth`. The `n_steps` parameter only affects the table.

### Custom Export Filename

    sunburstServer(
      "my_plot", chartData, design,
      steps_table_export_name = reactive("my_analysis_steps.csv")
    )

If not provided, the filename defaults to `{TargetCohortName}_steps_table.csv`.

## Using the Low-Level Widget

If you need custom UI instead of the full module dashboard, use the widget directly:

    ui <- fluidPage(
      sunburstShinyWidgetOutput("my_sunburst", height = "600px")
    )

    server <- function(input, output) {
      output$my_sunburst <- renderSunburstShinyWidget({
        sunburstShinyWidget(chartData, design)
      })
    }

When using the widget directly, you handle all UI layout and event processing yourself. The widget sends data back to R through Shiny inputs with these suffixes appended to the output ID:

Input Suffix | Contents
--- | ---
`_chart_data_converted` | Converted chart data with color mappings
`_click_data` | Clicked arc info: pathway, node data, ancestor path
`_pathway_group_datatable` | Aggregated steps table data

For example, if your output ID is `"my_sunburst"`, access click data in the server as `input$my_sunburst_click_data`.

## Data Format

The widget requires two data structures, typically from an OHDSI ATLAS pathway analysis export.

### chartData

Contains pathway results — event codes and the pathways themselves:

    list(
      eventCodes = list(
        list(code = 1L, name = "Glipizide-txp", isCombo = FALSE),
        list(code = 2L, name = "Metformin-txp", isCombo = FALSE),
        list(code = 4L, name = "Simvastatin-txp", isCombo = FALSE),
        list(code = 3L, name = "Glipizide-txp,Metformin-txp", isCombo = TRUE)
      ),
      pathwayGroups = list(
        list(
          targetCohortId = 1781666L,
          targetCohortCount = 756L,
          totalPathwaysCount = 366L,
          pathways = list(
            list(path = "4-end", personCount = 115L),
            list(path = "4-2-end", personCount = 35L),
            list(path = "2-end", personCount = 35L)
          )
        )
      )
    )

### design

Contains the analysis configuration — which cohorts to visualize and display settings:

    list(
      name = "IQT-Pathways",
      targetCohorts = list(
        list(id = 1781666L, name = "T2DM Treatment group")
      ),
      eventCohorts = list(
        list(id = 1789987L, name = "Glipizide-txp"),
        list(id = 1789986L, name = "Metformin-txp"),
        list(id = 1789985L, name = "Simvastatin-txp")
      ),
      combinationWindow = 3L,
      maxDepth = 5L
    )

Key fields:

- `maxDepth` — maximum pathway steps tracked. Paths shorter than this get an `"-end"` suffix.
- `combinationWindow` — days within which concurrent treatments are combined into a single event code.
- `targetCohortId` in chartData must match an `id` in design’s `targetCohorts`.

### How to Get This Data

Export from OHDSI ATLAS:

1. Run a pathway analysis in ATLAS
2. Export the `PathwayDesignData.json`
3. The `data` key becomes your `chartData`, the `design` key becomes your `design`

    full_export <- jsonlite::read_json("PathwayDesignData.json")
    chartData <- full_export$data
    design <- full_export$design

Or load the included sample data from two separate files:

    chartData <- jsonlite::read_json(
      system.file("extdata", "chartData.json", package = "sunburstShinyWidget")
    )
    design <- jsonlite::read_json(
      system.file("extdata", "design.json", package = "sunburstShinyWidget")
    )

## Understanding Bitwise Event Codes

This is the most unusual aspect of the data format. Each base treatment gets a power-of-2 code:

Treatment | Code | Binary
--- | --- | ---
Glipizide | 1 | `001`
Metformin | 2 | `010`
Simvastatin | 4 | `100`

Combination treatments use bitwise OR:

Combination | Code | Binary
--- | --- | ---
Glipizide + Metformin | 3 | `011`
Glipizide + Simvastatin | 5 | `101`
Metformin + Simvastatin | 6 | `110`
All three | 7 | `111`

The chart handles this automatically — combo arcs are split into individually colored segments so you can see which treatments compose the combination.

A pathway like `"4-2-6-end"` reads as: Step 1 = Simvastatin, Step 2 = Metformin, Step 3 = Metformin + Simvastatin (combo), then the pathway ended.

## Embedding in a Larger App

Since `sunburstUI`/`sunburstServer` is a Shiny module, you can embed it alongside other components:

    ui <- page_navbar(
      title = "My Analysis Dashboard",
      nav_panel("Overview", "Summary stats here..."),
      nav_panel("Pathways",
        layout_columns(
          col_widths = 12,
          sunburstUI("pathways")
        )
      ),
      nav_panel("Details", "Other analysis outputs...")
    )

    server <- function(input, output) {
      sunburstServer("pathways", chartData, design)
    }

You can also use multiple sunburst modules for different cohorts:

    ui <- page_fluid(
      h3("Cohort A"),
      sunburstUI("cohort_a"),
      h3("Cohort B"),
      sunburstUI("cohort_b")
    )

    server <- function(input, output) {
      sunburstServer("cohort_a", chartData_a, design_a)
      sunburstServer("cohort_b", chartData_b, design_b)
    }

Each module instance is fully namespaced — no ID collisions.

## Helper Functions

The package exports several utility functions used internally that may be useful in custom workflows:

### `add_remain_and_diff_cols(btns_df, totalPathways)`

Adds Remain and Diff columns (with percentages) to a pathway breakdown table:

    df <- data.frame(Name = c("Step 1", "Step 2"), Remain = c(300, 180))
    add_remain_and_diff_cols(df, totalPathways = 756)
    #>     Name          Remain            Diff
    #> 1 Step 1 300 (39.7%) 456 (60.3%)
    #> 2 Step 2 180 (23.8%) 120 (15.9%)

### `customActionButton(inputId, label, color, font_size)`

Creates a Shiny action button with a custom background color:

    customActionButton("btn1", "Metformin", "#1f77b4", font_size = "12px")

### `match_color(x, eventCodes)`

Maps comma-separated event names to colored HTML button strings using an event codes data frame.

### `getPathwayGroupDatatable(id, pathwayAnalysisDTO, pathLength)`

Triggers the JavaScript-side pathway aggregation. Called internally by `sunburstServer` — you only need this if building custom server logic with the low-level widget.