Replay a finished session in the browser

Writes one self-contained HTML file that steps through a finished focus group from its saved records: a title page, one page per participant, then every logged message in order, with the record of each speaker selection before the turn it chose and each private answer where it was asked, and an end page. No model is called and nothing is reconstructed: a record the page needs but the session lacks stops the function with an error naming it.

Usage

fg_player(
  x,
  file = NULL,
  arm = NULL,
  annotations = NULL,
  mode = c("step", "static"),
  strip_speaker_prefix = FALSE,
  open = interactive()
)

Arguments

x: A focus_group_result from run_focus_group(), a focus_group_arms from run_focus_group_arms(), a FocusGroup object after run_simulation(), or the list that FocusGroup$run_arms() returns.
file: Path of the HTML file to write. NULL (the default) writes a temporary file. When x holds several arms and arm is NULL, one file is written per arm, each holding the shared messages and that arm's continuation; file then names a directory (a new temporary one when NULL), and the files are named <arm>.html.
arm: NULL, or the name of the one arm to replay.
annotations: Optional named list, by participant ID, of named character vectors shown on that participant's page and sidebar card, for example list(P1 = c(stake = "high")).
mode: "step" (the default) shows one step at a time; "static" shows every step at once, for printing and archives.
strip_speaker_prefix: FALSE (the default) shows every message as recorded. TRUE drops a speaker label that the model wrote at the start of its own line, such as "**MOD:**" in a moderator line or "P3:" in the reply of the participant whose handle is P3, never another speaker's label; a speaker's own label is its handle, not its ID. The title page says so and counts the lines changed.
open: Open the file with utils::browseURL(). The default opens it in an interactive session.

Value

The path of the file written, invisibly. For several arms, a character vector of paths named by arm.

Details

The page reads these records: transcript, with each message's metadata (verbatim moderator lines, injected comments, call-ons, and addressed turns); routing, for the scores, exclusions, tie draws, and rule behind each participant turn; probes, placed after the message named by after_message_id; participants, for each persona as sent, without the standing rules; summary; and metadata. Results saved by FocusGroup 0.5.3 and earlier lack routing and probes, so the function stops for them. For results without the handle column of 0.5.5, each speaker's handle is its ID.

The steps, in order:

a title page: topic and purpose, the number of participants, whether the moderator's lines were read as written or written by the model, the turn-taking rule, responses per question, model, date, package versions, and arm;
one page per participant: ID and handle, the persona as sent, and any annotations, with that participant's sidebar card highlighted;
one step per logged message: the roster line, moderator lines, injected comments marked with their source, and participant turns;
before each participant turn, a panel with the selection record: under desire-based selection, the score of every participant asked, those not asked with the reason, the participant chosen, and whether a tie was drawn at random; under probabilistic selection, each participant's chance of being drawn; for a call-on or a participant the moderator addressed, that fact. Round robin gets no panel;
each private question, as a panel with every answer, placed where it was asked; no agent sees these answers;
an end page with the turns of every participant, zeros included, and the final summary, which the model wrote after the session.

In "step" mode the right arrow, space, Page Down, Enter, or a click shows the next step; the left arrow, Page Up, or Backspace goes back; Home returns to the first page; End shows every step; S shows or hides the selection panels; and F toggles full screen. A presentation clicker sends Page Down and Page Up. Adding #step=12 to the address opens the page at step 12.

Each participant has one color, used in the sidebar, the turns, and the score bars: the Okabe-Ito palette for up to 7 participants and Paul Tol's muted scheme for 8 or 9, both readable with the common forms of color blindness. Beyond 9 the colors come from grDevices::hcl.colors(n, "Dark 3"), with a message, and are harder to tell apart. The moderator is gray.

The file needs no network connection: styles, script, and data are inline. Model text is inserted as text, never as markup; only **bold** and *italics* are rendered.

Examples

session <- readRDS(system.file("extdata", "player-session.rds",
                               package = "FocusGroup"))
page <- fg_player(session, file = tempfile(fileext = ".html"),
                  open = FALSE)
file.exists(page)
#> [1] TRUE

# Every step at once, with annotations on two participants' pages.
fg_player(session, file = tempfile(fileext = ".html"), mode = "static",
          annotations = list(P1 = c(recruited = "library newsletter"),
                             P2 = c(recruited = "hospital notice board")),
          open = FALSE)

Usage

Arguments

Value

Details

See also

Examples