Functional Specs

Baseline and Comparison Visit(s) Controls

These multi-select controls are used to select the visits that are displayed in the chart. The default visits are set to the first/last visit in the data set, but the default value can be adjusted to any visit upon the project team's request. Users can interactively select any single visit, or shift-click to select multiple visits. Selecting a visit will update the delta-delta chart accordingly. When multiple visits are selected, all participant measures from those visits are averaged.

X and Y Measure Controls

These controls are used to select the measures that are displayed in the chart. The default measures are set to the first and second measure found in the data set, but the default value can be adjusted to any measure upon the project team's request. Users can interactively select any measure, which updates the delta-delta chart accordingly.

Filter by Pre-selected Characteristics

The chart can be configured to have any number of data filters. Each specified filter has a drop-down menu that is used to filter the visit data that is displayed in the chart.

Total Participants Shown

Displayed under the controls, this statement provides the total number of participants in the data set in integers as well as the percentage of participants shown to one decimal place. When filters are used, the data shown in the histogram is manipulated and the number of participant records shown at the top of the page may increase or decrease, depending on the variable selected.

Hover

By moving a mouse cursor over a point in the chart, users can display exact x- and y-values for the chosen point along with the ID for the selected participant.

Linked Table

Clicking on a point in the chart will open a table beside the chart that contains a detailed listing of all participant lab data. Each row of the table has summary data for a single measure for the selected participant, and includes, the measure name, a sparkline showing the measure's value over time, and an annotated numeric value summarizing the change in the measure between the selected time points. This linked table contains a standard set of default columns that appear consistently across all filters. When a point is clicked it is highlighted and the table header shows the participant ID and any other specified participant details.

Regression Tests

Controls

• Confirm that if the X or Y Measure filter is changed, the distribution of observations change.
• Confirm that if the Baseline or Comparison Visit filters are changed, the distribution of observations change.
• Confirm that plotted values represent the change between baseline and comparison visits for the selected measures. (Clicking points and then mousing over values in the detail table should make this relatively easy to QC).
• Confirm that multi-select (shift-click) in Visit Filters works as expected. Participant with multiple values should have their values averaged. Click a point and mouseover points in the the detail section to confirm.
• View x of x participants note at the bottom of the controls: check that it updates when filters are applied
• Confirm that filters work as expected. {"filters":[{"value_col":"SITE","label":"Site"}]}
• Confirm that if a filter is added for a variable that is not in the data, then a browser console warning is thrown. Add a made up filter such as {"filters":[{"value_col":"SOTE","label":"Sote"}]} and render the chart. Open the browser's developer tools to the Console view and look for the "The [ Sote ] filter has been removed because the variable does not exist." message.
• Confirm that missing or non-numeric values in the dataset are handled and removed, and that the number of missing and non-numeric records appears opposite the number of participants annotation, beneath the controls. View the same Console in the developer tools and look for the "xxxx missing or non-numeric results have been removed." warning message. Download the dataset, remove some numeric values, save the datset, and then upload the new version, and render the chart. The number of missing or non-numeric values shown in the warning message should increment accordingly.
• Confirm that if you set initial X or Y Measure to an existent value (like IgE) and render, then the chart defaults to the specified measure, but with units attached. [[[TODO: ADD CODE]]]
• Confirm that specifying a non-existent value for a required field (such as Measure/Medical Sign or Result) and rendering the charts results in a "variable does not exist error" printed to both the console and the container element, and the chart is then destroyed. [[[TODO: ADD CODE]]]

Chart

• Confirm that you can view a detailed listing of all measures for a participant by clicking on a point in the chart.
• Confirm that the clicked point is highlighted with a thick black border
• Confirm that click a different point when the detail table is shown, redraws the table for the newly clicked participant.
• Confirm that changing any control removes the detail table.
• Confirm that the points are not cut off on the edge of the chart.

Data Listing

