R Helpers

R in formr

In formr, you can use R to write simple and complex code. Various places allow you to specify either R code (e.g., showif column, value column, SkipForward/SkipBackward, External, Pause button conditions) or R code interspersed with Markdown (as in knitr, e.g., labels, Stop button, Pause button texts). The R code you wrote will be automatically enriched with the data objects you name and processed using OpenCPU. By default, your participants cannot view the R code you write.

Automatically enriched data

When you write R code in formr, we try to automatically determine what data you need and supply it. To do so, formr has a look up table of all the available data (the surveys defined in the run, the items defined in these surveys, as well as some metadata about the participant and run progress).

For example, to obtain somebody's age, you need only write demographics$age. formr will then automatically create a data frame named "demographics" containing the variable "age". To give another example, to see whether a participant ever reported a headache in your diary, you might just write any(diary$headache > 1). In this case, formr would create a data frame containing all responses to the headache question. It's important to note that formr simply checks whether the name of the survey exists anywhere in the text and whether the name of the item exists anywhere else. So, demographics$age works, but so does demographics[, 'age']. If an item name exists in multiple surveys that you have named, it will be supplied for all surveys.

Available data

user_id

The unique user code which we use for logging people in, e.g., NqbpASFVlcci5cnVvpMZG4ueILaYvFk39fDND305XvPLh3KW4xzrP0ygJ1phs1gf.

.formr
$login_link $login_code $nr_of_participants $session_last_active

Useful shortcuts to obtain the link to the personalised study link, the login code (currently the same as user_id), the total number of participants in the run (even those who only saw the first page), as well as a date-time when the current participant was last active.

YourSurvey
$YourItem1
$YourItem2

Any of the surveys that are part of the run and any of their items can be requested in this way. In addition, if you have named items belonging to a scale with a numeric suffix and an optional R, you need only name the scale (e.g., extraversion) and all items (e.g., extraversion1, extraversion2R, extraversion3) will be supplied.

survey_users
$created
$modified
$user_code
$email
$email_verified
$mobile_number
$mobile_verified

This data frame contains user account information, such as when the account was created, the user's contact details, and whether they have been verified. This is usually empty, because most study participants don't sign up on formr.

survey_run_sessions
$session
$created
$last_access
$ended
$position
$current_unit_id
$deactivated
$no_email

This data frame tracks user sessions in the run/study, including when they started the study (created), last accessed it, ended it (reached a Stop button), the current position in the run, and whether the user has opted out of email notifications.

survey_unit_sessions
$created
$ended
$expired
$unit_id
$position
$type

This data frame contains metadata about the progression of the user through the run/study, including when they reached each unit (created), left it (ended), and so on.

externals
$created
$ended
$position

Metadata about external units linked to the study, i.e. when users were sent there, whether they returned/completed the external unit (ended) and the position in the run.

survey_items_display
$created
$answered_time
$answered
$displaycount
$item_id

This data frame tracks the display and response behavior for survey items, including timestamps for when they were displayed and answered.

survey_email_log
$email_id
$created
$recipient

This data frame logs email interactions, including when an email was sent and its recipient.

shuffle
$unit_id
$created
$group

This data frame tracks shuffled units and the group they belong to for randomisation purposes.

Packages

Wherever you use R in formr you can also use the functions in its R package. If you want to use the package in a different environment, you'll need to install it using the following code.

install.packages('formr', repos = c('https://rforms.r-universe.dev', 'https://cloud.r-project.org'))

The package currently has the following feature sets

• Some shorthand functions for frequently needed operations on the site:

  first(cars) # first non-missing value
  last(cars) # last non-missing value
  current(cars) # last value, even if missing
  "formr." %contains% "mr." # will yield TRUE
  "formr." %contains_word% "mr" # will yield FALSE
  "12, 15" %contains% "1" # will yield TRUE
  "12, 15" %contains_word% "1" # will yield FALSE

• Some helper functions to make it easier to correctly deal with dates and times:

  time_passed(hours = 7) 
  next_day()
  in_time_window(time1, time2)

• Connecting to formr, importing your data, correctly typing all variables, automatically aggregating scales.
• Easily making feedback plots e.g.

  qplot_on_normal(0.8, "Extraversion")

  The package also has a function to simulate possible data, so you can try to make feedback plots ahead of collecting data.

Further data

Sometimes, you need more than the data that formr auto-enriches your study with. For example, you might have designed a couples' diary study and need the partner's data to synchronize participation. In these cases, you will have to explicitly load the data using