Automated Feedback Report Generator

The Automated Feedback Report Generator takes a whole study’s worth of questionnaire responses and produces one bespoke, personalised report per participant — a polished HTML (and optionally PDF) feedback sheet that scores each person’s answers, places them against published population norms, and explains what the results mean in plain language. Point it at a CSV, run one script, and every respondent gets a document written for them.

It’s the batch, report-writing counterpart to the lab’s live Participant Feedback & Survey Platform: where that platform gives instant feedback inside a survey site, this pipeline generates rich, self-contained reports offline from an existing dataset — ideal for studies run through Qualtrics or REDCap, where the responses already exist and each participant is owed something back.

Why this matters for participation

Research participation is usually a one-way transaction: people give their time and their data, and receive a bare “thank you for participating” screen in return. That is a missed opportunity — and increasingly, a limiting one, as paid recruitment gets more expensive and participants get more discerning about where they spend their attention.

A personalised feedback report is a non-monetary reward, and there is good evidence that this kind of reward works. Giving participants a genuine, individual result — something about them, that they could not have got anywhere else — measurably increases willingness to take part, completion rates, and willingness to share data. The lab has seen this first-hand: its public self-test built on the same feedback-first principle has been completed by more than 40,000 people who chose to share their data for research. A study that offers a real personality report at the end is simply a more attractive study to join, without adding a cent to the incentive budget.

Turning data collection into collaboration

Beyond the recruitment maths, feedback reshapes the relationship between researcher and participant. When someone receives a careful, honest account of their own HEXACO profile, their personal values, and how they make sense of their life story, the exchange stops being extractive and starts to feel like a collaboration — the researcher learns from the participant, and the participant learns something about themselves in return.

That reciprocity has knock-on benefits the lab cares about: participants who feel like collaborators engage more thoughtfully, are more likely to return for follow-up waves, and become advocates who bring others in. It also raises the ethical floor of a study — people leave understanding what they contributed to and what it says about them, rather than handing over data into a void.

How it works

The pipeline is deliberately simple to run — edit a short config block, then run one script:

1. Prepare the data. Export your responses to a CSV in data/, with one row per participant: a username column (used to name each output file) plus the raw item responses — hexaco_1…hexaco_100, pvq_1…pvq_21, and nise_1…nise_20. A five-person synthetic dataset ships with the repo so you can see the whole thing run end-to-end before touching real data.
2. Configure the run. In master.R, set the project name, the dataset file, which rows to render ("all" or a selection like "1,3:5"), and whether you want HTML, PDF, or both.
3. Score the scales. Dedicated scripts score each instrument — the HEXACO-100 (six traits and their 24 facets), the PVQ-21 (ten of Schwartz’s basic human values), and the NISE (four narrative-identity dimensions) — handling reverse-keyed items and converting each raw score to a percentile via the embedded normative means and SDs.
4. Render the reports. A parameterised Quarto template (feedback_template.qmd + styles.css) is rendered once per participant, producing Personality_report_for_<username>.html in reports/<project_name>/. Each report is a single self-contained file — no assets to ship alongside it — so it can be emailed straight to a participant.

# master.R — the whole config surface
project_name  <- "my_study"       # → reports/my_study/
dataset_file  <- "my_data.csv"    # a file in data/
row_selection <- "all"            # or e.g. "1,3:5"
render_html   <- TRUE
render_pdf    <- FALSE            # set TRUE once LaTeX is installed

source(here::here("master.R"))    # run it

A nice touch for anyone who has fought with cloud-synced folders: the render loop copies the template to a local temp directory before Quarto runs, which sidesteps a notorious hang where OneDrive/iCloud/Dropbox stall the subprocess that opens the template. A bug_checks/diagnostics.R script prints a [PASS]/[FAIL] check of the whole environment if anything misbehaves.

An example report

Here is a full report generated by the pipeline from the synthetic dataset — one of the five example participants that ship with the repo:

▶ Open the example HTML report

(Synthetic data — “Alice Smith” and the study branding are illustrative placeholders, not a real participant.)

The report opens with a personal welcome and a checklist of the measures completed, then walks the reader through their results:

• Part 1 — HEXACO Personality. A description of each of the six broad traits (Honesty-Humility, Emotionality, Extraversion, Agreeableness, Conscientiousness, Openness), the participant’s own standing on each shown against the population, and a breakdown of the 24 underlying facets.
• Part 2 — Personal Values (PVQ-21). Where the participant falls across Schwartz’s ten value types — from Self-Direction and Stimulation through to Security, Conformity, and Universalism.
• Part 3 — Narrative Identity (NISE). Four dimensions of how the participant makes meaning from their life story.
• Summary and references, closing with the citations for every instrument used, so the report is transparent about where its interpretations come from.

Because every score is expressed as a percentile relative to published norms, the participant gets an honest, contextualised picture — “higher than about 70% of people” rather than a bare number — which is exactly what makes the report feel like a reward worth having.

The code

The full pipeline — scoring scripts, Quarto template, styling, synthetic data, and the diagnostics — is open source and documented for reuse:

github.com/ConalMonaghan/Automatic-Feedback-Report-Generator

The scales are modular, so the same scaffolding can be adapted to whatever instruments a study uses: swap the scoring scripts and normative values, and the report-generation machinery carries over unchanged.