User Requirements

Filter by Prevalence

This is a text box feature which is used to filter out all adverse events below the percentage entered. The default is 0%, but the default value can be adjusted according to the user's needs. Users can type any alphanumeric value into this box. Values must be numeric for the filter to work. After hitting Enter or clicking outside the box, the Explorer will hide the data rows where the prevalence for all groups is below the threshold entered. If any group has a prevalence at or above the threshold entered, it will be displayed on screen with all nested categories shown. To return to the default view, the user must either refresh the page or enter 0 into the filter box and again hit Enter or click outside the box.

Filter by Serious Event

This menu is used to filter by whether or not an event is serious in the data set. The default is set to include all events.

Filter by Severity

This menu is used to filter by adverse event severity level in the data set. The current severity levels captured are mild, moderate, and severe. The default is to display all severity levels.

Filter by Relationship

This menu is used to filter by the relatedness categories in the data set. The options included in the chart are not related, unlikely related, probably related, definitely related. The default is to display all relationships.

Filter by Outcome

This menu is used to filter by the outcome categories in the data set. The options included in the chart are recovered; resolved without sequelae; resolved, recovered; and resolved with sequelae. The default is to display all outcomes.

Toggle Between Participant and Event Summaries

This toggle option allows the user to view the adverse events data by participant or event. Summarizing AEs by participant presents the number of participants who experienced an AE of the corresponding category at least once by group. Summarizing AEs by event presents the number of events of the corresponding category by group. The chart defaults to display the participant data, which displays the adverse events.

Search

The Search box is used to search the category column of the table for terms of interest. Users can type any alphanumeric term into this box. After hitting Enter or clicking outside the box, the Safety Explorer will display only the categories that contain the search term entered. The search terms will also be highlighted in yellow within the category column. Text will also display next to the Search box indicating the number of categories returned with that search term. If there are no results matching the term entered, text will display next to the Search box indicating that no categories were returned with a matching search term. The table display will not change if there are no matches in the search.

Reset Search

To reset to the default Explorer view after conducting a search, users can click on the red X button in the alert bar which displays next to the Search box. Alternatively, users can clear the text in the Search box and hit Enter or click outside the box.

Hover

By moving a mouse cursor over certain sections of the table, users can display metadata for some variables. Hovering over the ‘E’ superscript beside one of the filter labels will display an explanation of an event filter. Hovering the cursor over a particular row will highlight the row in gray. Hovering over a value in a treatment group will display the number of participants affected out of n. Hovering over a colored data point in the AE Rate by Group column will present the percentage value for the group. Hovering over a diamond in the Difference Between Groups column will perform two actions:

• Display the raw data (numerator and denominator) used to calculate the adverse event prevalence percentage for each row in the table for the selected groups.
• Display the two treatments compared by percentage and the overall difference between them.

AE Rate by Group Column

The column following the Groups columns shows the rate of an adverse event by group. Each group is represented by a color-coded dot that corresponds to the color of the treatment group. The rate of the event for each group is shown on a scale by percentage. When hovering over a colored dot, the exact percentage appears for the group.

Difference Between Groups Column

The column on the right-hand side of the table shows a graphical representation of the difference between groups in the data set. Group comparisons are represented with a color-coded diamond that corresponds to the colors of the treatment groups being compared. When hovering over a diamond, the ratios and percentages of occurrence for the event appears for the compared groups in addition to the difference between the two groups.

Show nested rows for a single category

The preferred terms for a given system organ class are hidden on the default view. To show the hidden preferred terms rows, click on the '+' to the left of a given system organ class in the category column. This will expand the table to show the nested rows for this system organ class.

Hide nested rows for a single category

The preferred terms for a given system organ class are hidden on the default view. After a category has been expanded, you can hide the nested rows by clicking on the '-' to the left of a given system organ class in the category column. This will collapse the table to hide the nested rows for this system organ class.

Show Details View

Clicking on a category or any of its preferred terms will open the Show Details view. This view displays the raw data for every adverse event under that system organ class and/or preferred term.

Return to the Summary View

