---
title: "Visualization"
slug: "visualization"
updated: 2022-07-22T18:41:05Z
published: 2022-07-22T18:41:05Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://code.tag.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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"}
]
```