Technical Documentation

This page contains various technical documentation for the library, starting with a set of Feature Tests.

Feature Tests

These tests can be used to confirm that any given version of the chart is behaving as expected. The first example page or CAT can be used for testing unless otherwise noted.

Chart

Feature tests for the main chart.

• Confirm that you can drag horizontal and vertical dotted reference lines, and that the Quadrant table below the chart, the percentages in the annotations in the corners of the chart, and the Reference Line controls update according to the new placement of the chart lines
• Confirm that hovering on a data point brings up a (1) tooltip that displays participant details (ID, Visit milestones, r ratio) and (2) small ticks on the x- and y-axis representing the participants measures at each visit. The circle shows the maximum value across all visits should be positioned accordingly relative to the ticks.
• Confirm that clicking on a data point makes the circle bold and draws a line between one or more points, depending on how many visits the participant has completed. Each new point has it’s own tool tip with visit-level details.
• Confirm that there is a button in the upper left corner, beside the Safety eDish header, labeled Raw Data; and that clicking the button allows you to download the dataset used for the chart
• Confirm that boxplots summarizing the distribution of the are drawn to the top and right of the chart, and that hovering over each boxplot shows a tooltip with details.

Participant Details

Feature tests for the participant details section which appears when clicking a point in the main chart.

• Confirm that clicking a data point in the chart opens the Participant Details for the selected participant. Three new sections should appear:
• Participant Details – horizontal text-based list or participant characteristics
• Standardized Lab Values by Visit – Line chart showing key measures
• Raw Lab Values Summary Table – Table with small charts summarizing lab values
• R Ratio by Visit - Line chart showing R Ratio values for Study Day
• Confirm that the Standardized Lab Values by Visit chart has a Select Labs filter that is a multi-select box of labs. Confirm that all labs are selected by default and you can control click to select or deselect labs. Confirm that the chart only shows lines that correspond to the selected labs in the filter.
• Confirm that there is a Y-axis Display Type filter that is a drop down that allows you to select between different baseline or upper limit y-axis values.
• Confirm that hovering over a line in the Standardized Lab Values by Visit chart displays a reference line for that lab as a dotted line in the chart.
• Confirm that each measure in the Raw Lab Values Summary Table section has a sparkline (small chart) that can be clicked on to see an expanded view.
• Confirm that clicking the Clear button at the top of the Participant Details section closes the Participant Details view and the Quadrant table is again shown below the main chart.
• Using example 3, confirm that an exposure timeline is shown under the "Standardized Lab Values by Visit" chart when data is provided.

Messages

Feature tests for the Messages section in the sidebar.

• Confirm that there is a Message section at the top left of the chart, just under the header and download Raw Data button.
• Confirm that any relevant messages, such as a Caution message about how many rows were removed from the dataset sue to missing or non-numeric data; or a general caution message against using the chart as the sole determiner for clinical recommendations.
• Confirm that shorter summaries for each message are shown by default and that clicking the 3 white dots expands to show the whole message.
• Confirm that links to download csv data in messages indicating that data was excluded from the chart work as expected.
• Confirm that there is a Clear button that allows the user to clear the messages from display.

Filters

Feature tests for the filters section in the sidebar.

• Confirm that there is a filter for R Ratio that includes minimum and maximum values along with a reset button.
• Confirm that the range is initially set between 0 and the maximum value found in the data.
• Confirm that increasing or decreasing the numbers in the boxes updates the chart accordingly to only display points that match the filter.
• Confirm that the values automatically sort when entering a min value greater than the max value (or vice versa)
• Confirm that the reset button returns the values to the default.
• Confirm that an warning is displayed in place of the chart when no participants are selected (e.g. when setting both values greater than the default max)
• Confirm that additional data-driven filters appear as specified, and show-hide points as expected.
• Confirm that the participant count (“xxx of xxx participants shown”) in the Filters header updates as expected.
• Confirm that the Filters section appears on the left side of the chart, below the Messages section

Settings

Feature tests for the settings section in the sidebar

