Visualization

The visualization attribute is an array of objects which contain information for how to render protocol results to the user.

Overall schema

"visualization": [
  {
    "visualization_type": "numeric-tag", //Mandatory
    "collection": "Ccc ccc ccc", //Optional
    "descriptors": [
      {"focus-mean": "Average value of 'COLLECTION_PLACEHOLDER: VARIABLE_PLACEHOLDER' for cases in the focus cohort ARGUMENT_VALUE(argument_name) (FOCUS_COUNT_PLACEHOLDER entities)"},
      {"background-mean": "Average value of 'VARIABLE_PLACEHOLDER' for all cases (BACKGROUND_COUNT_PLACEHOLDER entities)"}
    ],
    "digits": #, //Optional
    "min": #, //Optional
    "max": # //Optional
  }
]

visualization_type

datatype: string
There are three supported visualization types: tag-tag, numeric-tag, and numeric-numeric. These correspond to the output of the method utilized by the protocol.

collection

datatype: string
The collection attribute is used to assign a custom visualization for only specific variable collections.

digits

datatype: float
The digits attribute restricts the number of decimal places displayed in calculated results.

min

datatype: int
The min attribute designates the minimum point of the scale to be rendered. This can be used in conjunction with the max attribute to ensure a common scale for numeric distributions.

max

datatype: int
The max attribute designates the maximum point of the scale to be rendered. This can be used in conjunction with the min attribute to ensure a common scale for numeric distributions.

descriptors

datatype: array
The descriptors attribute is an array of objects, with each object describing one line rendered in the visualization of a protocol. Because this is an array, these objects are rendered in sequence, from the top row of the visualization to bottom. The descriptors attribute is used to ensure that the response from a protocol provides the most relevance to the question being explored.

As shorthand, there are a variety of notations to represent different statistical comparisons as the key for each descriptor type. As a programming best practice, the usage of divisor (/) symbols within the descriptor keys have been replaced by pipe (|) symbols.

The values provided below are meant to be customized for each protocol and can include references for the arguments in the protocol or to display entity size placeholders.

descriptor options

"visualization_type": "tag-tag"

"descriptors": [
  {"score": "Tag.score for categorical comparison (Fischer's Exact Test)"},
  {"k": "ARGUMENT_VALUE(argument) count for the variable cohort"},
  {"expected-k": "Expected value of ARGUMENT_VALUE(argument) count for the variable cohort"},
  {"k-delta": "Difference between actual and expected values of ARGUMENT_VALUE(argument) count for the variable cohort"},
  {"n": "ARGUMENT_VALUE(argument) count for the background cohort"},
  {"m": "Variable cohort size"},
  {"N": "Background cohort size"},
  {"km": "ARGUMENT_VALUE(argument) rate for the variable cohort"},
  {"expected-km": "Expected value of ARGUMENT_VALUE(argument) rate for the variable cohort"},
  {"km-delta": "Difference between actual and expected value of ARGUMENT_VALUE(argument) rate for the variable cohort"},
  {"abs-km-delta": "Absolute value of difference between actual and expected value of ARGUMENT_VALUE(argument) rate for the variable cohort"},
  {"km-fold-change": "Ratio between actual and expected value of ARGUMENT_VALUE(argument) rate for the variable cohort"},
  {"nN": "ARGUMENT_VALUE(argument) rate for the background cohort"},
  {"n-not-k-ratio": "ARGUMENT_VALUE(argument) rate for entities NOT in the variable cohort"},
  {"kn": "Variable rate for the ARGUMENT_VALUE(argument) cohort"},
  {"expected-kn": "Expected value of variable rate for the ARGUMENT_VALUE(argument) cohort"},
  {"kn-delta": "Difference between the actual and expected value of variable rate for the ARGUMENT_VALUE(argument) cohort"},
  {"abs-kn-delta": "Absolute value of the difference between actual and expected value of variable rate for the ARGUMENT_VALUE(argument) cohort"},
  {"kn-fold-change": "Ratio between actual and expected value of variable rate for the ARGUMENT_VALUE(argument) cohort"},
  {"mN": "Variable rate for the background cohort"},
  {"m-not-k-ratio": "Not-in-variable rate for the ARGUMENT_VALUE(argument) cohort"}
]