The Return to the Summary View button is only visible if users have clicked on a category or preferred term to show the details view. Clicking on this button returns users to the default Safety Explorer view.

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.

View Treatment Groups

The chart can be configured to show or hide any of the treatment groups found in the data. Showing only 1 treatment group will automatically hide the 'Difference Between Groups' column and the 'Total' column.

Download the data

By entering the following settings {"validation": true}, users can download the data as a CSV. The CSV file will contain all of the data if no filters have been utilized. If filters have been used, the CSV file will contain the resulting data. The CSV download will be named using the following convention: major term-minor term-summary variable. The summary variable can either be 'Participant' or 'Event", depending on what the user summarized the data by using the toggle in the menu.

Regression Tests

Filters and Options

• Confirm that clicking on the "+" to the left of each category name expands the dataset
• Confirm that clicking on the “-“ to the left of each category name after it is expanded collapses the dataset
• Type a value into the search box and confirm that the table updates to only show the categories that match the search term. Matching terms should be highlighted in bold, regal orange.
• Confirm that the number of matching terms displays to the left of the search box
• Delete the entered value from the search bar and confirm that table resets
• Confirm that filters on events (e.g. Severity) are working as expected by filtering and then clicking on a category to display the underlying data listing to confirm that the data displayed matches the filtering
• Confirm that entering a minimum prevalence will filter the data based on the entered threshold
• Confirm that summarizing by 'participant' displays the number of participants who experienced an AE of the corresponding category by group
• Confirm that summarizing by 'event' displays the number of events of the corresponding category by group
• Ensure that the aeexplorer looks good in viz-library
• Confirm there is no column overlapping when bootstrap is toggled off/on
• Confirm that the "Filter by prevalence" field no longer accepts letters in the prevalence input, and that the up and down buttons work as expected
• Confirm that the graphic updates after each keystroke in the search and filter by prevalence inputs (instead of after focus leaves the input altogether)
• Confirm that if there are no AEs that match the current filters - the error message thrown says "Error: No AEs found for the current filters. Update the filters to see results."

Hovering

• Hover over a value in a treatment group to see the number of participants affected out of n
• Hover over a value in ‘AE Rate by group’ to see the percentage of participants affected by group
• Hover over a value in ‘Difference Between Groups’ to see two treatments compared and the overall difference between them. This will also highlight the bar containing the value in gray and reveal the count and percentage of both groups under their treatment name
• Hover over the ‘E’ superscript beside one of the filter labels to display an explanation of an event filter

Detailed Listing

