Configuration - SafetyGraphics/hep-explorer GitHub Wiki

Configuration Overview

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 eDish 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 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

settings.id_col

string

Unique subject identifier variable name

default: "USUBJID"

settings.value_col

string

result variable name

default: "STRESN"

settings.measure_col

string

measure variable name

default: "TEST"

settings.unit_col

string

measure unit variable name

default: "STRESU"

settings.normal_col_low

string

LLN variable name

default: "STNRLO"

settings.normal_col_high

string

ULN variable name

default: "STNRHI"

settings.studyday_col

string

Study day variable name

default: "DY"

settings.visit_col

string

Visit variable name

default: null

settings.visitn_col

string

Visit number variable name

default: null

settings.exposure_stdy_col

string

Exposure start day variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXSTDY'

settings.exposure_endy_col

string

Exposure end day variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXENDY'

settings.exposure_trt_col

string

Exposure treatment name variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXTRT'

settings.exposure_dose_col

string

Exposure dose variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXDOSE'

settings.exposure_dosu_col

string

Exposure dose variable name. Note: setting is ignored if exposure data domain is not provided.

default: 'EXDOSU'

settings.baseline

object

Object defining the baseline visit of the study.

settings.baseline.value_col

string

Column containing the baseline visit data

default: "DY"

settings.baseline.values

array

One or more values found in settings.baseline.value_col indicating that the record represents the baseline visit.

default: [0]

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

boolean

If true filters are set up to allow multiple selections.

default: true

settings.details

array

an array of ID-level variables and associated metadata

default: Automatically uses values specified in settings.id_col, settings.group_cols and settings.filters

settings.details[].value_col

string

Variable name

default: Automatically uses values specified in settings.id_col, settings.group_cols and settings.filters

settings.details[].label

string

Variable label

default: Automatically uses values specified in settings.id_col, settings.group_cols and settings.filters

settings.group_cols

array

an array of grouping variables and associated metadata

default: none

settings.group_cols[].value_col

string

Variable name

default: none

settings.group_cols[].label

string

Variable label

default: none

settings.analysisFlag

object

Flags records for use in the eDish and mDish calculations.

default: none

settings.analysisFlag.value_col

string

Indicates which column should be used to flag rows for inclusion eDish and mDish analysis

default: none

settings.analysisFlag.values

array or string

Indicates which values should be used to flag rows for inclusion eDish and mDish analysis

default: none

settings.calculate_palt

object

Indicates whether PALT should be calculated.

default: none

settings.paltFlag

object ** Removed in v1.4.2 **

Flags records for use in the PALT calculations. Only used if settings.calculate_palt is true.

default: none

settings.paltFlag.value_col

string ** Removed in v1.4.2 ** Indicates which column should be used to flag rows for PALT analysis.

default: none

settings.paltFlag.values

array or string ** Removed in v1.4.2 **

Indicates which values should be used to flag rows for for PALT analysis.

default: none

settings.measure_values

object

An object defining the data values from measure_col for the lab measures used in eDish evaluations.

default:

  {
    ALT: 'Aminotransferase, alanine (ALT)',
    AST: 'Aminotransferase, aspartate (AST)',
    TB: 'Total Bilirubin',
    ALP: 'Alkaline phosphatase (ALP)'
  },

settings.add_measures

boolean

If true, all unique values from settings.measure_col are automatically added to the settings.measure_values object. Can be paired with the "all" option for settings.x_options, settings.y_options and settings.point_size_options to allow for flexible interactive axis controls using all available data. Added in v1.2.

default: false

settings.x_options

array or string

Specifies variable options for the x-axis using the key values from settings.measure_values (e.g. "ALT"). When multiple options are specified, a control allowing the user to interactively change the x variable is shown. Specifying 'all' (added in v1.2) uses all options from measure_values.

default: 'all'

settings.x_default

string

String indicating the starting value for the x-axis when the chart is loaded. Must be an option from the settings.x_options array. First item in the settings.x_options array is used if an invalid option is specified.

default: 'ALT'

settings.y_options

array or string

See settings.x_options.

default: ['TB']

settings.y_default

string

See settings.x_default.

default: 'TB'

settings.point_size_options

array or string

See settings.x_options. For point size, options for 'Uniform' (the default) and 'rRatio' are automatically added to the control in addition to the users selections.

default: 'all'

settings.point_size_default

string

