Skip to contents

Stratified Survival Widget

Source: R/Widget_StratifiedSurvival.R
Widget_StratifiedSurvival.Rd

A widget that renders the bio.viz stratified survival chart: a Kaplan-Meier curve for each group on one endpoint of an outcomes table, with the number at risk beneath, and under them R's log-rank test, each group's median survival and the hazard ratio. The groups are a column, or a biomarker or a participant-level number cut into groups by the shared cut rule. The test is computed here, in R, by Analyze_Survival(), and shipped with the page, so a saved page shows it with no R and no network. A click on a curve, or on a count at risk, lists those participants.

Usage

Widget_StratifiedSurvival(
  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, offers its category columns to the Groups control, and its numbers can be cut. Default: NULL.

lSettings

list bio.viz stratified survival settings, under bio.viz's own names; laid over the chart's defaults in the page, so only overrides are needed. For example endpoint, group_by, cuts, at_risk_times, groups, filters, baseline_visits and the outcome columns. The setting connection cannot be given, and statistic can only be "Analyze_Survival" or NULL for no statistics line. Default: list().

dfOutcomes

data.frame The outcomes table: one row per participant and endpoint, with a time and a flag (see "The outcomes table"), or NULL, when the chart says it needs one and nothing is stored. 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.

The outcomes table

One row per participant and endpoint, with a time and a flag, as ADaM's time-to-event dataset holds it: PARAMCD names the endpoint, PARAM labels it, AVAL is the time and CNSR the flag, 1 for censored. The settings endpoint_col, endpoint_label_col, time_col, censor_col and outcome_id_col (the participant's id, id_col when NULL) name other columns. A flag the other way round, 1 for an event, is named by event_col; named alone it is the flag, and exactly one of the two is named. A participant with no row for the endpoint, more than one, a time or flag that is missing or not a number, a flag that is not 0 or 1, or a negative time is left out, and the chart says how many and why.

What the page opens on

The endpoint is endpoint, the first the outcomes table has when none is named. The groups are group_by: a column's name, or a cut variable, list(measure, visit, cut) for a biomarker or list(col, type = "number", cut) for a number, cut at its "median", "tertiles", "quartiles" or at typed points; with none named, the first category column. A column's groups are in order of name; a cut's run low to high, labelled with their bounds. The setting cuts lists more cut variables the Groups control offers, and a cut line can be dragged on the chart's histogram.

Statistics shipped with the page

The chart computes no test. It asks R once for its curves, with one row per participant drawn: the id, the time, the group and the flag. A cut's groups are handed to R high to low, so the hazard ratio is the higher group's hazard over the lower's; a column's are in order of code point. The widget stores R's answer for the view the settings open on. A reader who moves the endpoint, the groups, a cut line or a filter to a view that was not computed is told that statistics are unavailable for it; the page never shows one view's test under another.

The cut rule

A cut is the one bio.viz uses in every chart: the points are stats::quantile() with its default, type 7, on the participants the filters keep who have a value, or the typed points as written; a participant is in the group base::cut() puts them in with right = TRUE, so a value equal to a point falls in the lower group; a bound is written to four significant digits.

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.

See also

Analyze_Survival(), which computes the test, and Synthetic_Outcomes, the synthetic study's outcomes table.

Other widgets: Widget_AssociationScatter(), Widget_BiomarkerScreen(), Widget_CorrelationMatrix(), Widget_CrossTab(), Widget_GroupComparison()

Examples

# Event-free survival in the synthetic study by CRP at Baseline cut at its
# median: the study plants worse survival with high CRP. R's log-rank test,
# medians and hazard ratio are stored in the page.
Widget_StratifiedSurvival(
  Synthetic_Results,
  Synthetic_Participants,
  lSettings = list(
    endpoint = "EFS",
    group_by = list(measure = "CRP", visit = "Baseline", cut = "median"),
    cuts = list(list(measure = "CRP", visit = "Baseline", cut = "tertiles"))
  ),
  dfOutcomes = Synthetic_Outcomes
)



# The same endpoint by arm.
Widget_StratifiedSurvival(
  Synthetic_Results,
  Synthetic_Participants,
  lSettings = list(group_by = "ARM"),
  dfOutcomes = Synthetic_Outcomes
)