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.

Change the X-axis

The chart contains a toggle that controls the display of the x-axis. Users can view the x-axis data by study day, visit, or visit number. The x-axis displays the data point at which the measure data is collected and manipulating it changes the scale at which the measure data is plotted. Study day, visit, or visit number can be chosen for a given measure, but the chart default is to show the x-axis by study day.

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.

Normal Range Controls

Users can opt to change the method for the normal ranges to the following options: None, LLN-ULN, Standard Deviation, and Quantiles. The default for the normal range controls is set to "LLN-ULN", which is the upper and lower normal range specified in the data. Users may select "None", which will remove the green shading around the normal ranges and will remove the inlier count to the left of the charts. Users may also select "Standard Deviation", which will prompt the user to enter the number of standard deviations they would like to set as the normal range. Altering the default value will change the upper and lower normal range bands in the chart and will change the inlier count to the left of the chart. Users may also select "Quantiles", which prompts the user to enter an upper and lower quantile to set as the normal ranges. Altering the upper quantile will change the upper normal range band in the chart and altering the lower quantile will change the lower normal range band in the chart. Changing the normal ranges may change the number of inliers and the inlier count to the left of the chart will update based on your selections.

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.

View Small Multiples

Clicking a data point will open a listing of small multiples below the chart that contains a detailed listing of all of the participant's records. This linked table contains small charts for each measure captured in the data set as well as the participant's subject ID, age, sex, and race. When the listing appears, the data points selected will appear in a continuous gray line inside of the chart. When a user clicks outside of the selected data point, the gray line disappears along with the detailed listing.

Clicking a data point will perform 2 actions:

• Display the raw data records, including the subject identifier, age, race, sex, and small data renderings of each measure captured in the data set
• Create a gray line to connect the selected data points

Regression Tests

• Confirm that the number and percentage of participants is captured above the chart
• Confirm that selecting the Measure filter changes the distribution of observations
• Confirm that the x-axis filter changes the x-axis to the selected variable
• Confirm that entering a value into the Y-axis Lower Limit box and clicking outside of the box updates the lower limit of the y-axis
• Confirm that entering a value into the Upper Limit box and clicking outside of the box updates the upper limit of the y-axis
• Confirm that selecting the y-axis reset button returns the chart to the default values for that measure
• 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 hovering on a data point displays tooltips for the data point with Subject, value, and visit
• Confirm that date can be added to the standard tooltip with these settings: {tooltipcols: [{label:"Date", valuecol:"DT"}]}
• Confirm that clicking on a data point applies a dark highlight to all of the participant's data points
• Confirm that clicking on a data point opens a detailed listing of a participant's data beneath the chart
• Confirm that when clicking a point that overlaps with another point.
• Confirm that all marks (points, lines) associated with that participant should highlight.
• Confirm that a note should appear beneath the chart detailing which participants have results overlapping with the click mark.
• Confirm that hovering over any ID in the note should highlight that participant in the chart above.
• Confirm that clicking any ID in the note should highlight that participant in the chart above and display that participant's measures below.
• Confirm that with an overlapping point highlighted, changing any control should remove the note but maintain the highlighting of the selected participant.
• Confirm that the selected participant is displayed in a dropdown with the current participant selected
• Confirm that the listing contains subject-level demographic data (Age, Sex, and Race appear by default, can add other Participant Details if wanted)
• Confirm that the listing contains subject-level information about measures and and visits
• Confirm that you can change the selected participant via the dropdown and the new subject should be highlighted in the main chart and the small multiples should update to reflect that participant's data.
• Confirm that a dropdown labeled Normal range method appears in the controls section with four options: None, LLN-ULN, Standard Deviation, and Quantiles.
• Confirm that selecting Standard Deviation displays a text input labeled Number of standard deviations and defaults to 1.96.
• Confirm that selecting Quantiles displays two text inputs, one for the lower quantile and one for the upper quantile, labeled Lower quantile and Upper quantile respectively, that default to .05 and .95.
• Confirm that the x-axis tick labels change rotation angles depending on the x-axis control variable.
• Confirm that a unit variable is appended to each measure in the Measure dropdown.
• Confirm that there is a specified unit variable in the form on the left panel of CAT.
• Confirm that there are values displayed next to each measure under the specified unit variable in the data set.
• Confirm that the chart lines, when the scrolled on, darken significantly. When the user removes his/her cursor from the chart line, it should return to its default state.
• Confirm that when clicking the arrows in the y-axis limit inputs, the limits should increment by a reasonable factor of the y-axis range, or roughly 1/15 of the range. For example, if the range is 150 the increment should be 10 and if the range is 1.5 the increment should be .1.
• Confirm that the minimum and maximum points are not clipped by the edge of the chart canvas and can be clicked.
• Confirm that hovering over a point that overlaps with one or more other points yields an additional line in the tooltip: Number of overlapping point(s) = n.
• Confirm that hovering over a point that does not overlap with any other points does not yield an additional line in the tooltip.

