Edit element properties

This tutorial details some of the advanced options than can be set within the Element Properties interface.

The Element Properties dialog can be accessed by selecting "Edit JSON..." from the context menu for any element.

The Element Properties editor uses a syntax called "JSON" (JavaScript Object Notation). The beauty of this interface is that it allows you to see and edit 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 a set of key:value pairs, separated by commas, where the key is always contained in quotes. The value may be a string, number, null, or another JSON object, e.g.,:

{"key":"value"}

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

PropertyDescription
key
A string that uniquely identifies the element. It is the name of a column in the dataset, and is assumed to be a column name unless field is specified, or type is "empty." It is not editable, but you can override how it appears with displayKey.
displayKey
An optional string to appear instead of key for display. The default is null, e.g.,"Q1".
title

An optional string to appear as a title within the element, providing additional context. e.g., "Q1. Age (years)".

type
Either "string" or "number" or "". For groups and custom elements, set type to "empty".
round byDefines ranges for numeric variables:
  • a number, e.g.,15 for custom linear ranges
  • "auto" for automatic linear ranges
  • "log" for logarithmic ranges
  • "none" to disable rounding
  • an array, e.g. [0,10,40,100] for custom breaks
children

An array of element keys as strings, e.g., ["q5a", "q5b", "q5c"] that defines an element as a group of other elements. Typically, a group will also specify type: "empty".

weightSpecifies a weight value for this element. Can be a:
  • the 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

Specifying a weight for an element overrides any global weight (e.g., see weighting tutorial.)

Specifying a specific value, e.g., 1 as an override can be useful to prevent a field used as the global weight from being weighted by itself.

compact to
Controls 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
  • null for no summary
formatAn object specifying a display values for each raw value, e.g.,:
{ "1": "True", "2": "False" }

Both the raw values on the left, and the formatted values on the right, are specified as strings.

By default, if a format is provided, then all values specified in the format are shown in the distribution, even if the frequency is zero.

And any value not specified in the format is grouped into a special $other value, which can be expanded to show the raw values.

maxValue

Specifys a reference value for drawing bar lengths when compact to is set to $mean or $sum . In some cases, this value is detected and set automatically as the largest value of any element in the group.

colorAny HTML color string, either a named CSS color, e.g., "orange", or a hex RGB value "#FC0"

Recoding and transformations

There are a number of advanced options that transform or filter the data before analysis.

PropertyDescription
filter

A 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]}}
  • {"QA5a": {"$nin": [-9, 98, 99]}}
  • {"QS4": {"$gte":0, "$lt": 100}}

The first allows only the values 1, 2, 3, 4 and 5. The second filters out -9, 98, and 99. The third allows only values from 0 to 99.

reformat

An object specifying a simple recoding. It works a like like format but actually transforms the values before analysis.

E.g., Some surveys elicit respondent gender as text open-ends. preformat 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.

There are even more advanced capabilities. If you have any questions about how to do something, please contact support@protobi.com.

Aside: Users actually have direct programmatic access to all of Protobi within their browser, which will be covered in a later tutorial. Javascript is a powerful programming language. It can do many things you might associate with with a stats package like SAS or SPSS, or you would think needed to be done by hand. E.g., Extracting and applying variable/value labels from a vendor's code sheet.