Fetch & Process Results
fetch-and-process-results.RmdThe new formr API (V1) provides a streamlined pipeline
for importing data. The API strictly separates fetching
(getting data from the server) from wrangling
(processing types, reversals, and scales), but the package provides a
powerful convenience wrapper, formr_api_results(), to
handle the entire process in one step.
1. Authentication
Before fetching data, ensure you are authenticated. If you have stored your keys (see Getting Started), this is automatic.
# Authenticate using stored credentials
formr_api_authenticate(host = "https://api.rforms.org", account = "dashboard") # or your custom URL and account name!2. The One-Stop Solution (formr_api_results)
The primary function is formr_api_results(). By default,
it performs a “Smart Fetch” that handles everything from download to
psychometric scoring.
# Fetch, reverse, aggregate, and join all data
df <- formr_api_results(run_name = "daily_diary")What does formr_api_results do by default?
- Downloads results and metadata for all surveys in the run.
- Recognises data types (converts “2023-01-01” to Dates, JSON arrays to lists, etc.).
-
Reverses items ending in
R(e.g.,neuro_3R) based on item choices. - Aggregates scales (calculates means for items with a shared stem).
- Joins all surveys into a single “wide” format (one row per session).
Customizing the Fetch
You can toggle these behaviors using arguments if you want raw data or need to handle processing manually:
# Get processed data, but strictly separated by survey (no join)
list_of_dfs <- formr_api_results("daily_diary", join = FALSE)
# Get raw data (types recognized, but NO reversing or scoring)
raw_data <- formr_api_results("daily_diary", compute_scales = FALSE)3. Advanced: The Manual Pipeline
If you used compute_scales = FALSE above, or if you are
debugging why a specific scale isn’t calculating correctly, you can use
the lower-level processing functions manually. These rely on the
survey’s metadata (the item table).
A. Get Metadata
Processing requires knowing which items are numeric, which are
reversed (e.g., ends in R), and what the scale options
are.
# Fetch the survey structure (contains all item metadata)
metadata <- formr_api_survey_structure("daily_diary")B. Reverse Coding (formr_api_reverse)
This function automatically reverses items that end in R
(e.g., bfi_neuro_3R). It uses the item’s defined choices
(e.g., 1 to 5) to calculate the reversal correctly:
.
# Apply reverse coding to raw results
df_reversed <- formr_api_reverse(results = raw_data, item_list = metadata)Result: The column bfi_neuro_3R now contains
reversed values. An attribute reversed = TRUE is added to
the column for tracking.
C. Aggregation (formr_api_aggregate)
This function calculates mean scores for items sharing a common
“stem”. For example, if you have extra_1,
extra_2, and extra_3R, the function detects
the stem extra, calculates the row-mean, and creates a new
column extra.
# Calculate scales (means)
df_scored <- formr_api_aggregate(results = df_reversed, item_list = metadata)Result: A new column extra is added to the
dataframe containing the mean of the items.
By default, at least 2 items are required to form a scale. You can
override this with min_items:
# Allow single-item "scales"
df_scored <- formr_api_aggregate(results = df_reversed, item_list = metadata, min_items = 1)4. Full Workflow Example
Here is a complete, reproducible snippet for a typical analysis
script. Note how formr_api_results simplifies the process
significantly compared to older versions of the package.
library(formr)
library(dplyr)
# 1. Connect
formr_api_authenticate(host = "https://api.rforms.org") # or your custom URL!
# 2. Get Processed Data (Reversed & Scored)
run_name <- "daily_diary"
data <- formr_api_results(run_name)
# 3. Analyze
summary(data$bfi_neuro) # This scale was computed automatically!
# ...