Skip to contents

Cross-Tabulation Widget

Source: R/Widget_CrossTab.R
Widget_CrossTab.Rd

A widget that renders the bio.viz cross-tabulation: a two-way table of counts, with its totals and percentages, beside stacked bars of the same numbers, and under it a test of the table. Either variable is 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_Contingency(), and shipped with the page, so a saved page shows it with no R and no network. A click on a count lists that cell's participants.

Usage

Widget_CrossTab(
  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 the Rows and Columns controls, and its numbers can be cut. Default: NULL.

lSettings

list bio.viz cross-tabulation settings, under bio.viz's own names; laid over the chart's defaults in the page, so only overrides are needed. For example row_by, col_by, percent ("row", "col" or "none"), test ("chisq", "fisher" or "none"), cuts, groups, filters and baseline_visits. The setting connection cannot be given, and statistic can only be "Analyze_Contingency" or NULL for no statistics line. 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 rows are row_by and the columns col_by: each 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 neither named the table is of the first two category columns. A column's categories are in order of code point; a cut's run low to high, labelled with their bounds. The setting cuts lists more cut variables the Rows and Columns controls offer.

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.

Statistics shipped with the page

The chart computes no test. It asks R once for the table, with one row per participant who has a category each way, and the categories in the table's order. The widget stores R's answer for the table the settings open on, by chi-square and by Fisher's exact test, so the Test control is answered either way. A reader who moves the rows, the columns or a filter to a view that was not computed is told that statistics are unavailable for it; the page never shows one table's test under another.

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_Contingency(), which computes the test.

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

Examples

# Response by arm in the synthetic study, with R's chi-square test and
# Fisher's exact test of the table stored in the page.
Widget_CrossTab(
  Synthetic_Results,
  Synthetic_Participants,
  lSettings = list(row_by = "ARM", col_by = "RESPONSE")
)



# Response by CRP at Baseline cut at its median.
Widget_CrossTab(
  Synthetic_Results,
  Synthetic_Participants,
  lSettings = list(
    row_by = "RESPONSE",
    col_by = list(measure = "CRP", visit = "Baseline", cut = "median")
  )
)