Warnings and Notes

• Confirm that the right side of the webpage between the controls and the chart a note should appear that details how many records with missing and/or non-numeric results were removed.
• Confirm that the test dataset already contains missing records. To test non-numeric records edit ADBDS.csv by adding non-numeric values to the STRESN column.
• Confirm that a warning appears in the console when an invalid initially displayed measure is entered, i.e. one that doesn't appear in the data. (Fill in some dummy text in the "Initially Displayed Measure" field in Settings)
• Verify that after entering the dummy text in the "Initially Displayed Measure" field and reloading the chart, that the Measure dropdown defaults to an existent measure
• Confirm that when entering a valid initially displayed measure but without units, (e.g. Temperature) that a warning appears in the console noting that the specified measure does not include units
• After entering the measure and reloading the chart, verify the Measure dropdown defaults to the specified measure with units

Highlighting

• Confirm that adding the following block to the Settings input will add custom marks to the chart: { "custom_marks": [ { "per": [ "USUBJID", "VISIT", "TEST", "STRESN" ], "type": "circle", "attributes": { "fill": "red", "fill-opacity": 1, "stroke": "black", "stroke-opacity": 1 }, "radius": 4, "values": { "DY": [ "56", "112", "168", "224", "280", "336" ] } } ] }
• Verify that custom marks as well as default marks highlight as expected
• Verify that custom marks as well as default marks can be clicked
• Verify that custom marks maintain their visual characteristics, e.g. fill, stroke, etc.

The Safety Outlier Explorer is initialized with JSON data files that match the format created by d3.csv(). The chart expects an ADaM-esque data structure by default but can be customized to work with any dataset that contains one row per participant per time point per measure and includes the required columns specified below.

Default Chart

The following columns are expected in a data file used to create an instance of the safety outlier explorer. A sample chart using this configuration is found here.

Data Specification

Settings Variable	Description	Default	Required?
id_col	Unique Subject Identifier	USUBJID	Y
timecols[0].valuecol	Visit Name	VISIT	Y
timecols[0].ordercol	Visit Name (N)	VISITNUM
timecols[1].valuecol	Study Day of Visit	DY
measure_col	Name of Measure or Test	TEST	Y
value_col	Result or Finding	STRESN	Y
unit_col	Units	STRESU
normalcollow	Normal Range Lower Limit	STRNLO
normalcolhigh	Normal Range Upper Limit	STRNHI
details[0].value_col	Age	AGE
details[1].value_col	Sex	SEX
details[2].value_col	Race	RACE

Settings

No customization is needed to initialize a chart when the data object contains all default variables above. Just pass an empty object ({}) for settings and initialize the chart like so: safetyOutlierExplorer('body', {}).init(data).

Customized Chart with Queries

The following data specs and chart settings can be used to create a chart with several custom filters, including Sex, Race and Query Status. A sample chart using this configuration is found here.

Data Specification

Settings Variable	Description	Default	Required?
id_col	Unique Subject Identifier	USUBJID	Y
timecols[0].valuecol	Visit Name	VISIT	Y
timecols[0].ordercol	Visit Name (N)	VISITNUM
timecols[1].valuecol	Study Day of Visit	DY
measure_col	Name of Measure or Test	TEST	Y
value_col	Result or Finding	STRESN	Y
unit_col	Units	STRESU
normalcollow	Normal Range Lower Limit	STRNLO
normalcolhigh	Normal Range Upper Limit	STRNHI
details[0].value_col	Age	AGE
details[1].value_col	Sex	SEX
details[2].value_col	Race	RACE
filter	Site ID	SITEID	Y
filter	Treatment Arm	ARM	Y
filter	Sex	SEX	Y
filter	Race	RACE	Y
filter	Query Flag ("Y" for yes)	QUERYFL	Y
custom_marks[0].tooltip	Query Details	QUERYDETAILS	Y

Settings Object

{
     time_cols: [
        {
            value_col: 'VISIT',
            type: 'ordinal',
            label: 'Visit',
            rotate_tick_labels: true,
            vertical_space: 100,
            order_col: 'VISITNUM'
        },
        {
            value_col: 'DY',
            type: 'linear',
            label: 'Study Day',
            rotate_tick_labels: false,
            vertical_space: 0
        }
    ],
    filters: [
        {value_col: 'ARM', label: 'Arm'},
        {value_col: 'SITEID', label: 'Site ID'},
        {value_col: 'SEX', label: 'Sex'},
        {value_col: 'RACE', label: 'Race'},
        {value_col: 'QUERYFL', label: 'Open Query?'}
    ],
    details: [
        {value_col: 'ARM', label: 'Arm'},
        {value_col: 'AGE', label: 'Age'},
        {value_col: 'SEX', label: 'Sex'},
        {value_col: 'RACE', label: 'Race'}
    ],
    custom_marks: [
        {
            per: ['USUBJID', 'VISIT', 'STRESN'],
            type: 'circle',
            attributes: {
                'fill-opacity': 1,
                'stroke': 'red',
                'fill': 'red'
            },
            values: {
                QUERYFL: ['Y']
            },
            tooltip: 'Query Details: [QUERYDETAILS]'
        }
    ],
    multiples_sizing: {
        width: 250,
        height: 75
    }
}

