Functional Specs

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 range of the measure and the number of observations collected for this variable.

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.

Normal Range Function

This feature highlights the normal ranges for the selected measure by displaying a gray rectangle behind the data. This rectangle represents the normal range for that measure and data that falls within the upper and lower limits of the range contains records of participants who are associated with results that are considered normal. Normal ranges are not shown by default , but the option can be activated by checking the normal ranges check box above the chart. If the data does not cite a normal range for a measure, the option to activate the normal range function is not available and the checkbox disappears.

Set X-axis Limits

Users are able to adjust the lower limit of the x-axis by manipulating the input within the Lower Limit box. Users are able to adjust the upper limit of the x-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 an x-axis limit, the x-axis on the chart below the controls will reflect the change.

Reset X-axis limits

Users can change the upper and lower x-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.

Hover

By moving a mouse cursor over a bar in the chart, users can display metadata for some variables. Hovering the cursor over a particular bar will display the number of records for the measure in that bar's range in a statement below the chart.

Linked Table

Clicking on a bar in the chart will open a table below the chart that contains a detailed listing of participant records. This linked table contains a standard set of default columns that appear consistently across all filters. When a bar is clicked the other available bars lighten, the table header defines the data included in the table, and the records appear in a table below the chart. When a user clicks outside of a bar, the detailed table disappears and the table header will prompt the user to "Click a bar for details."

Clicking on a bar will perform 3 actions:

• Display the raw data records, including the subject identifier, result, lower limit of normal, and upper limit of normal
• Lighten all of the bars not contained in the table
• Display the number of records for the measure underneath the chart

Regression Tests

Controls

• Confirm that if the Measure filter is changed, the distribution of observations change
• Confirm that different measures reflect different precisions, appropriate to their values
• View x of x participants note at the top of the page: check that it updates when filters are applied
• Confirm the ability to apply normal ranges by checking the Normal Range box: a range rectangle should appear for each participant
• Confirm that applying normal ranges does not change the axes in the chart.
• Confirm that when normal ranges are applied, there is a tooltip displayed beside "Normal Range".
• Confirm that typing in a number into either the lower limit or upper limit control updates the x-axis domain accordingly and the chart is redrawn to match the new limits.
• 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 the Reset Limits button resets the x-axis to the minimum and maximum values in the data.
• Confirm that the y-axis changes when the x-axis controls are modified
• Confirm that other controls (filtering, changing measures, etc.) work logically when using a custom x-axis. Example of an added filter: {"filters":[{"value_col":"SITE","label":"Site"}]}
• Confirm that with a filter added, such as SITE, the x-axis does not change when changing the Site filter but leaving the same Measure selected. The x-axis domain should only change when the measure changes.
• 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 a warning is thrown to the console when the user specifies an invalid starting measure, and that the chart then defaults to the first measure in the data, when sorted alphabetically. (To check: set Initial Medical Sign to an invalid value, render the chart, and view the console).
• Confirm that if you set Initial Medical Sign to an existent value (like IgE) and render, then the chart defaults to the specified measure, but with units attached.
• Confirm that if you set Unit to a non-existent value, then the chart will render, but the units no longer appear beside the Measure names in the filter, or along the x-axis.
• 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.
• Verify a control labeled Quantity appears in the Bins group of controls.
• Confirm changing the Quantity sets the Algorithm control to Custom and sets the Width input to the range of the data divided by the number of bins
• Confirm that changing the input to a value less than 1 is not valid and get's rounded to 1 when you tab out
• Confirm that when you enter a non-integer and tab out, the input rounds to the nearest integer
• Verify a new control labeled Algorithm appears in the Bins group of controls with these options: Square-root choice, Sturges formula, Rice Rule, Scotts normal reference rule, Freedman-Diaconis choice, Shimazaki and Shinomotos choice, Custom
• Confirm that if you select an algorithm other than "Custom", the following occurs: The algorithm returns the number of bins and the width of each bin, the Quantity and Width inputs update accordingly, the info icon updates with a link to an description of the algorithm
• Confirm the number of bins in the Quantity input matches the number of bars in the chart
• Confirm the width of each bin in the Width input matches the width of the bars in the chart
• Verify that a control labeled X-axis Ticks appears with two radio buttons: linear and bin boundaries
• Confirm that when set to linear, the x-axis ticks should be spaced evenly along the x-axis but not necessarily at the boundaries between the bars/bins
• Confirm that when set to bin boundaries, the x-axis ticks should appear at the boundaries between each bar/bin

