Protobi JSON API

Updated at March 24th, 2023

Protobi defines each element as a set of parameters written in JSON syntax. An example is below:

{
    "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": [4,5],
    "chartType": "Pie",
    "filter": {
        "Q1": 2
    },
    "roundby": null
}

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 by humans (at least with a little bit of introduction).

The basic idea is that an element is defined as a "hash" or "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"), arrays of values (e.g. [4,5]) or other objects (e.g. see format above).

Each element is uniquely identified by an attribute  "key".    No two attributes in a Protobi project can have the same value of "key".   And the value of  "key" alone is enough to define the element, a lot of things can be assumed from its value, principally what data column to associate with the element.

Below is a partial list of attributes recognized by Protobi with their allowable values and a brief description:


Attribute Type Example Description




key
string "s1" Unique identifier for element. Required and immutable.
displayKey
string "S1" Override key for display.
title
string "Primary specialty" Additional description text.
field
string "s1x" Specify another data column as data source (default is "key")
element
key "s1x" Specify another element as data source, a
children
array  ["s1a","s1b","s1c"] List child elements. If not null, element is a group.
format
hash {"1":"PCP","2":"Neuro"} Format values for display after analysis.
reformat
object {"99":"", "7":0} Recode values prior to analysis.
color
string "gold"|"#FA0" CSS color for element.
colors
object {"1":"red","2":"yellow"} CSS colors for values. Can be "ascending" or "descending".
type
string "string"|"number"|"empty" Whether element values are numbers, string, or not applicable.
compactto
value or array 1 One or more summary values for top/bottom box percentages.
roundby
value or name 0|10|"auto"|"log" Bin range for numeric values.
transform
name "squish"|"sum"|"mean"|(fn) Specify standard transform function or code a custom function
split
string "," Split values at delimiter into a multiple response value
weight
number or key "ptwt"|1000 Weight frequencies by value of a data column or constant.
scale
number or key "s4"|100 Multiply values by a data column or constant.
denominator
number or key "s3"|100  Divide values by a data column or constant.
display
name null|"checkbox"|"compact" Specify how to display element as expanded, compact or group
hidden
boolean TRUE Hide element from tab
hideChildren
boolean TRUE Hide children (useful for groups with transform specified)
showBody
boolean FALSE Hide distribution (useful to show just summary stats)
heritable
boolean FALSE Whether changes to heritable properties propagate to children
showMissing
boolean FALSE Whether to include NA values in distribution percentages
chartType
name "VennDiagram" Specify alternative chart type (default is "BaselineBarChart")
chartOptions
boolean {"width":"480px"} Specify options specific to selected chartType
showStats
array of values or objects [[1,2],{label:"net",value:[6,7]} Additional custom statistics to show
follow
hash {"q1":["chartOptions.width"} Specify which elements and which attributes of them to follow

Was this article helpful?