Use JavaScript to process data

Adding code to your project

Protobi lets you make programmatic changes to your survey data directly within the platform. There are two ways to do this: Pre-calculate, which runs automatically every time your project loads, and Data process, which you run manually when needed.

For small modifications, Pre-calculate is a good place to start.

Pre-calculate

Go to your project's Settings and open the Pre-calculate tab. You'll see a single line of code by default:

return rows;

<img src="/uploads/upload/image/5200/direct/1596212857855-1596212857855.png" alt="Project settings page showing "Pre-Calculate" section with "Save" and "Advanced users only!" buttons at top. Left sidebar lists navigation items including Open, Overview, Wiki pages, Data, Permissions, Elements, Pre-calculate, Downloads, Log, History, Help, Advanced, and To do. Main area displays code editor with line 1 containing "return rows;" in purple syntax highlighting." class="fr-fic fr-dib">

This is the most basic data process. rows represents your project's primary dataset, and this line simply returns it as-is. Protobi executes whatever is in Pre-calculate before your project finishes loading, so it's best suited for simple, lightweight operations that won't slow things down.

Try it out

The example below creates a pop-up message showing the number of respondents in your dataset. Copy it into Pre-calculate and hit Save.

var message = "This dataset has " + rows.length + " respondents";
alert(message);

return rows;

The message will appear each time the project is opened or the page is reloaded.

Summing values across columns

A common use of Pre-calculate is creating a derived variable that adds together several columns from the same row. For example, suppose you want to total the number of patients across all products for Q2.

<img src="/uploads/upload/image/5200/direct/1596224839135-1596224839135.png" alt="Question Q2 with blue square icon asking "Thinking about your Condition X patients on a GA (gamma antagonist), how many are currently on the following therapies?" displaying "Compact to Mean" format with three products: Product A (12.6), Product B (10.5), Product C (1.91), shown with blue magenta arrow markers and short blue bars." style="width: 410px;" class="fr-fic fr-dib">

You can create a new variable Q2_sum like this:

rows.forEach(function(row) {
    row.Q2_sum = (+row.Q2_1) + (+row.Q2_2) + (+row.Q2_3);
});

return rows;

The forEach loop runs this calculation for every respondent in the dataset.

A note on the + operator. Protobi stores your data as a CSV, which means all values are text strings — the string "2" rather than the number 2. This matters because JavaScript handles addition differently depending on the type: two numbers give you a sum (2 + 2 = 4), but two strings give you concatenation ("2" + "2" = "22"). Prefixing each value with + forces JavaScript to treat it as a number.

Using your new variable

Once created, Q2_sum will have numeric values that you can bin into ranges.

Note that variables created in Pre-calculate are not added to your dashboard automatically — you'll need to create the element manually by clicking the + button under a group or tab and referencing the variable key (e.g. Q2_sum).

Data process

For more substantial data work, you can create a dedicated process in the Data tab of your project's Settings. Unlike Pre-calculate, data processes are run manually and are better suited for heavier operations like combining multiple data tables or defining variables with complex logic.

Return a data table

If your project has a data table with the key main, the simplest process just returns it:

var rows = data["main"];

return rows;

Combine survey waves

A common use case is stacking multiple waves of data into a single dataset. If your project has separate data tables for each wave, you can combine them like this:

var W1 = data["wave1"];
var W2 = data["wave2"];
var W3 = data["wave3"];
var W4 = data["wave4"];

var rows = Protobi.stack_rows([W1, W2, W3, W4]);

return rows;

Define new variables with conditional logic

You can also create new variables based on conditions. The example below creates a therapy_use variable derived from a respondent's answers to Q1 and Q5_1:

var rows = data["main"];

rows.forEach(function(row) {
    if (row.Q1 == 1 || row.Q5_1 == 1) row.therapy_use = 1; // High use
    else row.therapy_use = 0; // Low use
});

return rows;

We recommend assigning integer values to new variables and using Value formats to label them — this is consistent with how most survey data is programmed.

Remember: After editing a data process, click Save then Run. To use the result as your project's primary data, you'll also need to mark it as Primary. Data processes are project-specific, so your implementation may look slightly different from the examples above.