Skip to contents

Association Scatter Widget

Source: R/Widget_AssociationScatter.R
Widget_AssociationScatter.Rd

A widget that renders the bio.viz association scatter: one point per participant, with a variable on each axis, a correlation coefficient printed under each panel and, when asked for, a fitted line over the points. The coefficient and the line are computed here, in R, by Analyze_Correlation() and Analyze_Fit(), and shipped with the page, so a saved page shows them with no R and no network.

Usage

Widget_AssociationScatter(
  dfResults,
  dfParticipants = NULL,
  lSettings = list(),
  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 colour and panel by and its numeric columns on either axis; it also says who the participants are. Without it a colour or a number comes from a column carried on the results rows. Default: NULL.

lSettings

list bio.viz association scatter settings, under bio.viz's own names; laid over the chart's defaults in the page, so only overrides are needed. For example x and y (the two variables), color_by, panel_by, x_scale, y_scale, fit ("none", "identity", "linear" or "smooth"), method ("pearson" or "spearman") and baseline_visits. The settings connection and back cannot be given; statistic can only be "Analyze_Correlation" or NULL for no statistics line, and fit_statistic only "Analyze_Fit" or NULL for no linear fit and no smooth. Default: list().

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, 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

The pair the settings name in x and y, each a variable as bio.viz writes one: list(measure = "IL-6", visit = "Week 4") for a biomarker's result at a visit, with value = "change", "fold_change", "percent_change" or "baseline" for a value worked out from its baseline, or list(col = "AGE") for a participant-level number. With neither named the chart opens on the first two biomarkers at the first visit.

Statistics shipped with the page

The chart computes no coefficient and no line. It asks R for a coefficient per panel and, for a linear fit or a smooth, a line per panel, and in a widget the answers are worked out when the widget is made and stored in the page, on the rows the chart draws in each panel of the view the settings open on: its two variables, colour, panel column, filters and scales.

For that view the widget stores both coefficients, Pearson's and Spearman's, and both lines, the linear fit and the smooth, whichever the settings open on: four results for each panel. The Method control and the Fitted line control change what is asked of the same rows and nothing else, so a reader of a saved page can move them and still be answered. The line y = x is the chart's own and needs no R.

A reader who moves any other control, to another variable, value type, visit, colour, panel column, filter or scale, is told that statistics are unavailable for that view, and a fitted line is not drawn. The page never shows one view's numbers under another.

On a logarithmic axis R is given the base-10 logarithm of the value, as the chart gives it, so a coefficient or a line there is of the values as plotted. The scale is part of what a stored result is found by.

The page states which R computed the results: the R version, the gsm.bio version and the time (see StatisticsResult). So that R and the chart resolve the same rows, 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.

See also

Analyze_Correlation() and Analyze_Fit(), which compute every stored result.

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

Examples

# TNF-alpha against IL-10 at Baseline, the pair the synthetic study plants a
# correlation of 0.6 in, coloured by arm, with R's straight line and its
# band. Under the chart: Pearson's coefficient of everyone drawn and of each
# arm, and the slope and intercept of each line. The Method and Fitted line
# controls are answered from the page; a filter or another variable is a
# view that was not computed, and says so.
lColumns <- list(
  list(value_col = "ARM", label = "Arm"),
  list(value_col = "SEX", label = "Sex"),
  list(value_col = "RESPONSE", label = "Response")
)

Widget_AssociationScatter(
  Synthetic_Results,
  Synthetic_Participants,
  lSettings = list(
    x = list(measure = "TNF-alpha", visit = "Baseline"),
    y = list(measure = "IL-10", visit = "Baseline"),
    baseline_visits = "Baseline",
    color_by = "ARM",
    fit = "linear",
    groups = lColumns,
    filters = lColumns
  )
)