• Confirm that you can view a detailed listing of events by clicking on the category name of a given row in the table
• Confirm that the ‘Return to the Summary View’ button brings you back to the original summary view.
• Confirm that the section labeled ‘The listing is filtered as shown:’ displays the filters that were selected in the original summary view
• Confirm that there is a sentence in the header stating ‘Details for x category name records’ that displays both the correct ‘x’ value for the number of records in the listing and ‘category name’
• Ensure details listing appears as normal before adding anything.
• Add a details object, like in the example above, that has columns with and without a label and ensure that they show up by themselves and with the proper label when you view the details listing (see this issue for an example of labels: https://github.com/RhoInc/aeexplorer/issues/105)
• Confirm in CAT with the following settings: { defaults:{webchartsDetailTable:true}} that the detail table view (accessed by clicking the label of any row in the summary table), is rendered using a webcharts table, and that sort, search, pagination and export work as expected.

Downloading Data

• Confirm that entering the following settings in the CAT will show the option to download the data file: {"validation": true}
• Confirm that when downloading a CSV, the file will save as major term - minor term - participant/event
• Confirm that when downloading a participant CSV, "participant" appears in the title
• Confirm that when downloading an event CSV, "event" appears in the title
• Confirm that filtering the data will appear as filtered in the CSV download

Settings

• Confirm that the following settings set the serious event filter to ‘Y’ and make it the only filter to be displayed by default: {"validation": true ,"variables": {"filters": [ {"value_col": "AESER" ,"label": "Srs?" ,"type": "event" ,"start": ["Y"]} ] } }
• Confirm that the following settings summarize the data by participant on default: {"validation": true ,"defaults": {"summarizeBy": "participant"} }
• Confirm that the following settings summarize the data by event on default: {"validation": true ,"defaults": {"summarizeBy": "event"} }
• Confirm that the following setting only shows treatment group totals and hides the 'Difference Between Groups' column: {"defaults":{"totalCol":true,"groupCols":false}}
• Confirm that the following setting only shows the placebo group and hides the 'total' and 'Difference Between Groups' columns: {"groups":["Placebo"]}
• Confirm that when grouping by RACE, yellow is no longer the color that appears
• Confirm that adding 2+ values to each component (id, major, minor and groups) of the variableOptions array adds a new control.
• Confirm that multiple filters are created if more than one variableOptions array is provided, and that they both work as expected.
• Confirm that the new variableOption controls work before and after filtering, searching, and changing the summarizeBy option.
• Confirm that the value for the default variable appears in the variable control even if it is not specified in config. That is, ARM appears in the groups control with these settings: { variables:{group:"ARM"}, variableOptions:{ group:["RACE","SEX"] }, };
• Confirm in CAT that margins are drawn for the dot plot when plotSettings.margin is specified. Just tweak the following settings object, and confirm that the margin changes as expected: {plotSettings: {margin: {left: 40, right: 40}}}

Data Guidelines

AE Explorers are initialized using JSON data files that match the format created by d3.csv(). The chart requires a data set with one record per adverse event and optionally with placeholder rows for participants who didn't experience any adverse events over the course of the study. The chart uses column names from the ADAM data standard by default, but can be customized to work with any column names as long as the data structure is as expected.

Default Chart

The following table describes chart settings and data specifications required to create an AE Explorer. A sample chart using this configuration is found here.

Data Specification

Settings Object

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: aeTable("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 Object

const settings = {
        'variables': {
            'id': 'USUBJID',
            'major': 'AEBODSYS',
            'minor': 'AEDECOD',            
            'group': 'ARM',
            'filters': [
                { 'value_col': 'AESER', 'label': 'Serious?', 'type': 'event' }, 
                { 'value_col': 'AESEV', 'label': 'Severity','type': 'event' }, 
                { 'value_col': 'AEREL', 'label': 'Relationship','type': 'event' }, 
                { 'value_col': 'AEOUT','label': 'Outcome','type': 'event' }, 
                { 'value_col': 'SITEID', 'label': 'Site ID','type': 'participant' }, 
                { 'value_col': 'ARM', 'label': 'Arm','type': 'participant' },
                { 'value_col': 'SEX', 'label': 'Sex','type': 'participant' },
                { 'value_col': 'RACE', 'label': 'Race','type': 'participant' },
                { 'value_col': 'QUERYFL','label': 'Open Query?','type': 'event' }
            ]
        },
        'defaults': {
            'placeholderFlag': {'value_col': "AEBODSYS", 'values': [""] },
            'maxPrevalence': 10,
            'maxGroups': 7,
            'totalCol': true,
            'diffCol': true,
            'prefTerms': false 
        },
        'plotSettings': { 'h': 15,
            'w': 200,
            'margin': { 'left': 40, 'right': 40 },
            'diffMargin': { "left": 5, "right": 5 },
            'r': 7 }
        };

aeTable(element, settings)

A factory to create a custom aeTable object.

returns: chart

Overview

The most straightforward way to customize an AE Explorer is by using a settings object whose properties describe the chart's behavior and appearance. Parameters for the settings object are described in detail below. All defaults can be over-written by users when creating an AE Explorer.

settings

object

Objects passed to aeTable() which controls the settings and appearance of the output.

settings.variables

object

Objects that specify how to map columns from the data file to the chart settings.

variables.id

string

Participant ID variable name

default: 'USUBJID'

variables.major

string

Higher-level term variable name

default: 'AEBODSYS'

variables.minor

string

Lower-level term variable name

default: 'AEDECOD'

variables.group

string

Group variable name, each value of which displays in its own column in the AE Explorer unless settings.groups is defined

default: 'ARM'

variables.details

array of objects

An array listing each variable to display in the detail listing; if empty or unspecified, all variables in input data file will appear in detail listing

default: []

details[].value_col

character

Field in the data object to be in the details table

details[].label

character

Label for the details table header

variables.filters

array of objects

An array listing each variable with which to filter the data

default:

[   
  {
    'value_col': 'AESER',
     'label': 'Serious?',
     'type':'event',
     'start':[]
  },
  {
    'value_col': 'AESEV',
    'label': 'Severity',
    'type':'event',
    'start':[]
  },
  {
    'value_col': 'AEREL',
    'label': 'Relationship',
    'type':'event',
    'start':[]
  },
  {
    'value_col': 'AEOUT',
    'label': 'Outcome',
    'type':'event',
    'start':[]
  }
]

filters[].value_col

character

Field in the data object to be used for the filter; all values treated as categorical

filters[].label

character

Label for the filter

filters[].type

character

Variable type, event-level or participant-level, e.g.

var settings = 
filters: [
  {'value_col': 'SITEID','label': 'Site ID','type': 'participant' },
  {'value_col': 'AESER','label': 'Serious AE?','type': 'event' }
]

filters[].start

array of characters

Initial values on which the input sata will be filtered; no values are filtered and all values are shown if start is empty or false-y

settings.variableOptions

object

Allows users to specify options for the 4 key data mapping settings (id, major, minor, group) defined in the variable object above. Whenever more than one option is specified for a setting, an interactive control is added allowing users to update the chart after it is drawn. Added in v3.3.0.

default:

 variableOptions: {
        id: [],
        major: [],
        minor: [],
        group: []
    },

settings.groups

array of objects or strings

An array specifying which levels of settings.variables.group will appear as columns in the AE Explorer. If more levels are specified than config.defaults.maxGroups levels, the chart will throw an error and will not render. The array elements should be formatted as either strings (e.g. ["Placebo", "Treatment A"]) or objects with a key value matching the group level (e.g. [{key:"Placebo"},{"key":"Treatment A"}])

default: [] (all possible levels are used)

settings.defaults

An object containing default settings affecting the appearance of the tables and defining other miscellaneous settings

defaults.maxPrevalence

number

Filters out any higher- and lower-level rows without at least one group rate above specified value

default: 0

defaults.diffCol

boolean

Specifies whether or not to render a column of graphical incidence differences

default: true

defaults.totalCol

boolean

Specifies whether or not to render a column of overall rates across all groups

default: true

defaults.groupCols

boolean

Specifies whether or not to render columns for each group

default: true

defaults.prefTerms

boolean

Specifies whether or not to initially display all lower-level rows

default: false

defaults.maxGroups

number

Maximum number of group levels allowed; display gets ugly with more than a handful of columns and browser performance deteriorates quickly (and may lock up) after a few dozen levels

default: 6

defaults.placeholderFlag

object

Object that specifies how to identify placeholder rows for participants with no AEs

default: {'value_col':"AEBODSYS", 'values':["NA"]}

defaults.summarizeBy

character

Specifies whether to show "participant" rates or "event" rates by default

default: "participant"

defaults.webchartsDetailTable

boolean

Specifies whether to renderer the details table using a webcharts table with search and sort capabilities (as opposed to the simple default table without interactivity). Added in v3.3.0.

default: false

settings.plotSettings

object

Object to specify the appearance of the plots embedded in the table rows

plotSettings.h

number

Height of the plot svg in pixels

default: 15

plotSettings.w

number

Width of the plot svg in pixels

default: 200

plotSettings.r

number

Radius of the plotted points in pixels

default: 7

plotSettings.margin

object

Object specifying the dot plot margins

default: {'left':40, 'right':40}

plotSettings.diffMargin

object

Object specifying the margins for the difference diamonds plot

default: {'left':5, 'right':5}

settings.validation

boolean

Adds a link to download the summarized data in a comma-separated format, which exports a file named "settings.variables.major-settings.variables.minor-[current value of Summarize by control].csv"

default: false