Running R Inside Your formr Study

A. Calculate Items (API Entry Point)

A calculate item evaluates an R expression when the participant reaches it. The last value is stored in the session data and can be used by later units (showif conditions, labels, other calculate items). This is where formr_api_authenticate() and formr_api_fetch_results() go.

# Inside a calculate item's "value" field:
formr_api_authenticate()

past <- formr_api_fetch_results(.formr$run_name, item_names = "score", join = TRUE)
mean(past$score, na.rm = TRUE)

Use calculate items for any logic that needs cross-session data: computing norms, generating tokens, processing JSON, or counting completions per experimental cell.

B. Inline R in Labels (Display + Fetch)

Labels render text and plots to the participant. They can call API functions just like calculate items — formr_api_authenticate() and formr_api_fetch_results() work here too.

# In a note item's label — fetch and display in one step:
# ```{r, echo=FALSE, results='asis'}
# formr_api_authenticate()
# scores <- formr_api_fetch_results(.formr$run_name,
#   item_names = "engagement", join = TRUE)
# cat("The sample mean is ", mean(scores$engagement, na.rm = TRUE), ".")
# ```

Use echo=FALSE to hide the code and results='asis' to print raw output. You can also render ggplot2 charts this way (see the Group Norms walkthrough in §5).

As a style choice, you can separate fetch logic into a calculate item and keep labels minimal — this makes studies easier to debug. But nothing prevents you from doing both in one label, as the Group Norms walkthrough in §5 does.

C. Inline R in Choices (Display)

Choice labels can also display dynamic content, useful when a dropdown menu should reflect live database contents.

# Inside a mc_multiple choice option's label — fetch and display in one step:
# ```{r}
# formr_api_authenticate()
# posts <- formr_api_fetch_results(.formr$run_name, item_names = "title", join = TRUE)
# posts$title[1]
# ```

Authentication

Inside a run, credentials are injected automatically. Just call:

formr_api_authenticate()

The package detects .formr$access_token and .formr$host set by the server. The token is valid for the duration of the request and is revoked when the request finishes.

Run Context

Two hidden variables are always available:

run_name <- .formr$run_name
user_session <- survey_run_sessions$session

Use these to fetch the right data and associate new data with the right session, making your code portable across runs.

Fetching Data from Other Surveys

The function for reading data from within a run is formr_api_fetch_results(). It differs from formr_api_results() in important ways:

Inside a run, you almost always want formr_api_fetch_results() — raw data without transformations is safer when you process it yourself.

data <- formr_api_fetch_results(.formr$run_name,
  item_names = c("name", "age", "score"), join = TRUE)

Always specify item_names to keep requests fast. The result is a tibble with one row per session and a column per requested item (plus a session column). If the same item name appears in multiple surveys, the survey name is prefixed.

The current() Shorthand

In showif conditions and value expressions, formr repeats items within a session. The helper current(x) returns the most recent submission of an item — the last element of the vector, which is always the current session’s value:

# formr repeats items within a session; current() returns the latest value.
# Here is a participant's history of one menu item across repeats:
choice_history <- c("option_a", "option_b", "option_a")
current(choice_history)                 # the current (most recent) selection
#> [1] "option_a"

# In a showif you would compare it directly, e.g.:
current(choice_history) == "option_a"   # TRUE
#> [1] TRUE

# first() and last() are siblings that drop missing values by default:
first(c(NA, 2, 3))   # 2
#> [1] 2
last(c(1, 2, NA))    # 2
#> [1] 2

This is cleaner than the equivalent base-R x[length(x)] pattern and makes your intent explicit. See ?current for details.

Run Structure

Calculate: participant_count

formr_api_authenticate()

past <- formr_api_fetch_results(.formr$run_name, item_names = "name", join = TRUE)

if (nrow(past) > 0) nrow(past) + 1 else 1

Survey: welcome

A note item with this label:

# ```{r, echo=FALSE, results='asis'}
# cat("## Welcome, Participant #", participant_count, "\n\n", sep = "")
# cat("Please proceed with the study.")
# ```

Run Structure

The burnout survey has a regular item called engagement where the participant enters their score. The feedback label does everything in one step — no separate calculate item needed, no data stored between units.

Survey: feedback (label)

A note item whose label fetches all engagement scores via the API and renders a ggplot comparing the current participant against the sample distribution:

# ```{r, echo=FALSE, results='asis', fig.width=6, fig.height=3}
# library(ggplot2)
# formr_api_authenticate()
#
# # Fetch all participants' engagement scores
# all_scores <- formr_api_fetch_results(.formr$run_name,
#   item_names = "engagement", join = TRUE)
#
# # Current participant's own score — local, no API needed
# my_engagement <- current(burnout$engagement)
#
# ggplot(all_scores, aes(x = engagement)) +
#   geom_density(fill = "grey70") +
#   geom_vline(xintercept = my_engagement, colour = "red", linewidth = 1) +
#   labs(
#     title = "Your engagement score vs. the organisation",
#     subtitle = paste0("Sample: ", nrow(all_scores), " colleagues"),
#     x = "Engagement", y = ""
#   ) +
#   theme_minimal()
# ```

Note two patterns worth reusing:

1. The current participant’s own score (current(burnout$engagement)) is available locally from the session — no API roundtrip needed.
2. The API call (formr_api_fetch_results) only fetches what the label cannot already see: other participants’ data. This is one roundtrip, one OpenCPU session, and nothing stored in the database beyond what the burnout survey already saves.

Run Structure

Calculate: pick_condition

formr_api_authenticate()

# Fetch the condition assignments from all completed sessions
past <- formr_api_fetch_results(.formr$run_name,
  item_names = "assigned_condition", join = TRUE)

count_a <- sum(past$assigned_condition == "A", na.rm = TRUE)
count_b <- sum(past$assigned_condition == "B", na.rm = TRUE)

# Assign to the smaller group; break ties randomly
if (count_a <= count_b) "A" else "B"

Showif conditions

Position 30 (intervention_a) showif:

current(pick_condition) == "A"

Position 40 (intervention_b) showif:

current(pick_condition) == "B"

Run Structure

The waiting room survey has a single hidden submit button configured with submit: 2000 in its survey settings, causing it to re-submit every 2 seconds. A SkipBackward unit (position 30) immediately sends the session back to position 20, creating a continuous loop.

An administrator trigger (run manually or on a cron schedule) polls for queued sessions and releases them:

# Admin trigger — run outside the study, on your local machine or a cron job
formr_api_authenticate(host = "https://api.rforms.org", account = "admin")

# Find sessions currently at the waiting room (position 20)
queued <- formr_api_sessions("my-run-name", active = TRUE)
waiting <- queued$session[queued$position == 20]

if (length(waiting) >= 2) {
  formr_api_session_action("my-run-name",
    session_codes = waiting, action = "move_to_position", position = 40)
  message("Released ", length(waiting), " participants to the dyadic task.")
}

After release, sessions land directly on position 40 (the dyadic_task survey), bypassing the SkipBackward loop.

Participant experience

1. Complete the lobby survey.
2. Land on the waiting room — the page auto-re-submits every 2 s, keeping them in the loop.
3. When the admin trigger finds enough participants, it moves them past the SkipBackward to the live task.