Protobi

← All help posts

View post

# Element Property (Edit JSON)

**PARTIAL DRAFT**

-   Clarify editorial intent ... is this to explain how these attributes to someone who doesn't already know them inside out?
-   E.g. read the sections on **element** and **type**
-   Revise styling for neater visual look
-   All code should be in ⪯ode> or ⪯pre> block with monospace font
-   The attributes names should be larger than the heritable keyword
-   Check spelling/grammar and sentence structure

For any element or group, press the circle or square icon and select "Edit..." . This will bring up the Advanced Editor:

The Element Properties editor uses a syntax called "JSON" (JavaScript Object Notation). The beauty is that you are seeing and editing the actual code that defines your Protobi project.

The syntax is pretty simple, and you can figure it out pretty well from existing examples. The general pattern is `{"key":"value"}` pairs, separated by commas, where the key is always contained in quotes, and the value may be a string, number, null, an array in square brackets, or even another JSON object in curly braces.

All of the above attributes have default values, and can be set to null or "". Below are the allowable values...

## Attributes

#### `key`

Each element has a unique `key` that identifies it. Multiple groups can refer to the same `key` as a child element, and each group will point to the same element with the same properties. By default, the key appears in the element's header.

## Formatting

#### `displayKey`

Specifies a different string to display in the element's header. This might be handy if the survey define a column with key **s0** but you would prefer the user to see **Specialty** instead. In this case you might have:

```json
{
   "key": "s0",
   "displayKey": "Specialty"
}
```

#### `title`

Longer text that appears below the element header. For instance, the element **specialty** might have the title "Doctor, what is your primary specialty?"

#### `showHtml`

If title text includes HTML (e.g. images, bold/italic, etc), `showHTML` will allow the text to be shown with:

```json
"showHtml":true
```

#### `color` [heritable](#heritable-properties)

The color of the element icon. It may be any CSS named color (e.g. `"color": "gold"`) or hexadecimal color code (e.g.`"color": "#FA0"`)

#### `colors` [heritable](#heritable-properties)

The colors of the chart. (e.g. stack chart) It may be any CSS named color (e.g. `"color": "gold"`) or hexadecimal color code (e.g.`"color": "#FA0"`)

#### `format` [heritable](#heritable-properties) < object >

Translates raw values to human-readable strings for display. Underlying value is unchanged. Formats are directly comparable to SPSS value labels. Formats are specified as Javascript objects with the raw value as the key and the formatted string as the value, e.g.

```json
"format": {
       "AD": "Andora",
       "AI": "Anguila",
       "AG": "Antigua",
       "AR": "Argentina",
      ...
   }
```

If no format is defined, then all raw values that appear in the data are displayed directly in the distribution. If a format is defined, then all formatted values appear in the distribution, whether or not they have data values. Values that exist in the data but are not defined in the format will appear under "Other".

You can toggle formatted value vs. raw value using the `Format` button.

#### `display`

Valid Values are: ("independent"|"compact"|"checkbox")

-   "independent"
-   "compact"
-   "checkbox"

## Data

#### `field`

By default, Protobi assumes that each element key refers to a data column with the same name. For instance, the element with key `"s0"` will look for a data column `"s0"`. You can override this using the `field` attribute. For instance the following defines an element "s0" which looks to the data column `"spec"` for its data:

```js
{
   "key": "s0",
   "field": "spec"
}
```

#### `element`

Instead of **field** attribute, you could change the the reference to use **element** instead. This will allow you to refer to the coded data.

```js
{
   "key": "s0",
   "element": "spec"
}
```

This will refer to the element **"spec"** instead of the data field, and bring over anything that has been reformatted or transformed

#### `type`

< ""|"string"|"number"|"empty" >