safetyOutlierExplorer(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 line or 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.

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 Outlier Explorer 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 Outlier Explorer 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-outlier-explorer setting as of version 2.3.0.

settings.id_col

string

unique identifier variable name

default: "USUBJID"

settings.time_cols

array

visit metadata

default:

[
  {
    "type": "ordinal",
    "value_col": "VISIT",
    "label": "Visit",
    "order_col": "VISITNUM",
    "order": null,
    "rotate_tick_labels": true,
    "vertical_space": 100
  },
  {
    "type": "linear",
    "value_col": "DY",
    "label": "Study Day",
    "order_col": "DY",
    "order": null,
    "rotate_tick_labels": false,
    "vertical_space": 0
  }
]

settings.time_cols[].type

string

Visit variable data type

default: "ordinal"

settings.timecols[].valuecol

string

Visit variable name

default: "VISIT"

settings.time_cols[].label

string

Visit variable label

default: "Visit"

settings.timecols[].ordercol

string

Visit ordering variable name

default: "VISITNUM"

settings.time_cols[].order

array

Visit order

default: none

settings.timecols[].rotatetick_labels

boolean

Rotate tick labels 45 degrees?

default: true

settings.timecols[].verticalspace

number

Rotated tick label spacing

default: 100

settings.measure_col

string

measure variable name

default: "TEST"

settings.unit_col

string

measure unit variable name

default: "STRESU"

settings.value_col

string

result variable name

default: "STRESN"

settings.normalcollow

string

LLN variable name

default: "STNRLO"

settings.normalcolhigh

string

ULN variable name

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

array

an array of ID-level variables and associated metadata

default:

[
  {
    "value_col": "AGE",
    "label": "Age"
  },
  {
    "value_col": "SEX",
    "label": "Sex"
  },
  {
    "value_col": "RACE",
    "label": "Race"
  }
]

settings.details[].value_col

string

Variable name

default: "AGE"

settings.details[].label

string

Variable label

default: "Age"

settings.tooltip_cols

object

added in v2.4. Takes an array of col/label objects and adds those values to the end of the standard point tooltips. The following would add Date to the tooltip: {tooltip_cols: [{label:"Date",value_col:"DT"}]};

default: null

settings.multiples_sizing

object

width and height of small multiples

settings.multiples_sizing.width

number

Width

default: 300

settings.multiples_sizing.height

number

Height

default: 100

settings.normalrangemethod

string

method for identifying the normal range

default: "LLN-ULN"

settings.normalrangesd

number

the number of standard deviations from the mean with which to define the normal range

default: 1.96

settings.normalrangequantile_low

number

this quantile defines the lower bound of the normal range

default: 0.05

settings.normalrangequantile_high

number

this quantile defines the upper bound of the normal range

default: 0.95

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

array

an array of strings that identify unscheduled visits; overrides unscheduledvisitpattern

default: none

settings.line_attributes

object

an object that defines the line color, thickness, and opacity

settings.line_attributes.stroke

string

Line Color

default: "black"

settings.line_attributes.stroke-width

number

Line Thickness

default: 0.5

settings.line_attributes.stroke-opacity

number

Line Opacity

default: 0.75

settings.point_attributes

object

an object that defines the point color, radius, and opacity and its outline color, thickness, and opacity

settings.point_attributes.stroke

string

Point Outline Color

default: "rgb(102,194,165)"

settings.point_attributes.stroke-width

number

Point Outline Thickness

default: 0.5

settings.point_attributes.stroke-opacity

number

Point Outline Opacity

default: 1

settings.point_attributes.fill

string

Point Color

default: "rgb(102,194,165)"

settings.point_attributes.radius

number

Point Radius

default: 3

settings.point_attributes.fill-opacity

number

Point Opacity

default: 1

Webcharts settings

The object below contains each Webcharts setting as of version 2.3.0.

{
    x: {
        column: null, //set in syncSettings()
        type: null, //set in syncSettings()
        behavior: 'raw'
    },
    y: {
        column: null, //set in syncSettings()
        stat: 'mean',
        type: 'linear',
        label: 'Value',
        behavior: 'raw',
        format: '0.2f'
    },
    marks: [
        {
            per: null, //set in syncSettings()
            type: 'line',
            attributes: {
                'clip-path': 'url(#1)'
            },
            tooltip: null //set in syncSettings()
        },
        {
            per: null, //set in syncSettings()
            type: 'circle',
            attributes: {
                'clip-path': 'url(#1)'
            },
            tooltip: null //set in syncSettings()
        }
    ],
    resizable: true,
    margin: { right: 20 }, //create space for box plot
    aspect: 3
}