The formr R package is the official companion to the formr survey framework.
The former package is designed to provide useful helper functions inside formr surveys (for feedback plots and logic). Version 0.12.0 introduces a robust API client. Now, you can use R to manage your studies locally, sync files, control the version of your surveys, and securely fetch results.
We highly encourage you to work through the full documentation and tutorials. They are available at rubenarslan.github.io/formr.
⚠️ Compatibility Note: Version 0.12.0 introduces breaking changes to support the new formr API (v1). If your formr server instance does not yet support the v1 API, you should install the previous version (0.11.1).
To install the latest version (v0.12.0+):
if (!requireNamespace("remotes")) install.packages("remotes")
remotes::install_github("timseidel/formr")To install the legacy version (compatible with older servers):
remotes::install_github("rubenarslan/formr@873c3ba")To use the API features (fetching results, managing files), you must first authenticate. You can store your credentials securely in your system's keyring so you don't have to type them every time.
- Log in to formr.org and go to Account > API Settings.
- Create a Client ID and Secret.
library(formr)
# Store your credentials once
# This saves them securely in your OS credential store
formr_store_keys(
host = "https://formr.org", # or the URL of your instance
client_id = "YOUR_CLIENT_ID",
client_secret = "YOUR_CLIENT_SECRET"
)
# Then, in all of your scripts, simply run:
formr_api_authenticate(host = "https://formr.org") # Simply run:
formr_api_authenticate()The package provides tools to fetch data from complex runs and automatically join survey results, handle randomization (shuffles), and type items.
# 1. Fetch results from a run
# join = TRUE automatically merges multiple surveys and shuffles by session
results <- formr_results("my-run-name", join = TRUE)
# 2. Get the run structure (items, choices, types)
items <- formr_run_structure("my-run-name")
# 3. Post-process
# This handles type conversion, reverse-scoring, and aggregation for you.
cleaned_data <- formr_post_process_results("my-run-name")
# Your data is now ready for analysis!
head(cleaned_data)You can now develop surveys and runs locally (using Excel/JSON/RMarkdown) and sync them to the server. This allows you to use Git for version control.
Download everything—results, assets, survey items, and run structure—to a local folder.
formr_backup_run("my-run-name", dir = "backup_folder")You can pull a project structure, make edits to Excel files or CSS locally, and push them back.
# Initialize/Sync local folder with server state
formr_pull_project("my-run-name", dir = "my_project")
# ... Make changes to surveys/my-survey.xlsx or css/custom.css ...
# Push changes back to formr.org
formr_push_project("my-run-name", dir = "my_project")Control participants programmatically. Useful for automated testing or managing users.
# Create a test session
formr_create_session("my-run-name", testing = TRUE)
# Find a specific session
session_info <- formr_sessions("my-run-name", session_codes = "...")
# Move a user to a specific position in the run
formr_session_action("my-run-name", session_codes = "...", action = "move_to_position", position = 10)The package contains the utility functions used inside formr's OpenCPU environment for dynamic feedback and logic:
- Logic Shorthands:
time_passed(),%contains%,if_na(). - Feedback Plots:
qplot_on_normal(),qplot_on_bar(),feedback_chunk.
# Example: Check if a string contains a word
"apple, banana" %contains% "apple" # TRUE
# Example: Feedback text logic
feedback_chunk(0.5, c("Low", "Average", "High")) # Returns "Average"MIT