Report how each persona was rendered — persona_rendering

Returns the record, kept with a roster, of how every requested demographic field and survey item was rendered into each participant's persona: the text shown, or the reason it was left out. Rosters built from respondent records by create_agents_from_survey(), create_agents_from_data(), and create_agents() carry the report; check it before a session runs.

Usage

persona_rendering_report(x)

Arguments

x: A roster returned by one of the constructors, a FocusGroup built from such a roster, or the result of run_focus_group().

Value

A data frame with one row per participant and rendered field or item, in the order requested. A variable requested more than once has one row, and a sampling-weight column, which is never rendered, has none. The columns are:

agent_id: The participant ID.
kind: "demographic" or "item".
variable: The variable in the file, or the column of the data.
question: The text shown for it: the field label of a demographic, the question of an item.
question_source: Where that text came from: "wording" (question_wording), "name" (a name given to the variable), "dictionary" (the data's dictionary), "label" (the variable label), or "variable" (the variable name itself).
code: The stored value, as text; NA when there is none.
text: The answer as it appears in the persona; NA when dropped.
rendered_as: "label", "supplied_label" (from value_labels), "scale", "value", or "code"; NA when dropped.
status: "rendered", "fallback", or "dropped".
reason: Why a field is a fallback or was dropped; NA otherwise.
template: For an answer shown on a scale, the scale_template used; NA otherwise.

The call stops when x carries no report, as for a roster built from supplied persona text or a list subset from a roster.

Details

A field is "rendered" when the persona states it as the source gives it. It is a "fallback" when the persona shows it in a form that needs checking: a code that has no value label, shown as the code; a label exactly 80 characters long, which some survey releases (the ANES 2024 Stata file among them) produce by cutting longer labels; or the label of a negative code that does not match na_strings, where the release may use negative codes for missing data; or a field of a supplied record that holds several values, of which the persona shows the first. It is "dropped" when the persona leaves it out, which happens when there is no answer to show: no value, a value whose label is a missing-data label or is empty, a text value that is a missing-data label (see Rendering answers in create_agents_from_survey()), a negative code without a label, an SPSS user-defined missing value, a record field that does not hold a single value, or a variable that is not in the file. An identifier is dropped too, with the reason "identifier column": a column whose name identifies respondents (id, caseid, respondent_id, respid, persona_id, uid, record_id, row_id, ResponseId, participant_id, subject_id, user_id, PROLIFIC_PID, workerId, caseno, or QKEY, in any case and with or without separators, as in ID or CaseID), or, among the items create_agents_from_survey() chooses when survey_vars is NULL, a variable that looks like a case ID, as described there. The agents would otherwise read the respondent's ID; the roster keeps it in source_ids.

Examples

toy <- data.frame(
  age = c(25, 41, 80),
  abortion = haven::labelled(c(2, 7, -9), c(
    "1. Always permitted" = 1, "7. Never permitted" = 7, "-9. Refused" = -9))
)
path <- file.path(tempdir(), "toy_scale.dta")
haven::write_dta(toy, path)
agents <- create_agents_from_survey(
  n_participants = 3, survey_path = path,
  config = LLMR::llm_config("groq", "openai/gpt-oss-20b",
                            api_key = LLMR::llm_api_key_env("GROQ_API_KEY")),
  demographic_vars = c(age = "age"), survey_vars = "abortion",
  question_wording = c(abortion = "Where would you place yourself on abortion?")
)
#> 1 answer(s) were left out of the personas as missing values (abortion); persona_rendering_report() lists them.
report <- persona_rendering_report(agents)
report[, c("agent_id", "variable", "text", "status")]
#>   agent_id variable
#> 1       P1      age
#> 2       P1 abortion
#> 3       P2      age
#> 4       P2 abortion
#> 5       P3      age
#> 6       P3 abortion
#>                                                                                                   text
#> 1                                                                                                   25
#> 2 On a scale of 1 to 7, where 1 is Always permitted and 7 is Never permitted, you place yourself at 2.
#> 3                                                                                                   41
#> 4                                                                                      Never permitted
#> 5                                                                                                   80
#> 6                                                                                                 <NA>
#>     status
#> 1 rendered
#> 2 rendered
#> 3 rendered
#> 4 rendered
#> 5 rendered
#> 6  dropped