• Confirm that the Settings section appears on the left side of the chart, below the Filters section
• Confirm that there is a Group setting dropdown that allows you to change the grouping variable for the chart. When changed, the legend and point color should update accordingly. When ‘None’ is selected, all points should be the same color and the legend above the chart should be removed. (can use the settings object { "group_cols": "SEX" })
• Confirm there is a Display Type setting, to set Relative or absolute axes, using a dropdown field that allows for the selection of either “Upper limit of normal adjusted (eDish)” (this is the default) or Baseline adjusted (mDish). Changing this setting should update the chart accordingly (test using settings object { "baseline": { "value_col": "VISIT", "values": [ "Visit 1" ] } } ).
• Confirm there is an X-axis Measure setting dropdown field that allows the selection of either ALT, AST, or ALP, with each selection updating the x-axis of the chart, as well as the data points shown in the chart.
• Confirm there is are “[measure] Reference Line” settings where [measure] is set to one of the key variables (typically TB, ALT, AST, or ASP) depending on the current variables used for the x- and y-axes. Confirm that this field is a box with a number that can be adjusted either by changing the number in the box, or by dragging the x-axis reference dotted line in the chart itself. Changing the number in the box should shift the line in the chart to the appropriate new spot on the x-axis, dragging the line in the chart should update the number in the box to show the axis point to which you dragged the line.
• Confirm there is a Point Size setting drop down field that allows for the selection of different measures in the chart to have a larger point radius to make them more visible. The default selection should be Uniform, with the other options being ALT, ASP, ALP, TB.
• Confirm there is an Axis Type setting drop down field that allows you to change the chart between linear or log Axes. The default selection should be linear.
• Confirm there is a Highlight Points Based on Timing setting number field that updates the chart’s fill points with max values less than X days apart. As you increase the setting number, you should see more points fill in in the chart. Confirm that the footnote regarding timing is shown below the main chart and that it updates when the control is changed (including good grammar for 0 and 1 days).
• Confirm that the x-axis measure and Point Size options show the long name, not just the three letter abbreviation, (ex.: "Aminotransferase, alanine (ALT)", "Alkaline phosphatase (ALP)", etc.)
• Confirm there is a Reset Chart button at the bottom of the Settings section that resets the chart to its default view and default Filters and Settings.
• Confirm that all options should be shown for x and point size, but the y-axis control should be hidden by default since TB is the only option.
• Confirm that the addmeasures setting adds additional options under the x-Axis and point size controls. settings = {addmeasures:true}
• Confirm that the new "all" option works as expected for the axes and point-size controls, including for the y-axis, so that changing settings to {xoptions:["ALT","ALP"],yoptions:"all", pointsizeoptions:["TB","AST"]} adds the Y-axis Measure dropdown.
• Confirm that the new "all" options works in tandem with {add_measures:true} as well.
• Confirm that changing the default settings updates the default values for the given controls on initial load, and that the controls still work as expected. {settings = {xdefault:"ALP",yoptions:"all", ydefault:"ALT", pointsizedefault:"rRatio"}}
• Confirm that updating the cuts object works as expected. With the settings below, TB should have its cut point set to 2, ALP should be 4, AST should be 5 and all other measures should be 6. { "addmeasures": true, "cuts": { "ALP": { "relativebaseline": 4.8, "relativeuln": 4 }, "AST": { "relativebaseline": 5.8, "relativeuln": 5 }, "defaults": { "relativebaseline": 6.8, "relativeuln": 6 } }, "baseline": { "valuecol": "DY", "values": [ 1 ] } }
• Confirm that with the same settings in place as above, when you change Display Type to mDish, then TB should have its cut point set to 4.8, ALP should be 4.8, AST should be 5.8 and all other measures should be 6.8.
• Confirm that a single new measure can be added to the x axis and point size controls with the settings {measurevalues:{ige:"IgE"}}. Adding addmeasures:true to the settings should still add all measures.

Plot Style

