Functional Specifications

Filter by Measure

This drop-down menu is used to filter the lab variable that is displayed in the chart. The default measure is set to the first variable in the data set, but the default value can be adjusted to any measure upon the project team's request. Users can select any pre-defined measure in this filter. Selecting a measure will display the data points associated with that measure and will display the visits that the measure is collected at underneath the chart.

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 header, 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. In the default view, all participant data is included in the chart, or 100%, unless the project team requests otherwise. 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.

Set Y-axis Limits

Users are able to adjust the lower limit of the y-axis by manipulating the input within the Lower Limit box. Users are able to adjust the upper limit of the y-axis by manipulating the input within the Upper Limit box. Each limit box has up and down arrows to adjust the value of the box by 1. Users can select an arrow to change the input or delete the current value in the box and type in a new value. When typing in a value, users must click outside of the box to apply the changes. When a user manipulates a y-axis limit, the y-axis on the chart below the controls will reflect the change.

Reset Y-axis limits

Users can change the upper and lower y-axis limits back to the default values for a measure by selecting the "Reset Limits" button. Pressing the button will erase the current values in the upper and lower limit boxes and replace them with defaults. The chart below will also reflect the changes and will show the default axes.

View Visits Without Data

Users can select the checkbox to view visits that do not contain data. Checking the box will show a timepoint for the visit. Unchecking the checkbox will hide the timepoint for visits without data; visits without data are hidden on default.

View Unscheduled Visits

Users can select the checkbox to view data that is not associated with a scheduled visit. Checking the box will show a timepoint for the unscheduled visit and its associated data. Unselecting the checkbox will hide the unscheduled visit timepoint and its data; unscheduled visits are hidden on default.

Box and Whisker Plots

The chart includes box and whisker plots to show the data distribution for a given measure. These plots show the data distribution for a data measure and can be added to the chart by clicking the box to the right of the Box plots text located above the chart. To take the plots away, the user can uncheck the box by clicking in it again. The box is checked by default, so the box and whisker plots appear when the chart is rendered.

Violin Plots

The chart includes violin plots to show the data distribution for a given measure. These plots show the data distribution for a data measure and can be added to the chart by clicking the box to the right of the Violin plots text located above the chart. To take the plots away, the user can uncheck the box by clicking in it again. The box is not checked by default, so the violin plots do not appear when the chart is rendered.

Regression Tests

• Confirm that the number and percentage of participants is displayed
• Confirm that the filters are working as expected (Measure, Group): selecting a variable changes the plot values. Customize the chart to add the Group filter: {"groups":["SEX","RACE"]}
• Confirm that when a grouping is selected, the order of box/violin plots for each x-axis value match the group order in the legend.
• Confirm that checking the "Visits without data" checkbox shows a timepoint for visits with no associated data points
• Confirm that unchecking the "Visits without data" checkbox hides the timepoint for visits with no associated data points
• Confirm that checking the "Unscheduled visits" checkbox shows a timepont for unscheduled visits and their associated data
• Confirm that unchecking the "Unscheduled visits" checkbox hides the timepoint for unscheduled visits and their associated data
• Confirm that selecting the violin plot option causes violin plots to appear around the data ranges
• Confirm that selecting the box plot option causes box plots to appear around the data ranges
• Confirm that checking the Outliers checkbox causes results outside the 5th and 9th percentiles (i.e. results outside the horizontal lines of box plots) to be displayed in the chart.
• Confirm that Outlier points are clearly visible in the chart, even with Violin plots selected and that hovering on an outlier causes it to expand.
• Confirm that unchecking the Outliers checkbox hides the outliers from the chart.
• Confirm that the # of enrolled/randomized participants is visible at the top of the page
• Confirm that hovering over a plot displays a tooltip with information about the data (N, Min, Median, etc.). Verify that Min and Max have the lowest precision; 5th %, Q1, Median, Q3, 95th %, and Mean have precision to one more decimal place than the lowest precision; and StDev has precision to two more decimal places than the lowest precision.
• Confirm that typing in a number into either the lower limit or upper limit control updates the y-axis domain accordingly.
• Confirm that the lower limit cannot be equal to or greater than the upper limit and the upper limit cannot be equal to or less than the lower limit. Entering this condition should cause the limits to flip automatically and always have the larger limit as the Upper Limit.
• Confirm that a Scale radio control appears next to the y-axis limit controls with two options, linear and log, and that selecting either radio button updates the scale of the y-axis updates as expected.
• Confirm that Y-axis tick labels do not overlap for any measure plotted on a log scale.
• Confirm that the Reset Limits button resets the y-axis to the minimum and maximum values in the data.
• Confirm that the unit value for a given measure is appended to the measure in the Measure dropdown and in the y-axis label.
• Confirm that you can update the Unit (setting: unit_col) to a nonexistent variable name in CAT and re-render the chart, where the chart should behave identically, except units are not appended to the options in the Measures filter, or to the y-axis label.
• Confirm that you can update the start_value setting for a Measure to have the Measure dropdown default to displaying a measure that is not the first one alphabetically in the list.
• Confirm that you can update the start_value setting for a Measure to have a non-existent Measure and chart will handle it and display an existing measure by default instead. Verify that a warning is written to the console explaining that the specified measure does not exist.
• Confirm that you can specify a group variable (ARM, SEX, etc.) as well as a group label (Treatment Group, Sex, etc.) in CAT and that the group labels, and not the group variable names) appear in the Group dropdown, as well as in the legend label.
• Confirm that adding a non-existant group variable/label gets handled by the chart and the group label/name is not actually displayed in the Group dropdown.
• Confirm that group-by labels corresponding to duplicate group-by variables do not appear in the group-by dropdown, even if the labels differ.