"visualization_type": "numeric-tag"

"descriptors": [
  {"score": "Tag.score for a numeric comparison (Mann-Whitney Test)"},
  {"focus-count": "Number of values for variables in the focus cohort"},
  {"focus-total": "Total sum of variables in the focus cohort"},
  {"focus-mean": "Mean value of variables in the focus cohort"},
  {"focus-median": "Median value of variables in the focus cohort"},
  {"focus-minimum": "Minimum value of variables in the focus cohort"},
  {"focus-maximum": "Maximum value of variables in the focus cohort"},
  {"focus-5th-percentile": "5th percentile of variables in the focus cohort"},
  {"focus-25th-percentile": "25th percentile of variables in the focus cohort"},
  {"focus-75th-percentile": "75th percentile of variables in the focus cohort"},
  {"focus-95th-percentile": "95th percentile of variables in the focus cohort"},
  {"focus-distribution": "Up to 1000 values of variables in the focus cohort"},
  {"background-count": "Number of values for variables the background cohort"},
  {"background-total": "Total sum of variables in the background cohort"},
  {"background-mean": "Mean value of variables in the background cohort"},
  {"background-median": "Median value of variables in the background cohort"},
  {"background-minimum": "Minimum value of variables in the background cohort"},
  {"background-maximum": "Maximum value of variables in the background cohort"},
  {"background-5th-percentile": "5th percentile of variables in the background cohort"},
  {"background-25th-percentile": "25th percentile of variables in the background cohort"},
  {"background-75th-percentile": "75th percentile of variables in the background cohort"},
  {"background-95th-percentile": "95th percentile of variables in the background cohort"},
  {"background-distribution": "Up to 1000 values of variables in the background cohort"},
  {"mean-difference": "Difference of means between the focus cohort and the background cohort"},
  {"abs-mean-difference": "Absolute value difference of means between the focus cohort and the background cohort."},
  {"median-difference": "Difference of medians between the focus cohort and the background cohort"},
  {"abs-median-difference": "Absolute value difference of medians between the focus cohort and the background cohort"},
  {"not-focus-mean": "Mean value of variable for entities NOT in the focus cohort"}
]

"visualization_type": "numeric-numeric"

"descriptors": [
  {"background-count": "Number of entities in background"},
  {"coefficient": "Change in ARGUMENT_VALUE(argument) when VARIABLE_PLACEHOLDER increases by 1.0"},
  {"intercept": "Base value of ARGUMENT_VALUE(argument) when VARIABLE_PLACEHOLDER = 0.0"},
  {"adjusted-r-square": "Adjusted r-square value for multivariate regression"},
  {"rmse": "Root-mean-square error for multivariate regression"}
]

"visualization_type": "numeric-summary"

"descriptors": [
  {"COUNT_PLACEHOLDER": "Number of values for VARIABLE_PLACEHOLDER"},
  {"MEAN_PLACEHOLDER": "Mean of VARIABLE_PLACEHOLDER"},
  {"MEDIAN_PLACEHOLDER": "Median of VARIABLE_PLACEHOLDER"},
  {"TOTAL_PLACEHOLDER": "Total sum of VARIABLE_PLACEHOLDER"},
  {"IQR_PLACEHOLDER": "Interquartile range of VARIABLE_PLACEHOLDER"}
]

descriptor options

"color"

A descriptor can receive a standard hexadecimal color code to further customize the visualization.

"descriptors": [
  {
    "color": "#999"
  }
]

collection_placeholder: variable_placeholder

A collection_placeholder and/or variable_placeholder can be used to display collections or variables analyzed within the text of the visualization.

"descriptors": [
  {"Ddd": "COLLECTION_PLACEHOLDER: VARIABLE_PLACEHOLDER"}
]

count_placeholder

A count_placeholder displays the number of entities calculated by a descriptor.

"descriptors": [
  {"Ddd": "FOCUS_COUNT_PLACEHOLDER"}
  {"Ddd": "BACKGROUND_COUNT_PLACEHOLDER"}
  {"Ddd": "n_PLACEHOLDER"}
]