Skip to contents

Correlation Matrix Widget

Source: R/Widget_CorrelationMatrix.R
Widget_CorrelationMatrix.Rd

A widget that renders the bio.viz correlation matrix: a grid over a set of variables, each pair a cell holding its correlation coefficient and its own pair count, and a click on a cell opens that pair's association scatter in place. The coefficients are computed here, in R, by Analyze_CorrelationMatrix(), and each cell's scatter by Analyze_Correlation() (and Analyze_Fit() for a fitted line), and shipped with the page, so a saved page shows them with no R and no network.

Usage

Widget_CorrelationMatrix(
  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; it also says who the participants are. Default: NULL.

lSettings

list bio.viz correlation matrix settings, under bio.viz's own names; laid over the chart's defaults in the page, so only overrides are needed. For example mode, visit, biomarkers, measure, visits, value_type, method, min_pairs, limit and baseline_visits, and scatter, a list of settings for the association scatter a cell opens (its groups, numbers, color_by, fit). The setting connection cannot be given; statistic can only be "Analyze_CorrelationMatrix" or NULL for no coefficients; and scatter cannot name what the grid hands the scatter itself: x, y, method, filters, connection or back. 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

Across biomarkers (mode = "biomarkers", the default), every biomarker the limit allows at one visit, visit, the first visit when none is named; or those named in biomarkers. Across visits (mode = "visits"), one biomarker, measure, at each visit, or those named in visits. Every variable has the same value type, value_type. The grid draws at most limit variables, twelve by default.

The grid prints no p-value, by design: Analyze_CorrelationMatrix() returns none. A cell's scatter prints that pair's coefficient with its interval and p-value.

Statistics shipped with the page

The chart computes no coefficient. It asks R once for the grid, on a frame with one row per participant and one column per variable, keeping a participant who has only some of the values, so that each cell is of the participants who have both of its values. The widget stores R's answer for the grid the settings open on.

A click on a cell opens the association scatter for its pair, with the column's variable on the x axis and the row's on the y axis, and the scatter asks R for its own statistics. For every cell of the grid, on either side of the diagonal, the widget stores exactly what that scatter asks when it opens: its coefficient, by the grid's method, under the grid's filters, and a fitted line when the setting scatter asks for one. On the synthetic study, twelve biomarkers at Baseline, that is one grid and 132 scatters.

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

The minimum number of pairs is R's: min_pairs is handed to R only when it is set. 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.

See also

Analyze_CorrelationMatrix(), which computes the grid, and Widget_AssociationScatter(), the chart a cell opens.

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

Examples

# Every biomarker of the synthetic study at Baseline, biomarker against
# biomarker. The cell of TNF-alpha with IL-10 holds the correlation the study
# plants; a click on it, or on any other cell, opens that pair's scatter with
# its coefficient, its interval and its p-value, 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_CorrelationMatrix(
  Synthetic_Results,
  Synthetic_Participants,
  lSettings = list(
    visit = "Baseline",
    baseline_visits = "Baseline",
    filters = lColumns,
    scatter = list(groups = lColumns)
  )
)