See settings.x_default.

default: "Uniform"

settings.imputation_methods

array of string

Specifies how data should be imputed for each measure specified in config.measure_values. Valid options are:

  • "data-driven" is the default and it takes 0 values and sets them to 0.5 times the minimum value for the measure across all participants/time points
  • "user-defined" takes all values less than config[key].imputation_value and sets then to 0.5 times config[key].imputation_value. (The config.imputation_value option is ignored otherwise)
  • "drop" means all 0 values are dropped.

default:

{
  ALT: 'data-driven',
  AST: 'data-driven',
  TB: 'data-driven',
  ALP: 'data-driven'
}

settings.imputation_values

number

used as described above when config.imputation_method is set to "user-defined"

default: none

settings.cuts

object

Object defining default cut-points for each measure defined in config.measure_values for each of the different types of supported eDish displays defined in config.display. If config.measure_values is customized to add additional key measures, then values from cuts.defaults are used unless the user provides values using the format shown below.

default:

{
  TB: {
    relative_baseline: 4.8,
    relative_uln: 2
  },
  ALP: {
    relative_baseline: 3.8,
    relative_uln: 1
  }
}

settings.cuts.defaults

object

Default cut values to be used when no user settings are provided. Added in v1.2.

default:

{
  relative_baseline: 3.8,
  relative_uln: 3
}

settings.display

"string"

Defines the display type used on the eDish scatter plot on initial view. Can be changed by the user once the chart is rendered. Valid options are:

  • "relative_uln" which shows the standard eDish view where values are scaled relative to the Upper Limit or Normal
  • "relative_baseline" which shows the mDish view where values are scaled relative to the participants baseline value

Note: Support for an "absolute" option used to show the raw values for the measure was removed prior to the v1 release.

settings.display_options

array

Defines nice labels for the different display options.

default:

  display_options: [
        { label: 'Upper limit of normal adjusted (eDish)', value: 'relative_uln' },
        { label: 'Baseline adjusted (mDish)', value: 'relative_baseline' }
    ]

settings.measureBounds

array of number

Sets upper and lower percentiles used for defining outlier in the "Lab Summary Table" in the participant details section.

default: [0.01,0.99]

settings.populationProfileURL

string

URL linking to additional charts related to population level analysis

default: none

settings.participantProfileURL

string

URL linking to additional charts related to population level analysis. Will need an update in a future release to allow dynamic links for different participants.

default: none

settings.visit_window

number

Default visit window used to highlight eDish points where x and y measures occurred within the specified number of days. Editable by user after render.

default: 30

settings.r_ratio_filter

boolean

Specifies whether the R Ratio filter should be shown. R ratio is defined as: (ALT value/ULN for ALT) / (ALP value/ULN for ALP).

default: true

settings.r_ratio_cut

numeric

Default cut point for R Ratio filter. Ignored when r_ratio_filter is false. User can update this setting via the UI when r_ratio_filter is true.

default: 0

settings.title

character

Title to be drawn above the controls. Use an empty string or NULL if no title is desired.

default: "Hepatic Safety Explorer"

settings.warningText

string

Informational text to be displayed near the top of the controls (beneath the title, if any). No warning is displayed if warningText is false-y.

default: 'Caution: This interactive graphic is not validated. Any clinical recommendations based on this tool should be confirmed using your organizations standard operating procedures.'

Webcharts settings

The object below contains the default Webcharts settings for the display.

  x: {
        column: null, //set in onPreprocess/updateAxisSettings
        label: null, // set in onPreprocess/updateAxisSettings,
        type: 'linear',
        behavior: 'raw',
        format: '.2f'
        //domain: [0, null]
    },
    y: {
        column: null, // set in onPreprocess/updateAxisSettings,
        label: null, // set in onPreprocess/updateAxisSettings,
        type: 'linear',
        behavior: 'raw',
        format: '.2f'
        //domain: [0, null]
    },
    marks: [
        {
            per: [], // set in syncSettings()
            type: 'circle',
            summarizeY: 'mean',
            summarizeX: 'mean',
            attributes: { 'fill-opacity': 0 }
        }
    ],
    gridlines: 'xy',
    color_by: null, //set in syncSettings
    max_width: 900,
    aspect: 1,
    legend: { location: 'top' },
    margin: { right: 25, top: 25, bottom: 75 }
⚠️ **GitHub.com Fallback** ⚠️