Protobi

← All help posts

View post

## Overview

Protobi projects consist of "data" and "metadata".  The "data" is the response values for each respondent, and the "metadata" is information about the data, such as the question title, the column name, and the response value labels.

The metadata is stored in [JSON syntax](<https://quickref.me/json> "JSON syntax cheat sheet").  as array of elements, where each element is an object with atttribute-value pairs.

## Example
An example is below:

```json
{
    "key": "Q2",
	"displayKey": "Question 2.  Opinions",
    "title": "Do you agree with the following statements?",
    "children": ["Q2a", "Q2b", "Q2c", "Q2d","Q2e"],
    "format": {
       "1": "Extremely favorable",
       "2":  "Somewhat favorable",
       "3":  "Somewhat unfavorable",
       "4":  "Extremely unfavorable",
       "5":  "Don't know / no opinion"
    },
    "type": "number",
    "showBasis": true,
    "showStats":  { "value": [1,2], "label": "Favorable NET"},
    "chartType": "Pie",
    "filter": {
        "Q1": 2
    },
    "roundby": null
}
```

## Brief intro JSON Syntax
This syntax may look foreign at first, but has the advantage of being both easily readable by computers in almost any language, and also readable and editable by humans (at least with a little bit of introduction).

The basic idea is that an element is defined as an "object" that defines attribute-value pairs. In the example above, "title" is one such key and "Do you agree with the following statements?" is its corresponding value.

Attributes are always strings. Values can be
* **numbers** (e.g. 10),
* **strings** (e.g. "Q2"),
* **booleans** (e.g. `true`),
* **arrays** of values (e.g. [4,5]) or
* **objects** (e.g. see format above).

[A complete list of all JSON attributes](https://protobi.com/tutorials/json)

## Protobi conventions
In Protobi Each element is uniquely identified by an attribute "key". No two attributes in a Protobi project can have the same value of "key".

And often the key alone can be enough to define the element - Protobi will assume the element corresponds to a data column of the same name, and will use the key as its identifier for display.

- **Top-level attributes** Core information needed to calculate the data are generally top-le
- **Chart options** Detailed attributes to customize display are typically under the `chartOptions`
- **Root element** The element with key `"$root"` specifies project-level settings and defaults.

## Top-Level Element Properties

Properties that can be set on any element (question, category, group).

### Core Properties

| Property | Type | Description | Values/Examples |
|----------|------|-------------|-----------------|
| `key` | `string` | Each element is uniquely identified by its key.  The key can be any string value, including spaces or special characters.  The key is immutable. |  |
| `title` | `string` | Longer description or question text |  |
| `children` | `string` | Define a group by listing keys of child elements, separated by commas. |  |
| `type` | `string` | Type of data.  Set type to 'empty' for groups that don't have their own data column. | `""`, `"date"`, `"empty"`, `"number"`, `"string"` |
| `display` | `string` |  | `""`, `"checkbox"`, `"compact"`, `"independent"`, `"stacked"`, `"squish"` |

### Common Properties

| Property | Type | Description | Values/Examples |
|----------|------|-------------|-----------------|
| `col` | `string` | Element key(s) that define crosstab column, separated by comma |  |
| `color` | `string` | Sets the color for an element or category. Accepts any CSS color value | `"red"`, `"#FF0000"`, `"#F00"`... |
| `compactto` | `string|number|Array` | Specifies which values to compact/roll up in display. Can be a number, array of numbers, or special value like "$mean" or "$median" | `"$mean"`, `"$median"`, `1`... |
| `dataType` | `string` |  | `"date"`, `"number"`, `"string"` |
| `displayKey` | `string` | Specify a different string to appear as the key for display. |  |
| `editorOnly` | `boolean` | Hide element from clients with View permissions | `false`, `true` |
| `element` | `string` | Draw data for this element from a different element.  This is useful to leverage recoding or other transforms applied in another element. | `"A8_1"`, `"B6"`, `"B7_dampening"`... |
| `field` | `string` | Use a different data column to use as source for this element. The default is to assume the field is the same as the element key. |  |
| `filter` | `Object` | Filters data using MongoDB query syntax. Defines which records to include in this element | `{"Q1A":1}`, `{"$or":[{"Q1A":1},{"Q1A":2}]}`, `{"$and":[{"age":{"$gte":18}},{"region":"US"}]}`... |
| `footnote` | `string` | Specify text to appear below the element. Text here will override any auto-generated footnotes. |  |

### Additional Properties

| Property | Type | Description | Values/Examples                                                                                                                           |
|----------|------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `format` | `Object` | Maps data values to display labels. Used to define value labels for categorical variables | `{"0":"Yes","1":"No"}`, `{"0":"1 - Not important at all","1":"2","2":"3","3":"4 - Very important"}`...                                    |
| `headline` | `string` | Brief description or summary |                                                                                                                                           |
| `heritable` | `boolean` | Optionally prevent any changes to this element from propagating to child elements. Default is true. | `false`, `true`                                                                                                                           |
| `hidden` | `boolean` |  | `false`, `true`                                                                                                                           |
| `isCaseWeight` | `boolean` |  | `false`, `true`                                                                                                                           |
| `maxChildren` | `number` | Number of child elements to display before converting to a scrollable layout. Set to 0 to clear. | `10`, `12`, `15`...                                                                                                                       |
| `maxValue` | `number` | Set maxValue to provide a reference for means, so that they can be drawn as bar charts. | `100`...                                                                                                                                  |
| `measure` | `string` |  | `"nominal"`, `"ordinal"`, `"scale"`                                                                                                       |
| `multiples` | `string` | Copy for each value of another element | `"hd0a"`, `"hidSQ30"`, `"overall"`...                                                                                                     |
| `numericMax` | `number` | Maximum allowed value for numeric input validation | `10`, `100`, `120`...                                                                                                                     |
| `numericMin` | `number` | Minimum allowed value for numeric input validation | `0`, `1`, `-999`...                                                                                                                       |
| `protect` | `boolean` | Protect element when resetting from survey engine | `false`, `true`                                                                                                                           |
| `roundby` | `string|number| Array`                                                                                                                                    | Controls rounding of numeric values. Can be a number (round to nearest), array of numbers (custom breakpoints), "log" (logarithmic rounding), or "auto" (automatic rounding) | `"auto"`, `"log"`, `0`... |
| `scale` | `number` | Multiply values by a constant or data value, e.g. scale fractions by 100 to become percentages between 0 and 100. | `100`...                                                                                                                                  |
| `showBasis` | `boolean` | Whether to show the sample size (N) for this element | `false`, `true`                                                                                                                           |
| `showBasisUnweighted` | `boolean` |  | `false`, `true`                                                                                                                           |
| `showDistinct` | `boolean` |  | `false`, `true`                                                                                                                           |
| `showMean` | `boolean` |  | `false`, `true`                                                                                                                           |
| `showMissing` | `boolean` | Override [NA] tool button to never (or always) include missing values in percentages. | `false`, `true`                                                                                                                           |
| `showPercent` | `boolean` | Override #/% toolbar button to never or always show percentages | `false`, `true`                                                                                                                           |
| `showStats` | `Array` | Array of custom statistics to display. Each can be an object with value and label, or a simple value. Values can be either a single "top-box" value, and array of "top-box" values, or special values like "$mean", "$median" | `[{"value":[4,5],"label":"Top-2 box"}]`, `[{"value":[2,3,4,5],"label":"Aware"},{"value":[3,4,5],"label":"Familiar"}]`, `["$mean","$median"]`... |
| `showUnformatted` | `boolean` |  | `false`, `true`                                                                                                                           |
| `split` | `string` | Split responses at a delimiter to treat as a multiple responses. | `","`, `"json"`, `"word"`                                                                                                                 |
| `suppress` | `Object` | Maps values to boolean indicating whether to hide that value in display | `{"":true,"$other":true}`, `{"1":true,"2":true,"3":false}`, `{"=6":false,"=7":false}`...                                                  |
| `titles` | `Object` | Multi-language title mappings. Keys are language codes (e.g., "en", "es", "fr"), values are translated titles | `{"en":"What is your age?","es":"¿Cuál es tu edad?","fr":"Quel est votre âge?"}`...                                                       |
| `valueFormat` | `string` | Number format for element values and means, in d3 syntax (e.g '0.1%' for percent with one decimal) | `".02%"`, `".0f"`, `"%"`...                                                                                                               |
| `weight` | `string` | Count each response by a frequency  | `0.125`, `1`, `"B10_Kx"`...                                                                                                               |

---

## Chart Options

Chart options are specified within the `chartOptions` object on an element. These control how data is visualized.

### Usage Example

```json
{
  "q1": {
    "key": "q1",
    "title": "Satisfaction",
    "chartOptions": {
      "width": 800,
      "height": 400,
      "orientation": "h",
      "barmode": "stack",
      "showlegend": true,
      "xaxis": {
        "tickangle": -45
      },
      "yaxis": {
        "rangemode": "tozero"
      }
    }
  }
}
```

---

### General Chart Options

Properties used across multiple chart types.

| Property | Type | Description | Values/Examples |
|----------|------|-------------|-----------------|
| `barWidth` | `number` | Set the width of the bar |  |
| `fontWeight` | `string` | Font weight, e.g. bold or 700 | `""`, `"bold"` |
| `rowHeight` | `number` | Set the height of the row |  |
| `showBars` | `boolean` | Whether to show bars | `false`, `true` |
| `testUsingPairedSamples` | `boolean` | Test differences using as paired samples (rather than independent samples) if possible | `false`, `true` |

---

### Plotly.js Properties

These properties map directly to [Plotly.js](https://plotly.com/javascript/) layout and trace properties.

#### Dimensions

Control chart size.

| Property | Type | Description | Plotly Mapping |
|----------|------|-------------|----------------|
| `height` | `number` | Chart height in pixels | [`layout.height`](https://plotly.com/javascript/reference/layout/#layout-height) |
| `width` | `number` | Chart width in pixels | [`layout.width`](https://plotly.com/javascript/reference/layout/#layout-width) |

#### Margins

Control spacing around the chart.

| Property | Type | Description | Plotly Mapping |
|----------|------|-------------|----------------|
| `margin.b` | `number` | Bottom margin, in pixels | [`layout.margin.b`](https://plotly.com/javascript/reference/layout/#layout-margin-b) |
| `margin.l` | `number` | Left margin, in pixels | [`layout.margin.l`](https://plotly.com/javascript/reference/layout/#layout-margin-l) |
| `margin.r` | `number` | Right margin, in pixels | [`layout.margin.r`](https://plotly.com/javascript/reference/layout/#layout-margin-r) |
| `margin.t` | `number` | Top margin, in pixels | [`layout.margin.t`](https://plotly.com/javascript/reference/layout/#layout-margin-t) |

#### Legend

Control legend appearance and position.

| Property | Type | Description | Plotly Mapping |
|----------|------|-------------|----------------|
| `legend.orientation` | `string` | Whether to show legend vertically or horizontally | [`layout.legend.orientation`](https://plotly.com/javascript/reference/layout/#layout-legend-orientation) |
| `legend.xanchor` | `string` | Whether legend x position specifies the left, center or right of the legend | [`layout.legend.xanchor`](https://plotly.com/javascript/reference/layout/#layout-legend-xanchor) |
| `legend.yanchor` | `string` | Whether legend y position specifies the top, center or bottom of the legend | [`layout.legend.yanchor`](https://plotly.com/javascript/reference/layout/#layout-legend-yanchor) |

#### X-Axis

Control horizontal axis appearance and behavior.

| Property | Type | Description | Plotly Mapping |
|----------|------|-------------|----------------|
| `xaxis.autorange` | `boolean` | Automatically set the range based on data | [`layout.xaxis.autorange`](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-autorange) |
| `xaxis.rangemode` | `string` | If 'normal', the range is computed in relation to the extrema of the input data. If 'tozero'`, the range extends to 0, regardless of the input data If 'nonnegative', the range is non-negative, regardless of the input data. Applies only to linear axes. | [`layout.xaxis.rangemode`](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-rangemode) |
| `xaxis.showticklabels` | `boolean` | Determines whether or not the tick labels are drawn | [`layout.xaxis.showticklabels`](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-showticklabels) |
| `xaxis.tickangle` | `number` | Sets the angle of the tick labels with respect to the horizontal. For example, a `tickangle` of -90 draws the tick labels vertically. | [`layout.xaxis.tickangle`](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-tickangle) |
| `xaxis.tickfont` | `Object` | Sets the tick font. We can define properties like: size, color, weight | [`layout.xaxis.tickfont`](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-tickfont) |
| `xaxis.tickformat` | `string` | Determines the format of the ticks (e.g., '.0%', '.2f') | [`layout.xaxis.tickformat`](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-tickformat) |
| `xaxis.visible` | `boolean` | Determines whether or not the x-axis is shown | [`layout.xaxis.visible`](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-visible) |

#### Y-Axis

Control vertical axis appearance and behavior.

| Property | Type | Description | Plotly Mapping |
|----------|------|-------------|----------------|
| `yaxis.autorange` | `boolean` | Automatically set the range based on data | [`layout.yaxis.autorange`](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-autorange) |
| `yaxis.nticks` | `number` | Maximum number of ticks for the axis | [`layout.yaxis.nticks`](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-nticks) |
| `yaxis.rangemode` | `string` | If 'normal', the range is computed in relation to the extrema of the input data. If 'tozero'`, the range extends to 0, regardless of the input data If 'nonnegative', the range is non-negative, regardless of the input data. Applies only to linear axes. | [`layout.yaxis.rangemode`](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-rangemode) |
| `yaxis.showticklabels` | `boolean` | Determines whether or not the tick labels are drawn | [`layout.yaxis.showticklabels`](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-showticklabels) |
| `yaxis.tickangle` | `number` | Sets the angle of the tick labels with respect to the horizontal. For example, a `tickangle` of -90 draws the tick labels vertically. | [`layout.yaxis.tickangle`](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-tickangle) |
| `yaxis.tickfont` | `Object` | Sets the tick font. We can define properties like: size, color, weight | [`layout.yaxis.tickfont`](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-tickfont) |
| `yaxis.visible` | `boolean` | Determines whether or not the y-axis is shown | [`layout.yaxis.visible`](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-visible) |

#### Series (Trace)

Control individual data series appearance.

| Property | Type | Description | Plotly Mapping |
|----------|------|-------------|----------------|
| `orientation` | `string` | Whether to show vertical columns or horizontal bar | [`trace.orientation`](https://plotly.com/javascript/reference/bar/#bar-orientation) |
| `series.direction` | `string` | Specifies the direction at which succeeding sectors follow one another. | [`trace.direction`](https://plotly.com/javascript/reference/pie/#pie-direction) |
| `series.hole` | `number` | Sets the fraction of the radius to cut out of the pie. Use this to make a donut chart. | [`trace.hole`](https://plotly.com/javascript/reference/pie/#pie-hole) |
| `series.hoverinfo` | `string` | Determines which trace information appear on hover. If `none` or `skip` are set, no information is displayed upon hovering. But, if `none` is set, click and hover events are still fired. | [`trace.hoverinfo`](https://plotly.com/javascript/reference/bar/#bar-hoverinfo) |
| `series.insidetextorientation` | `string` | Controls the orientation of the text inside chart sectors. When set to 'auto', text may be oriented in any direction in order to be as big as possible in the middle of a sector. The 'horizontal' option orients text to be parallel with the bottom of the chart, and may make text smaller in order to achieve that goal. The 'radial' option orients text along the radius of the sector. The 'tangential' option orients text perpendicular to the radius of the sector. | [`trace.insidetextorientation`](https://plotly.com/javascript/reference/pie/#pie-insidetextorientation) |
| `series.line` | `Object` | Line styling properties including color, width, dash, etc. | [`trace.line`](https://plotly.com/javascript/reference/scatter/#scatter-line) |
| `series.marker` | `Object` | Marker styling properties including color, size, line, etc. | [`trace.marker`](https://plotly.com/javascript/reference/bar/#bar-marker) |
| `series.textinfo` | `string` | Determines which trace information appear on the graph. | [`trace.textinfo`](https://plotly.com/javascript/reference/pie/#pie-textinfo) |
| `textposition` | `string` | Sets the positions of the `text` elements with respects to the (x,y) coordinates. | [`trace.textposition`](https://plotly.com/javascript/reference/bar/#bar-textposition) |

#### Other Plotly Properties

| Property | Type | Description | Plotly Mapping |
|----------|------|-------------|----------------|
| `barmode` | `string` | How to display multiple bar series: 'group' for side-by-side, 'stack' for stacked, 'overlay' for overlapping, 'relative' for normalized to 100% | [`layout.barmode`](https://plotly.com/javascript/reference/layout/#layout-barmode) |
| `fontFamily` | `string` | Font family | [`layout.font.family`](https://plotly.com/javascript/reference/layout/#layout-font-family) |
| `margin` | `Object` | Sets all margins at once as an object. Alternative to setting margin.l, margin.r, margin.t, margin.b individually | [`layout.margin`](https://plotly.com/javascript/reference/layout/#layout-margin) |
| `showlegend` | `boolean` | Show legend in chart | [`layout.showlegend`](https://plotly.com/javascript/reference/layout/#layout-showlegend) |
| `uniformtext.minsize` | `number` | Sets the minimum text size between traces of the same type. | [`layout.uniformtext.minsize`](https://plotly.com/javascript/reference/layout/#layout-uniformtext-minsize) |
| `uniformtext.mode` | `number` | Determines how the font size for various text elements are uniformed between each trace type. If the computed text sizes were smaller than the minimum size defined by `uniformtext.minsize` using 'hide' option hides the text; and using 'show' option shows the text without further downscaling. Please note that if the size defined by `minsize` is greater than the font size defined by trace, then the `minsize` is used. | [`layout.uniformtext.mode`](https://plotly.com/javascript/reference/layout/#layout-uniformtext-mode) |

*See [PLOTLY-MAPPINGS.md](PLOTLY-MAPPINGS.md) for complete Plotly.js integration details*

---

### Chart-Specific Options

Properties specific to particular chart types.

#### Word Cloud

| Property | Type | Description | Values/Examples |
|----------|------|-------------|-----------------|
| `drawOutOfBound` | `boolean` | Whether to show words that would extend out of bounds | `false`, `true` |
| `maxFontSize` | `number` | Size of most frequent word, in points |  |
| `maxWords` | `number` | Maximum number of words to show | `3`, `25`, `40`... |
| `minFontSize` | `number` | Show all words at least this size |  |
| `scaleToMaxFontSize` | `boolean` | Set size of most frequent word to value maxFontSize vs scale to fit margin | `false`, `true` |
| `shuffle` | `boolean` | Whether to randomly shuffle positions on each render | `false`, `true` |

#### Verbatim/Text Display

| Property | Type | Description | Values/Examples |
|----------|------|-------------|-----------------|
| `columnWidth` | `number` | Set the width of the column | `120.4`, `123.85714285714286`, `133`... |
| `enquote` | `boolean` |  | `false`, `true` |
| `maxRows` | `number` | Maximum number of rows to display by default |  |

#### Sankey Diagram

| Property | Type | Description | Values/Examples |
|----------|------|-------------|-----------------|
| `nodePadding` | `number` |  |  |
| `nodeWidth` | `number` |  |  |

#### Paired Table

| Property | Type | Description | Values/Examples |
|----------|------|-------------|-----------------|
| `columnWidth` | `number` | Set the width of the column | `120.4`, `123.85714285714286`, `133`... |
| `testPairedSamples` | `boolean` | Test differences using paired samples (rather than independent samples) | `false`, `true` |

---

## Root-Level Properties

These properties are used exclusively on the **`$root`** element to configure dataset-wide settings.

### Most Common Root Properties

| Property | Type | Description | Values/Examples |
|----------|------|-------------|-----------------|
| `precisionFreq` | `number` | Precision setting for numeric display |  |
| `toolbar` | `string` | Toolbar configuration |  |
| `nsymbol` | `string` | Symbol for display formatting |  |
| `showPairwise` | `boolean` | Controls visibility/display at root level |  |
| `view` | `Object` | View configuration settings |  |
| `nilSymbol` | `string` | Symbol for display formatting |  |
| `zeroSymbol` | `string` | Symbol for display formatting |  |
| `showPercentSymbol` | `string` | Symbol for display formatting |  |
| `loops` | `number` | Number of loops/iterations |  |
| `id` | `string` | Identifier |  |
| `minPercentSymbol` | `string` | Symbol for display formatting |  |
| `minPercent` | `string` |  |  |

*See [ROOT-PROPERTIES.md](ROOT-PROPERTIES.md) for complete list of 36 root properties*

---

## Common Patterns

### display

```json
{
  "display": "",            // Default table
  "display": "compact",     // Compact table
  "display": "checkbox",    // Checkbox list
  "display": "stacked",     // Stacked bars
  "display": "independent"  // Independent percentages
}
```

### orientation

```json
{
  "chartOptions": {
    "orientation": "h",     // Horizontal bars
    "orientation": "v"      // Vertical columns
  }
}
```

### barmode

```json
{
  "chartOptions": {
    "barmode": "group",     // Side-by-side bars
    "barmode": "stack",     // Stacked bars
    "barmode": "overlay",   // Overlapping bars
    "barmode": "relative"   // Normalized to 100%
  }
}
```

### Color Strategy

```json
{
  "chartOptions": {
    "colorBy": "category",  // Color by category
    "colorBy": "series",    // Color by series
    "colorBy": "index",     // Color by index
    "colorBy": "none"       // No coloring
  }
}
```

---

Publishing

Date

Status

Slug edit

Content

Thumbnail

Categories Manage

Tools

AI Database

Publishing

Content

Tools

Danger zone