• Confirm that Participant ID is displayed above the table
• Confirm that updating the Details option displays additional metadata above the chart [[[TODO: ADD CODE]]]
• Confirm that the table header has "Measure" and "Change over Time" headers
• Confirm that one row is shown for each measure collected for the clicked participant
• Confirm that each row has the measure's name, a sparkline showing the pattern of the data over time, and a change over time value.
• Confirm that change over time values are red if they are less than 0, green if they are greater than 0 and black if they equal 0.
• Confirm that values where baseline or comparison visits are missing renderer with a gray "NA"
• Confirm that in the sparkline, baseline visits are shown as filled blue circles, comparison visits are shown as filled orange circles and other visits are shown as empty gray circles.
• Confirm that the footnote beneath the table describes the colors used in the table accurately.
• Confirm that the currently selected x- and y-axis measures have the appropriate light blue tags.

The Safety Delta-Delta plot accepts JSON data of the format returned by d3.csv(). The renderer visualizes clinical medical signs data with one row per measurement plus the required variables specified below.

Data structure

one record per measurement

Data specification

required and optional variables:

safetyDeltaDelta(element, settings)

a factory to create a custom Webcharts chart object

returns: chart

The most straightforward way to customize the Safety Delta-Delta plot is by using a configuration object whose properties describe the behavior and appearance of the chart. Since the Safety Histogram is a Webcharts chart object, many default Webcharts settings are set in the webchartsSettings.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 the Safety Delta-Delta plot 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

The sections below describe each safety-delta-delta setting as of version 1.0.0.

settings.measure_col

string

a variable that contains the names of each medical sign

default: "TEST"

settings.value_col

string

a variable that contains the results for each medical sign; non-numeric results are removed with a notification thrown to the log

default: "STRESN"

settings.id_col

string

a variable that contains IDs for each participant

default: "USUBJID"

settings.visit_col

string

a variable that contains the categorical visit where the measure was collected

default: "VISIT"

settings.visitn_col

string

a variable that contains the numeric visit where the measure was collected

default: "VISITN"

settings.measure

object

Measures to be used in delta-delta scatter plot. Must be a value of the settings.measure_value column

settings.measure.x

string

Measure to be shown on the x-axis of the delta-delta plot

default: none

settings.measure.y

string

Measure to be shown on the y-axis of the delta-delta plot

default: none

settings.addRegressionLine

boolean

Indicates whether a regression line should be drawn on the delta-delta scatter plot

default: false

settings.visits

object

settings.visits.x

string

Measure to be shown on the x-axis of the delta-delta plot

default: none

settings.visits.y

string

Measure to be shown on the y-axis of the delta-delta plot

default: none

settings.filters

array

an array of variables and metadata that will appear in the controls as data filters

default: none

settings.filters[].label

string

a description of the variable

default: none

settings.filters[].value_col

string

the name of the variable

default: none

settings.details

array

an array of variables and metadata that will appear in the data listing

default: none

settings.details[].label

string

a description of the variable

default: none

settings.details[].value_col

string

the name of the variable

default: none

Webcharts settings

The object below contains Webcharts settings that define the safety-histogram chart as of version 1.0.0 of the Safety Delta Delta.

{
    "x": {
        "column": null,
        "type": "linear",
        "label": "x delta",
        "format": "0.2f"
    },
    "y": {
        "column": null,
        "type": "linear",
        "label": "y delta",
        "behavior": "flex",
        "format": "0.2f"
    },
    "marks": [
        {
            "type": "circle",
            "per": null,
            "radius": 4,
            "attributes": {
                "stroke-width": 0.5,
                "fill-opacity": 0.8
            },
            "tooltip": "Subject ID: [key]\nX Delta: [delta_x_rounded]\nY Delta: [delta_y_rounded]"
        }
    ],
    "gridlines": "xy",
    "resizable": false,
    "margin": {
        "right": 25,
        "top": 25
    },
    "aspect": 1,
    "width": 400
}