• Confirm that changing the plot style control shows/hides the study day slider under the chart.
• Confirm that changing the plot style control causes the the scatter plot points to update. Using the participants details view, confirm that the point position is correct. Selecting "Max Values" should show the point using max values across all visits, while selecting "By Study Day" should show the points using the most recent values collected on or before the selected study day.
• Confirm the study day slider defaults to the first non-negative study day in the data.
• Confirm that clicking a different value on the study day slider changes the position of the points
• Confirm that all controls (filters, point size, etc) and the participant profile (clicking a point) works in the expected way on the "By Study Day" view
• Confirm that clicking the play button starts an animation from the currently selected study day until the end of the study.
• Confirm that while the animation is running, a square stop icon is shown instead of the triangular play button.
• Confirm that clicking the stop button stops the animation on the current day
• Confirm that if the last study is selected on the study day slider, the play button changes to a circular "replay" arrow, and that clicking that button plays the animation from the first study day until the end of the study.
• Confirm that any user interaction involving control changes and point clicks while the animation is running, interrupt the animation and cause it to stop on the current date.
• Confirm that small points are shown during the animation when the study day is before or after a given participant's study enrollment (as described by the figures footnote).
• Confirm that footnotes regarding point size and fill change appropriately when changing plot style
• Confirm that point size changes appropriately over the course of the animation when an option other than "Uniform" is selected

R Ratio

• Confirm that 'rRatio' has been added as an option under points size, and that the points are sized appropriately when it is clicked.

• Confirm that a new 'R Ratio by Visit' chart is visible in the participant details when the point is clicked. The chart should have the following features:

  • Reference lines at 2 and 5, which should always be visible even when no R Ratio values >2 are present
  • Exact Study day and r ratio values shown on point mouseover.

• Filter to id = 5090-02 and confirm that R ratio values (shown on point mouseover) are correct for each plot type. Use the clinical-trials\renderer-specific\allQuads.csv dataset and this settings object: { "maxwidth": 600, "valuecol": "LBORRES", "measurecol": "TESTNAM", "visitcol": "VISIT", "studydaycol": "STUDYDAY", "normalcollow": "LBORRESLO", "normalcolhigh": "LBORRESHI", "idcol": "SUBJID", "groupcols": [ "TRTA", "SEX" ], "filters": [ { "valuecol": "TRTA", "label": "Treatment" }, { "valuecol": "SEX", "label": "Sex" }, { "valuecol": "SUBJID", "label": "ID" } ], "measurevalues": { "ALT": "ALT (SGPT)", "AST": "AST (SGOT)", "TB": "Total Bilirubin", "ALP": "Alkaline Phosphatase" }, "baseline": { "valuecol": "STUDYDAY", "values": [ 1 ] } }

• R ratio should be calculated based on the selected study day for the "by study day" view. Using the "R Ratio by Visit" chart as a guide, confirm that the R ratio value updates when study day changes.

• R ratio should be calculated using the timepoint when AST is maximized on the "max values view". This can be confirmed using id = 5090-02 in \example 2. For that participant, the summary R Ratio value (shown hovering over the point) should be 6.09 - from study day 84, when max ALT occurred. Note that this is not the maximal R Ratio, which was 9.12 from study day 14.

Data Guidelines

The Safety eDish chart is initialized with JSON data files that match the format created by d3.csv(). The chart is specifically designed for clinical trial safety monitoring, and requires a datasets that contains one row per participant per time point per measure and includes the required columns and fields specified below.

Data Standards

The chart expects an SDTM-esque data structure by default but also easily supports the ADaM data standard (Example : Settings, eDish Graphic). Other, non standard data can also be as long as the data is structured correctly.

Required and optional columns and fields for the SDTM and ADaM data standard are given in the tables below

Required Data Columns Settings

Six variables are required to create an eDish plot: ID, Measure, Value, high and low normal range values and study day. Details and suggested values for ADaM and SDTM are given below.

