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). Each script handles reverse-keyed items and converts every 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, with 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.