Biomarker Screen Widget

A widget that renders the bio.viz biomarker screen: one row per biomarker, each with its estimate and interval drawn on one shared axis and its raw and adjusted p-values, and a click on a row opens that biomarker's own chart in place. The rows are computed here, in R, by Analyze_Screen(), and the chart each row opens by Analyze_GroupDifference(), Analyze_Correlation() (and Analyze_Fit() for a fitted line) or Analyze_Survival(), and shipped with the page, so a saved page shows them with no R and no network.

Usage

Widget_BiomarkerScreen(
  dfResults,
  dfParticipants = NULL,
  lSettings = list(),
  dfOutcomes = NULL,
  width = NULL,
  height = NULL,
  elementId = NULL,
  bDebug = FALSE
)

Arguments

dfResults: data.frame Long-format results, one row per participant, biomarker and visit. Column names are supplied by lSettings; the defaults expect USUBJID/TEST/STRESN/VISIT/VISITNUM/STRESU, the columns of Synthetic_Results.
dfParticipants: data.frame One row per participant, or NULL. With it the chart has filters, and the columns of groups and the numbers it offers are read from it. Default: NULL.
lSettings: list bio.viz biomarker screen settings, under bio.viz's own names; laid over the chart's defaults in the page, so only overrides are needed. For example comparison, visit, value_type, group_by, levels, with, method, endpoint, adjustment, sort, limit, groups, numbers, filters, baseline_visits and the outcome columns; and group_comparison, association_scatter and stratified_survival, lists of settings for the chart a row opens. The setting connection cannot be given; statistic can only be "Analyze_Screen" or NULL for no rows; and the settings for the chart a row opens cannot name what the screen hands that chart itself: for the group comparison start_value, visits, value_type, group_by, levels and test, for the association scatter x, y and method, for the stratified survival chart group_by and endpoint, and for any filters, connection, waiting_note or back. Default: list().
dfOutcomes: data.frame An outcomes table, one row per participant and endpoint with a time and a flag, as Widget_StratifiedSurvival() takes it, or NULL. With it the screen offers a hazard ratio. It comes after lSettings, so a call written for v0.1.0 works as it did. Default: NULL.
width: character Width of the widget as a CSS unit. Default: NULL, as wide as its container.
height: character Height of the widget as a CSS unit. Default: NULL, as tall as the chart.
elementId: character ID of the widget's HTML element. Default: NULL.
bDebug: logical Print debug messages in the browser console? Default: FALSE.

Value

An htmlwidget. Its payload x carries dfResults, dfParticipants, dfOutcomes when it is given, lSettings, bDebug, whether a width and a height were left to the widget (bAutoWidth, bAutoHeight), and lStatistics: the stored results, each with name, args, dataId, rows and value, and computed_by, the R version, gsm.bio version and time that computed them.

What the page opens on

Every biomarker the Biomarker control offers, at one visit, visit (the first visit when none is named), with one value type, value_type. A difference (comparison = "difference", the default) compares two groups of one column, group_by and levels (the first column with two groups or more, and its first two groups, when none are named); each row is the standardised difference (Hedges' g) with Welch's p-value. A correlation (comparison = "correlation") correlates every biomarker with one variable, with, a biomarker at a visit or a participant-level number, by method; the biomarker that is that variable is not a row of its own. A hazard ratio (comparison = "hazard"), offered only with an outcomes table, cuts every biomarker at its median and compares high against low on one endpoint, endpoint (the first when none is named); each row is the hazard ratio, High over Low, with the log-rank p-value. The outcomes table is read as Widget_StratifiedSurvival() reads it, by the same settings. The p-values are adjusted across the rows by adjustment, Benjamini-Hochberg by default.

Statistics shipped with the page

The chart computes no estimate, interval or p-value. It asks R once for the whole screen, on a frame with one row per participant and one column per biomarker, keeping a participant who has only some of the biomarkers, so that each row is of the participants who have its value. The widget stores R's answer for the screen the settings open on.

A click on a row opens that biomarker's chart, which asks R for its own statistics. For a difference it is the group comparison, on the biomarker, at the screen's one visit, with only the two groups and Welch's test; for a correlation it is the association scatter, with the biomarker along the bottom and the variable up the side, by the same method; for a hazard ratio it is the stratified survival chart, on the biomarker cut at its median, on the same endpoint. For every row the widget stores exactly what that chart asks when it opens, under the screen's filters. On the synthetic study, a difference between the arms is one screen and twelve group comparisons.

A reader who moves a control of the screen, or of the chart a row opens, to a view that was not computed is told that statistics are unavailable for it: the screen's rows stay empty, and the chart prints the same. The page never shows one view's numbers under another.

The page states which R computed the results, and the widget names the baseline visits to the chart outright, as Widget_GroupComparison() does.

Filters

With a participant table the chart has filters, set by the setting filters under safety.viz's rules: a filter opens on its start when the data has it and otherwise on All, a filter set all = FALSE has no All and opens on its first value, and multiple = TRUE lets several values through. R works out what each filter opens on as the chart does, and stores the results for those participants.

The first value of an all = FALSE filter is the one exception, because the chart lists a filter's values in the order of the reader's browser, which R cannot know: for a letter with an accent or for punctuation it can differ from R's order, by code point. So the widget hands the chart R's first value as the filter's start, and the page opens on the participants R computed for, though that value may not be the first in the list.

Bundles

The widget loads bio.viz's bundle and the copy of safety.viz's bundle that bio.viz itself builds its chart from. Both are copied from bio.viz, with the bio.viz commit and a checksum per file recorded beside them in system.file("htmlwidgets", "lib", "SOURCE.json", package = "gsm.bio"). They are bio.viz v0.1.0 and safety.viz v1.9.0, the first safety.viz with the kit the chart is built from, as bio.viz takes it from safety.viz's dev branch; the record says from which commit. gsm.safety carries an earlier safety.viz without the kit, and once it carries v1.9.0 the widgets can take the bundle from there.

Examples

# Every biomarker's change from Baseline to Week 4 in the synthetic study,
# Placebo against Treatment. IL-6 is the biomarker the study plants a
# difference in; a click on its row, or on any other, opens that biomarker's
# group comparison with its test, all stored in the page.
lColumns <- list(
  list(value_col = "ARM", label = "Arm"),
  list(value_col = "SEX", label = "Sex"),
  list(value_col = "RESPONSE", label = "Response")
)

Widget_BiomarkerScreen(
  Synthetic_Results,
  Synthetic_Participants,
  lSettings = list(
    visit = "Week 4",
    value_type = "change",
    group_by = "ARM",
    baseline_visits = "Baseline",
    groups = lColumns,
    filters = lColumns,
    group_comparison = list(groups = lColumns)
  )
)


# Every biomarker at Baseline, high against low on event-free survival. CRP
# is the biomarker the study plants a survival effect in; a click on a row
# opens the survival curves of that biomarker cut at its median.
Widget_BiomarkerScreen(
  Synthetic_Results,
  Synthetic_Participants,
  lSettings = list(
    comparison = "hazard",
    visit = "Baseline",
    endpoint = "EFS",
    groups = lColumns,
    filters = lColumns
  ),
  dfOutcomes = Synthetic_Outcomes
)