Settings Variable	Description (type)	SDTM (Default)	ADaM	Required?
id_col	Unique Subject Identifier (char)	USUBJID	USUBJID	Y
measure_col	Name of Measure or Test (chart)	TEST	PARAM	Y
value_col	Result or Finding (numeric)	STRESN	AVAL	Y
normalcolhigh	Upper Limit of Normal (numeric)	STNRHI	ANRHI	Y
normalcollow	Lower Limit of Normal (numeric)	STNRLO	ANRLO	Y
studyday_col	Study Day (numeric)	DY	ADY	Y

Optional Data Column Settings

Users may customize the chart with the additional data mappings given below. Note that these are not specified by default, and must be defined by the user. Some suggested mappings for SDTM and ADaM are provided below for reference. See the settings object here for an example of a customized chart.

Settings Variable	Description	SDTM	ADaM	Required?
visitn_col	Visit Number	VISITNUM	VISITNUM	N
visit_col	Visit Name	VISIT	VISIT	N
filter[].value_col	Visit-level filter(s)	SEX, RACE, etc*		N
details[].value_col	Person-level descriptive(s)			N
groupcols[].valuecol	Grouping variable(s)	ACTARM*	TRTA	N
baseline.value_col	Baseline Visit definition	DY	ADY	N
analysisFlag.value_col	Analysis Visit Flag	EPOCH	ANL01FL	N

• - merged from demographics data domain.

Data Field Settings

Field level data is used for identifying key measures for the eDish plot (see settings.measure_details) and identifying baseline visits (see settings.baseline). Suggested values (including the default SDTM values) are shown below, but the user should note that these are very likely to change from study to study.

Usage	SDTM Column/Value (default)	ADaM Column/Field Value
Define ALT key measure	TEST / 'Aminotransferase, alanine (ALT)'	PARAM / 'Alanine Aminotransferase (U/L)'
Define AST key measure	TEST / 'Aminotransferase, aspartate (AST)'	PARAM / 'Aspartate Aminotransferase (U/L)'
Define TB key measure	TEST / 'Total Bilirubin'	PARAM / 'Bilirubin (umol/L)'
Define ALP key measure	TEST / 'Alkaline phosphatase (ALP)'	PARAM / 'Alkaline Phosphatase (U/L)'
Define Baseline visit	DY / 0	ADY / 0

API

hepexplorer(element, settings)

a factory to create a custom Webcharts chart object

returns: chart

Param	Type	Description
element	string	CSS selector identifying the element in which to create the chart
settings	object	settings object specifying options for how the chart is to appear and behave. Options defined here overwrite default values; see Configuration

Events

participantsSelected

The custom participantsSelected event is dispatched to the overall chart wrapper (chart.wrap) whenever the details for a given participant are viewed (or cleared) by clicking on a point in the chart. The event has a custom data property holding an array with the selected ID when a new participant is selected (["123-456-7"]) or an empty array when participant details are cleared.

Configuration Overview

The most straightforward way to customize the Safety Outlier Explorer is by using a configuration object whose properties describe the behavior and appearance of the chart. Since the safety eDish is a Webcharts chart object, many default Webcharts settings are set in the defaultSettings.js file as described below. Refer to the Webcharts documentation for more details on these settings.

In addition to the standard Webcharts settings several custom settings not available in the base Webcharts library have been added to facilitate data mapping and other custom functionality. These custom settings are described in detail below. All defaults can be overwritten by users.

Renderer-specific settings

settings.id_col

string

Unique subject identifier variable name

default: "USUBJID"

settings.value_col

string

result variable name

default: "STRESN"

settings.measure_col

string

measure variable name

default: "TEST"

settings.unit_col

string

measure unit variable name

default: "STRESU"

settings.normalcollow

string

LLN variable name

default: "STNRLO"

settings.normalcolhigh

string

ULN variable name

default: "STNRHI"

settings.studyday_col

string

Study day variable name

default: "DY"

settings.visit_col

string

Visit variable name

default: null

settings.visitn_col

string

Visit number variable name

default: null

settings.exposurestdycol

string