The Safety Results Over Time accepts JSON data of the format returned by d3.csv(). The renderer visualizes clinical medical signs data with one row per participant per visit per medical sign plus the required variables specified below.

Data structure

one record per participant per visit per medical sign

Data specification

required and optional variables:

safetyResultsOverTime(element, settings)

a factory to create a custom Webcharts chart object

returns: chart

The most straightforward way to customize the Safety Results Over Time is by using a configuration object whose properties describe the behavior and appearance of the chart. Since the Safety Results Over Time 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 the Safety Results Over Time 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-results-over-time setting as of version 2.3.1.

settings.id_col

string

name of variable that captures unique identifier of participant

default: "USUBJID"

settings.time_settings

object

visit metadata

settings.timesettings.valuecol

string

name of variable that captures visit name

default: "VISIT"

settings.time_settings.label

string

Visit variable label

default: "Visit"

settings.timesettings.ordercol

string

name of variable that captures visit order

default: "VISITNUM"

settings.time_settings.order

array

Visit order

default: none

settings.timesettings.rotatetick_labels

boolean

Rotate tick labels 45 degrees?

default: true

settings.timesettings.verticalspace

number

Rotated tick label spacing

default: 100

settings.measure_col

string

name of variable that captures measure name

default: "TEST"

settings.unit_col

string

name of variable that captures measure unit

default: "STRESU"

settings.value_col

string

name of variable that captures measure result

default: "STRESN"

settings.normalcollow

string

name of variable that captures LLN of measure

default: "STNRLO"

settings.normalcolhigh

string

name of variable that captures ULN of measure

default: "STNRHI"

settings.start_value

string

value of measure to display initially

default: none

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.groups

array

an array of grouping variables and associated metadata

default: none

settings.groups[].value_col

string

Variable name

default: none

settings.groups[].label

string

Variable label

default: none

settings.color_by

string

grouping variable; defaults to first item in groups setting; set to 'srot_none' to display chart without grouping on initialization

default: none

settings.boxplots

boolean

controls initial display of box plots

default: true

settings.outliers

boolean

controls initial display of outliers outside the 5th and 95th percentiles

default: true

settings.violins

boolean

controls initial display of violin plots

default: false

settings.missingValues

array

an array of strings that identify missing values in both the measure and result variables

default: none

settings.visitswithoutdata

boolean

controls display of visits without data for the current measure

default: false

settings.unscheduled_visits

boolean

controls display of unscheduled visits

default: false

settings.unscheduledvisitpattern

string

a regular expression that identifies unscheduled visits

default: "/unscheduled|early termination/i"

settings.unscheduledvisitvalues

array

an array of strings that identify unscheduled visits; overrides unscheduledvisitpattern

default: none

Webcharts settings

The object below contains Webcharts settings as of version 2.3.1 of the Safety Results Over Time.

{
    "x": {
        "column": null,
        "type": "ordinal",
        "label": null,
        "behavior": "flex",
        "sort": "alphabetical-ascending",
        "tickAttr": null
    },
    "y": {
        "column": null,
        "type": "linear",
        "label": null,
        "behavior": "flex",
        "stat": "mean",
        "format": null
    },
    "marks": [
        {
            "type": "line",
            "per": null,
            "attributes": {
                "stroke-width": 2,
                "stroke-opacity": 1,
                "display": "none"
            }
        },
        {
            "type": "circle",
            "per": null,
            "attributes": {
                "stroke": "black",
                "stroke-opacity": 0,
                "fill-opacity": 0
            },
            "values": {
                "srot_outlier": [
                    true
                ]
            },
            "radius": null,
            "tooltip": null,
            "hidden": true
        },
        {
            "type": "circle",
            "per": null,
            "attributes": {
                "stroke": "black",
                "stroke-opacity": 1,
                "fill-opacity": 1
            },
            "values": {
                "srot_outlier": [
                    true
                ]
            },
            "radius": 1.75,
            "tooltip": null,
            "hidden": false
        }
    ],
    "legend": {
        "mark": "square"
    },
    "color_by": null,
    "resizable": true,
    "gridlines": "y",
    "aspect": 3
}