-   "" or null element values to be displayed unaltered
-   "string" often used for verbatim, menu item recode is added so string values can be recoded. Recoded values are stored under element editor as [reformat](####reformat)
-   "number" use for numerical values. permits \[calculation\](#calculation} and other arithmetic analysis.
-   "empty" Hides values of the element or group For groups and custom elements, set \[type\] to "empty" unless transform is used

#### `weight` [heritable](#heritable-properties)

Specific a weight value for this element. Can be a:

-   Name of a data field with weight values, e.g. "sales"
-   Key of an element which calculates a weight, e.g. "weight"
-   Number, e.g. 1

#### `transform`

Created a summarized value based on all the children for the element. Can embed JS code.

##### By default [hideChildren](#user-content-hidechildren) = true

-   sum
-   mean
-   median
-   min
-   max

#### `reformat` [heritable](#heritable-properties)

An object specifying a simple recoding. It works a like like [format](#format) but actually transforms the values before analysis.

This is particularily useful to [code open ends(verbatim)](https://vimeo.com/251752157) or create [segmentation variables](https://tutorials.protobi.com/v3/datasets/5c2a3faf3f1a560004981368)

E.g. Some surveys elicit respondent gender as text open-ends. reformat is a simple way to map these to standard codes:

{ "Man": "M", "Male": "M" "male": "M" "Female": "F" "female": "F" "Woman": "F" }

The raw value is on the left, and is always written as a string. The new value on the right can be a number, boolean, null or string value.

Note that reformat is applied before format is applied and can be used in conjunction with other transformations.

#### `filter` [heritable](#heritable-properties) < object >

An query expression that filters out all other values. This is useful for including only valid responses. Filter objects operate on the entire row, so the field name has to be specified. Constraints are specified in MongoDB query syntax. A few examples:

-   {"QA5a": {"$in": \[1,2,3,4,5\]}} allows only the values 1,2,3,4,5
-   {"QA5a": {"$nin": \[-9, 98, 99\]}} filters out -9, 98 and 99
-   {"QS4": {"$gte":0, "$lt": 100}} allows only values from 0 to 99

#### 'split'

A split of the data based on a delimiter. Often used for multi-select where the values are stacked in to a single answer:

-   "split":"," to tease out the comma delimited values
-   "split":"word" split out by words (useful for [word cloud](https://protobi.com/tutorials#https://vimeo.com/273787197))

#### 'valueFormat'

Setting to change the display the format of the output value. (as supposed to the label)

-   "valueFormat":"0.1%" changes the output into percentage format with 1 decimal.
-   "valueFormat":"$0.1" changes the output to include $.

## Calculation

#### `roundby` [heritable](#heritable-properties)

< number|array|"log"|"auto">

-   A number, e.g. 15 for custom linear ranges
-   "auto" for automatic linear ranges
-   "log" for automatic logarithmic ranges
-   0 to disable rounding
-   An array, e.g. \[0, 10, 40, 100\] for custom breaks

#### `showMean`[heritable](#heritable-properties)

< null=true|false>

#### `showSum` [heritable](#heritable-properties)

< null=false|true>

#### `showMedian` [heritable](#heritable-properties)

< null=false|true>

#### `showBasis` [heritable](#heritable-properties)

< null=false|true>

#### `showMin` [heritable](#heritable-properties)

< null=false|true>

#### `showMax` [heritable](#heritable-properties)

< null=false|true>

#### `showStats` [heritable](#heritable-properties)

< null=false|\[,,...\]> This shows additional statistics, e.g. top2, middle3, bottom box would be:

```js
{
   "showStats": [
        [1,2],
        [3,4,5],
        [6,7]
    ]
}
```

#### `denominator` [heritable](#heritable-properties)

< null=false|true>

#### `hidden`

< null=false|true>

hides the entire element! to unhide the element, use the listing of all elements on the left and click Shift-D

## Grouping

#### `children`

list all sub-elements for the group. can use to create a shell for a new element. (advance use)

#### `hideChildren`

< null=false|true>

When transform or compactto is used, children are usually hidden for display purpose. Use to hide/unhide children

#### `compactto`

< number|string|array|null>

Control how group is summarized in compact form:

-   A specific value, e.g. 1 for a top-box percentage.

-   An array, e.g. \[1,2\] for a top-N box percentage.

-   "$mean" for a summary of means.

-   "$sum" for a summary of sums.

-   null for no summary.

-   \[compactto\] can also be used on an element to display a single summarized value.

## Heritable properties

Changes to heritable properties propagate down to child elements within a group (and to their children...)

`format`, `reformat`, `maxValue` , `color` ,`weight` , `showSum`, `showMean`,`showMedian`,`showMin`, `showMax`, `showBasis`, `denominator`

#### `heritable`

< null=false|true>

heritable properties can be turned off for any specific element or group by { "heritable": false }

$(function() {  $("#menu-actions").prepend('<li><a id="admin-project" href="/v3/datasets/5c2a4b1d3f1a560004982a85/admin" target="admin\_5c2a4b1d3f1a560004982a85">Edit project</a></li>'); });

Publishing

Date

Status

Slug edit

Content

Thumbnail

Categories Manage

Tools

AI Database

Publishing

Content

Tools

Danger zone