Exposure start day variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXSTDY'

settings.exposureendycol

string

Exposure end day variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXENDY'

settings.exposuretrtcol

string

Exposure treatment name variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXTRT'

settings.exposuredosecol

string

Exposure dose variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXDOSE'

settings.exposuredosucol

string

Exposure dose variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXDOSU'

settings.baseline

object

Object defining the baseline visit of the study.

settings.baseline.value_col

string

Column containing the baseline visit data

default: "DY"

settings.baseline.values

array

One or more values found in settings.baseline.value_col indicating that the record represents the baseline visit.

default: [0]

settings.filters

array

an array of filter variables and associated metadata

default: none

settings.filters[].value_col

string

Variable name

default: none

settings.filters[].label

string

Variable label

default: none

settings.filters_multiselect

boolean

If true filters are set up to allow multiple selections.

default: true

settings.details

array

an array of ID-level variables and associated metadata

default: Automatically uses values specified in settings.id_col, settings.group_cols and settings.filters

settings.details[].value_col

string

Variable name

default: Automatically uses values specified in settings.id_col, settings.group_cols and settings.filters

settings.details[].label

string

Variable label

default: Automatically uses values specified in settings.id_col, settings.group_cols and settings.filters

settings.group_cols

array

an array of grouping variables and associated metadata

default: none

settings.groupcols[].valuecol

string

Variable name

default: none

settings.group_cols[].label

string

Variable label

default: none

settings.analysisFlag

object

Flags records for use in the eDish and mDish calculations.

default: none

settings.analysisFlag.value_col

string

Indicates which column should be used to flag rows for inclusion eDish and mDish analysis

default: none

settings.analysisFlag.values

array or string

Indicates which values should be used to flag rows for inclusion eDish and mDish analysis

default: none

settings.calculate_palt

object

Indicates whether P_ALT should be calculated for participants flagged using settings.paltFlag.

default: none

settings.paltFlag

object

Flags records for use in the P_ALT calculations. Only used if settings.calculate_palt is true.

default: none

settings.paltFlag.value_col

string

Indicates which column should be used to flag rows for P_ALT analysis.

default: none

settings.paltFlag.values

array or string

Indicates which values should be used to flag rows for for P_ALT analysis.

default: none

settings.measure_values

object

An object defining the data values from measure_col for the lab measures used in eDish evaluations.

default:

  {
    ALT: 'Aminotransferase, alanine (ALT)',
    AST: 'Aminotransferase, aspartate (AST)',
    TB: 'Total Bilirubin',
    ALP: 'Alkaline phosphatase (ALP)'
  },

settings.add_measures

boolean

If true, all unique values from settings.measure_col are automatically added to the settings.measure_values object. Can be paired with the "all" option for settings.x_options, settings.y_options and settings.point_size_options to allow for flexible interactive axis controls using all available data. Added in v1.2.

default: false

settings.x_options

array or string

Specifies variable options for the x-axis using the key values from settings.measure_values (e.g. "ALT"). When multiple options are specified, a control allowing the user to interactively change the x variable is shown. Specifying 'all' (added in v1.2) uses all options from measure_values.

default: 'all'

settings.x_default

string

String indicating the starting value for the x-axis when the chart is loaded. Must be an option from the settings.x_options array. First item in the settings.x_options array is used if an invalid option is specified.

default: 'ALT'

settings.y_options

array or string

See settings.x_options.

default: ['TB']

settings.y_default

string

See settings.x_default.

default: 'TB'

settings.pointsizeoptions

array or string

See settings.x_options. For point size, options for 'Uniform' (the default) and 'rRatio' are automatically added to the control in addition to the users selections.

default: 'all'

settings.pointsizedefault

string

See settings.x_default.

default: "Uniform"

settings.imputation_methods

array of string

Specifies how data should be imputed for each measure specified in config.measure_values. Valid options are:

• "data-driven" is the default and it takes 0 values and sets them to 0.5 times the minimum value for the measure across all participants/time points
• "user-defined" takes all values less than config[key].imputation_value and sets then to 0.5 times config[key].imputation_value. (The config.imputation_value option is ignored otherwise)
• "drop" means all 0 values are dropped.

default:

{
  ALT: 'data-driven',
  AST: 'data-driven',
  TB: 'data-driven',
  ALP: 'data-driven'
}

settings.imputation_values

number

used as described above when config.imputation_method is set to "user-defined"

default: none

settings.cuts

object

Object defining default cut-points for each measure defined in config.measure_values for each of the different types of supported eDish displays defined in config.display. If config.measure_values is customized to add additional key measures, then values from cuts.defaults are used unless the user provides values using the format shown below.

default:

{
  TB: {
    relative_baseline: 4.8,
    relative_uln: 2
  },
  ALP: {
    relative_baseline: 3.8,
    relative_uln: 1
  }
}

settings.cuts.defaults

object

Default cut values to be used when no user settings are provided. Added in v1.2.

default:

{
  relative_baseline: 3.8,
  relative_uln: 3
}

settings.display

"string"

Defines the display type used on the eDish scatter plot on initial view. Can be changed by the user once the chart is rendered. Valid options are:

• "relative_uln" which shows the standard eDish view where values are scaled relative to the Upper Limit or Normal
• "relative_baseline" which shows the mDish view where values are scaled relative to the participants baseline value

Note: Support for an "absolute" option used to show the raw values for the measure was removed prior to the v1 release.

settings.display_options

array

Defines nice labels for the different display options.

default:

  display_options: [
        { label: 'Upper limit of normal adjusted (eDish)', value: 'relative_uln' },
        { label: 'Baseline adjusted (mDish)', value: 'relative_baseline' }
    ]

settings.measureBounds

array of number

Sets upper and lower percentiles used for defining outlier in the "Lab Summary Table" in the participant details section.

default: [0.01,0.99]

settings.populationProfileURL

string

URL linking to additional charts related to population level analysis

default: none

settings.participantProfileURL

string

URL linking to additional charts related to population level analysis. Will need an update in a future release to allow dynamic links for different participants.

default: none

settings.visit_window

number

Default visit window used to highlight eDish points where x and y measures occurred within the specified number of days. Editable by user after render.

default: 30

settings.rratiofilter

boolean

Specifies whether the R Ratio filter should be shown. R ratio is defined as: (ALT value/ULN for ALT) / (ALP value/ULN for ALP).

default: true

settings.rratiocut

numeric

Default cut point for R Ratio filter. Ignored when r_ratio_filter is false. User can update this setting via the UI when r_ratio_filter is true.

default: 0

settings.title

character

Title to be drawn above the controls. Use an empty string or NULL if no title is desired.

default: "Hepatic Safety Explorer"

settings.warningText

string

Informational text to be displayed near the top of the controls (beneath the title, if any). No warning is displayed if warningText is false-y.

default: 'Caution: This interactive graphic is not validated. Any clinical recommendations based on this tool should be confirmed using your organizations standard operating procedures.'

Webcharts settings

The object below contains the default Webcharts settings for the display.

  x: {
        column: null, //set in onPreprocess/updateAxisSettings
        label: null, // set in onPreprocess/updateAxisSettings,
        type: 'linear',
        behavior: 'raw',
        format: '.2f'
        //domain: [0, null]
    },
    y: {
        column: null, // set in onPreprocess/updateAxisSettings,
        label: null, // set in onPreprocess/updateAxisSettings,
        type: 'linear',
        behavior: 'raw',
        format: '.2f'
        //domain: [0, null]
    },
    marks: [
        {
            per: [], // set in syncSettings()
            type: 'circle',
            summarizeY: 'mean',
            summarizeX: 'mean',
            attributes: { 'fill-opacity': 0 }
        }
    ],
    gridlines: 'xy',
    color_by: null, //set in syncSettings
    max_width: 900,
    aspect: 1,
    legend: { location: 'top' },
    margin: { right: 25, top: 25, bottom: 75 }