Chart

• Confirm a description of the range and # of records appears below the chart when the user mouses over a bar
• Confirm that you can view a detailed listing of measure records by clicking on a bar in the chart: the number of records for the measure and selected range should appear underneath the chart
• Confirm that the bars are not cut off on either end of the chart
• Confirm that a value representing the lower and upper limit of each bar should appear to the left and right at the bottom of each bar on the x-axis when the bin boundaries radio button is selected.
• Confirm that when using a filter, the number of bins/columns displayed updates depending on the number of records displayed. (To check this: 1. Add a filter for VISIT. 2. Render the chart. 3. Flip through the VISIT dropdown and view the columns in the chart).
• Confirm that when data is filtered by something other than Measure, the Zoom button can be used to set the x-domain to the range of the filtered data.
• Confirm that hovering/clicking anywhere in the chart highlights the bar underneath the mouse vertically, regardless of whether the mouse is over the bar itself.
• Confirm that the custom mark for x domain when drawing the bars with the range of 0 is fixed via the Zoom button. (to test: 1. Add a USUBJID filter. 2. Select 01-021 in the filter dropdown. 3. Hit the zoom button - the bar should be centered on the underlying value (~47) and have a "normal" width, e.g. not too thin, not too thick, but just right.)
• Confirm that when 2 empty bins are next to each, tick labels still appear (Settings you can try to test: Alkaline phosphatase, X-Axis limits 1.62/2.87 Bins: 14/.09, can use linear or bin boundaries)
• Confirm that setting the x-axis limits wider than the defaults still has the bin boundaries extend to the edge of the charting canvas rather than to the edge of the histogram
• Confirm that the linear radio button is checked on default and that the x-axis displays evenly spaced ticks, both in distance and in range
• Confirm that the footnote that appears when hovering over a bar or after clicking a bar should detail the number of records as well as the range of values that bar encompasses (Ex: Click a bar: Table displays 34 records with Alkaline phosphatase (ALP) (μkat/L) values greater than or equal to 1.53 and less than 1.72
• Confirm that when you add a huge outlier to the data, the x-axis tick labels do not overlap (Ex. like 10,000 for Albumin)
• Use these test notes for the following 4 tests TEST NOTES
• Verify an annotation appears in the top right of the chart labeled Normality: with a p-value and an info icon
• Verify hovering over the p-value displays information about the statistical test
• Verify clicking the info icon opens the relevant Wikipedia page
• Verify the p-value updates upon selecting a different measure

(use these test notes for the following 4 tests and make sure the version is dev-v2.5.0 TEST NOTES)

• Verify a dropdown labeled Group by appears to the right of the histogram
• Select an option from the Group by dropdown and verify a histogram appears for each value of the selected option
• Confirm that selecting None from the dropdown makes the grouped histograms disappear
• Verify the grouped histograms update upon selecting a different measure

(Use these test notes for the following 2 tests and make sure the version is dev-v2.5.0 TEST NOTES)

• Confirm that the vertical sidebar appears after zooming in.
• Scroll to the bottom and mouse over and out of the chart and verify the page does not re-position on mouse-out.

(Use these test notes for the following 5 tests and make sure the version is dev-v2.5.0 TEST NOTES

• Select an option from the Group by dropdown
• Verify an annotation appears in the top right of the each grouped histogram chart with a p-value and an info icon
• Verify hovering over a p-value displays information about the statistical test
• Verify clicking an info icon opens the relevant Wikipedia page
• Verify the p-values update upon selecting a different measure

(Use these test notes for the following 9 tests and make sure the version is dev-v2.5.0 TEST NOTES

• Select an option from Group by dropdown
• Verify hovering over a bar in a grouped histogram highlights the corresponding bar in the main histogram and all other grouped histograms
• Verify hovering over a bar in the main histogram highlights the corresponding bar in all grouped histograms
• Verify hovering over a bar in the grouped histogram displays information about the group in the footnote beneath the main chart
• Verify clicking a bar in a grouped histogram displays a listing of records corresponding to only that group
• Verify clicking a bar in a grouped histogram increases the opacity of the clicked bar and reduces the opacity of all bars in the main chart, in the other grouped charts, and in the clicked chart
• Verify clicking a bar in the main chart after clicking a bar in a grouped chart resets the opacity of the previously clicked bar
• Verify clicking a bar in a grouped chart after clicking a bar in the main chart resets the opacity of the previously clicked bar
• Verify clicking the underlined footnote beneath the main chart resets the opacity of all bars and removes the listing

(Use this setting for the following test and make sure the version is dev-v2.5.0 TEST NOTES

• In CAT underneath 3. Customize the Chart, click the radio button labeled text. Verify a setting appears in the settings object named displaynormalrange.

(Use these test notes for the following 2 tests and make sure the version is dev-v2.5.0 TEST NOTES )

• Select an option from the Group by dropdown. Click bars in the grouped charts and in the main chart and try to get two bars highlighted.
• Confirm the 2 bars don't highlight.

(Use this setting for the following test and make sure the version is dev-v2.5.0 TEST NOTES )

• Verify a disclaimer appears in the tooltip of the info icons of the annotated p-values in both the main chart and the grouped histograms with this text: Caution: This graphic has been thoroughly tested, but is not validated.

(Use these settings for the following 2 tests and make sure the version is dev-v2.5.0 TEST NOTES )

• Select Aminotransferase, alanine (ALT) (pkat/L) from the Measure dropdown.
• Verify in the main chart the p-value is formatted with a less than sign
• Verify in the Treatment B grouped histogram the p-value is formatted with a greater than sign

Data Listing

• Confirm # of records is visible in data listing header
• Confirm the bottom of the data listing tab has pagination links
• Confirm each default page displays 10 records
• Confirm “>” pagination arrows link data records to the next page
• Confirm “<” pagination arrows link data records to the previous page
• Confirm pagination “>>” double arrows link data to the last pages of the data record
• Confirm pagination “<<” double arrows link data to the first pages of the data record
• Confirm that Search works to filter the data displayed in the listing
• Confirm that Sort works in the listing by clicking on column headers
• Confirm that you can export the displayed data to a csv via via the Export: CSV button
• Confirm data listing resets when a new filter is applied

The Safety Histogram 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:

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 Object

  {filters:
                [   {value_col: 'VISIT',    label: 'Visit'},
                ,   {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: 'USUBJID'     , label: 'Subject ID'},
                {value_col: 'SITEID'      , label: 'Site ID' },
                {value_col: 'SEX'         , label: 'Sex'    },
                {value_col: 'RACE'        , label: 'Race'   },
                {value_col: 'VISIT'       , label: 'Visit'  },
                {value_col: 'DY'          , label: 'Study Day' },    
                {value_col: 'STNRLO'      , label: 'LLN' },
                {value_col: 'STRESN'      , label: 'Result'}, 
                {value_col: 'STNRHI'      , label: 'ULN' },
                {value_col: 'STRESU'      , label: 'Units' },
                {value_col: 'QUERYDETAILS', label: 'Query Details'}]
            }

safetyHistogram(element, settings)

a factory to create a custom Webcharts chart object

returns: chart

The most straightforward way to customize the Safety Histogram 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 Histogram 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-histogram setting as of version 2.3.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.unit_col

string

a variable that contains the units of each medical sign

default: "STRESU"

settings.normalcollow

string

a variable that contains the lower limit of normal of the medical sign

default: "STNRLO"

settings.normalcolhigh

string

a variable that contains the upper limit of normal of the medical sign

default: "STNRHI"

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

settings.start_value

string

the name of the initially displayed medical sign; defaults to the first measure in the data

default: none

settings.normal_range

boolean

a boolean that dictates whether the normal range control will be generated

default: true

settings.displayNormalRange

boolean

a boolean that dictates whether the normal range will be displayed initially

default: false

Webcharts settings

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

{
    "x": {
        "type": "linear",
        "column": null,
        "label": null,
        "domain": [
            null,
            null
        ],
        "format": null,
        "bin": null
    },
    "y": {
        "type": "linear",
        "column": null,
        "label": "# of Observations",
        "domain": [
            0,
            null
        ],
        "format": "1d",
        "behavior": "flex"
    },
    "marks": [
        {
            "per": [],
            "type": "bar",
            "summarizeY": "count",
            "summarizeX": "mean",
            "attributes": {
                "fill-opacity": 0.75
            }
        }
    ],
    "aspect": 3
}