Package 'FocusGroup'

Description

Runs descriptive analyses offline. Thematic analysis and a model-generated summary are opt-in and run only when 'config' is supplied.

Usage

analyze_focus_group(
  focus_group_result,
  num_topics = 5,
  include_plots = TRUE,
  speakers = c("participants", "all"),
  language = "en",
  config = NULL,
  .runner = NULL
)

Arguments

Value

A 'focus_group_analysis' containing returned analysis components and an 'issues' table.

Examples

transcript <- data.frame(
  speaker = c("Moderator", "P1", "P2"),
  text = c("What matters most?", "Cost matters.", "Access matters.")
)
fg <- focus_group_from_transcript(transcript)
analysis <- analyze_focus_group(fg, include_plots = FALSE)
analysis$basic_stats$speaker_stats

Description

'ConversationFlow' is an R6 base class defining the interface for turn-taking mechanisms in a focus group simulation. Subclasses implement specific strategies for selecting the next speaker.

Value

An R6 generator meant for subclassing; instances are built by [create_conversation_flow()], which returns a 'ConversationFlow' subclass object ready for [FocusGroup].

Methods for Subclassing

'initialize(agents, moderator_id)'

Sets up the flow. Call 'super$initialize(agents, moderator_id)'.

'select_next_speaker(focus_group)'

*Required*. Logic to choose the next 'FGAgent' to speak. Should return the agent object or 'NULL'.

'update_state_post_selection(speaker_id, focus_group)'

Optional. Updates internal state after a speaker has spoken. Base implementation updates 'self$last_speaker_id'.

Public fields

Methods

Public methods

• ConversationFlow$new()

• ConversationFlow$select_next_speaker()

• ConversationFlow$update_state_post_selection()

• ConversationFlow$clone()

Method new()

Initializes the ConversationFlow object.

Usage

ConversationFlow$new(agents, moderator_id)

Arguments

Method select_next_speaker()

Selects the next speaker. Must be implemented by subclasses.

Usage

ConversationFlow$select_next_speaker(focus_group)

Arguments

Returns

The 'FGAgent' object of the selected speaker, or 'NULL'.

Method update_state_post_selection()

Updates internal state after a speaker is selected.

Usage

ConversationFlow$update_state_post_selection(speaker_id, focus_group)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

ConversationFlow$clone(deep = FALSE)

Arguments

Examples

RandomFlow <- R6::R6Class("RandomFlow", inherit = ConversationFlow,
  public = list(
    select_next_speaker = function(focus_group) {
      ids <- self$participant_ids
      self$agents[[sample(ids, 1)]]
    }))

Description

Creates participant agents from supplied records, direct personas, or the bundled ANES 2024 records, and adds a moderator.

Usage

create_agents(
  n_participants,
  config,
  demographics = NULL,
  survey_responses = NULL,
  direct_persona_descriptions = NULL,
  .runner = NULL
)

Arguments

Value

A named list of FGAgent objects (participants + 1 moderator), keyed by agent ID.

Examples

## Not run: 
cfg <- LLMR::llm_config("openai", "gpt-4o-mini")
agents <- create_agents(6, config = cfg)

# Create with custom demographics
demo_data <- data.frame(
  age = c(22, 35, 28, 41, 19, 33),
  gender = c("Female", "Male", "Male", "Female", "Male", "Female"),
  education = c("Bachelor's", "Master's", "High School", "PhD", "Some College", "Bachelor's")
)
agents <- create_agents(6, config = cfg, demographics = demo_data)

## End(Not run)

Description

Like [create_agents_from_survey()] but starting from a data frame already in memory (for example 'LLMR::anes_2024_personas'). Demographic columns are rendered as background; the remaining columns are rendered as survey responses, keyed by their question wording when the frame carries a 'dictionary' attribute (see [LLMR::llm_persona_split()]), else by their column names. Values are taken as-is (decode and clean them first if they are still coded).

Usage

create_agents_from_data(
  data,
  n_participants,
  config,
  demographic_cols = NULL,
  rows = NULL,
  weights = NULL,
  .runner = NULL
)

Arguments

Details

A frame of class 'silicon_panel', or a frame with both 'persona' and 'persona_id' columns, is treated as a pre-rendered persona panel. Its ‘persona' text becomes each participant’s direct persona description; 'persona' and 'persona_id' are not rendered as survey answers. This bridge uses the frame's structure and does not require LLMRpanel.

Value

A named list of 'FGAgent' objects (participants + moderator), keyed by agent ID.

Examples

## Not run: 
data(anes_2024_personas, package = "LLMR")
cfg <- LLMR::llm_config("openai", "gpt-4o-mini")
agents <- create_agents_from_data(
  anes_2024_personas, n_participants = 6, config = cfg
)

## End(Not run)

Description

Reads a labeled survey file (Stata '.dta', SPSS '.sav', or SAS '.sas7bdat'), decodes the chosen variables from their value labels, and turns each selected respondent into an 'FGAgent' whose persona states that respondent's demographics and survey answers. Numeric codes are decoded from the file's own value labels, so the same call works on ANES, GSS, WVS, or any other labeled file; nothing about a particular dataset is hard-coded.

Usage

create_agents_from_survey(
  n_participants,
  survey_path,
  config,
  demographic_vars = NULL,
  survey_vars = NULL,
  rows = NULL,
  weights = NULL,
  na_strings = .fg_default_na_strings,
  .runner = NULL
)

Arguments

Details

The survey answers are keyed by each variable's question wording (its label in the file) so the model sees the item, not a code name. The persona draws no inferences from the answers; it states them and lets the model interpret.

Value

A named list of 'FGAgent' objects (participants + moderator), keyed by agent ID.

See Also

[create_agents_from_data()] for an in-memory data frame, and 'LLMR::anes_2024_personas' for a ready-made example.

Examples

## Not run: 
agents <- create_agents_from_survey(
  n_participants = 6,
  survey_path = "anes_timeseries_2024_stata.dta",
  config = LLMR::llm_config("openai", "gpt-4o-mini"),
  demographic_vars = c(age = "V241458x", education = "V241465x"),
  survey_vars = c("Party identification" = "V241227x",
                  "Ideology" = "V241177"),
  rows = function(df) df$age != "18-24"   # exclude the youngest band
)

## End(Not run)

Description

Factory function to create an instance of a 'ConversationFlow' subclass.

Usage

create_conversation_flow(mode, agents, moderator_id, flow_params = list())

Arguments

Value

An initialized 'ConversationFlow' object (e.g., 'RoundRobinFlow', 'ProbabilisticFlow', 'DesireBasedFlow').

Examples

# Assuming FGAgent class and agents list (agent1, agent2, mod) are defined
# mod_id <- "MOD"
# all_my_agents <- list(P1 = agent1, P2 = agent2, MOD = mod)
# flow <- create_conversation_flow("desire_based", all_my_agents, mod_id)

Description

FGAgent Class

FGAgent Class

Details

Represents an agent (participant or moderator) in a focus group simulation. Each agent has a unique ID, a persona, an LLM configuration, and methods to generate utterances and express a desire to speak.

Value

An R6 generator. 'FGAgent$new(id, agent_details, config, is_moderator = FALSE, .runner = NULL)' returns an 'FGAgent'; [create_agents()] and its relatives construct whole rosters.

Customizing Agents

'FGAgent' is designed to be flexible:

• **Per-Agent LLM Configuration**: Each agent is initialized with its own 'llm_config' (stored in the 'config' field). This allows different agents to use different LLMs, temperatures, or even providers.

• **Persona Definition**: The 'agent_details' (containing 'demographics', 'survey_responses', 'direct_persona_description', and/or 'communication_style') are used to construct the 'persona_description' and 'communication_style_instruction'.

• **Subclassing**: For advanced customization, inherit from 'FGAgent' to override methods or add new fields.

Public fields

Methods

Public methods

• FGAgent$new()

• FGAgent$generate_utterance()

• FGAgent$get_need_to_talk()

• FGAgent$clone()

Method new()

Initialize a new FGAgent.

Usage

FGAgent$new(id, agent_details, config, is_moderator = FALSE, .runner = NULL)

Arguments

Method generate_utterance()

Generate an utterance for the agent.

Usage

FGAgent$generate_utterance(
  topic,
  conversation_history_string,
  utterance_prompt_template,
  max_tokens_utterance = 150,
  current_moderator_question = "N/A",
  conversation_summary_so_far = "N/A",
  current_phase = "discussion",
  conversation_log = NULL,
  standing_rules = NULL,
  self_state = TRUE
)

Arguments

Returns

A list with 'text' (the generated utterance) and 'meta' (a list of call metadata: token counts, finish reason, provider, model, timing).

Method get_need_to_talk()

Get the agent's "desire to talk" score. This method queries the LLM to rate how strongly the agent feels the need to contribute to the discussion at the current moment.

Usage

FGAgent$get_need_to_talk(
  topic,
  conversation_history_string,
  desire_prompt_template,
  max_tokens_desire = 20,
  current_moderator_question = "N/A",
  last_speaker_id = "N/A",
  last_utterance_text = "N/A",
  conversation_log = NULL
)

Arguments

Returns

Numeric. A score from 0 (no desire) to 10 (very strong desire).

Method clone()

The objects of this class are cloneable with this method.

Usage

FGAgent$clone(deep = FALSE)

Arguments

Examples

cfg <- LLMR::llm_config("groq", "openai/gpt-oss-20b",
                        api_key = LLMR::llm_api_key_env("GROQ_API_KEY"))
a <- FGAgent$new(
  id = "P1",
  agent_details = list(direct_persona_description = "A retired teacher."),
  config = cfg)
a$persona_description

Description

Turns a transcript that the package did not generate – a human focus group, a transcript exported from other software, or a saved CSV – into a [FocusGroup] object whose 'conversation_log' holds the imported turns. The returned object supports the analysis methods ('analyze()', 'analyze_participation_balance()', 'analyze_topics()', 'analyze_tfidf()', 'analyze_readability()', 'analyze_themes()'), the plotting methods, and [analyze_focus_group()]. No model call is made: importing and the descriptive analyses run offline, and only the model-dependent methods ('analyze_themes()', 'summarize()') contact a provider when you call them.

Usage

focus_group_from_transcript(
  data,
  speaker_col = "speaker",
  text_col = "text",
  topic = NULL,
  moderator_id = NULL
)

Arguments

Details

One lightweight agent is created per speaker so that speaker-aware methods have a roster to report on; these agents carry a minimal placeholder persona and are not meant to continue the conversation. Set 'moderator_id' when the transcript identifies the moderator. When it is 'NULL', the moderator is the first speaker whose id contains "mod" (case-insensitive), e.g. "Moderator" or "MOD". When the fallback finds no match, a non-speaking "MOD" agent is added so the object is complete, and it appears in 'analyze()' with zero utterances. Rows whose speaker is missing or blank are dropped with a warning; rows with speaker "System" are kept in the log but excluded from analyses, matching how the simulator treats its own roster message.

Value

A [FocusGroup] object with a populated 'conversation_log'.

See Also

[analyze_focus_group()] to run the descriptive analyses in one call; [run_focus_group()] to simulate a discussion instead.

Examples

transcript <- data.frame(
  speaker = c("Moderator", "Ana", "Ben", "Ana", "Moderator", "Ben"),
  text = c(
    "Welcome, everyone. What do you make of the new library hours?",
    "They help working parents like me; evenings matter most.",
    "I see it differently. Mornings are now far too crowded.",
    "Crowded mornings still beat being locked out after work.",
    "Ben, say more about what changed in the mornings.",
    "Staff are stretched thin before noon, so lines are longer."
  )
)
fg <- focus_group_from_transcript(transcript, topic = "library hours")
fg$analyze_participation_balance()$participation_stats

Description

Main R6 class for managing and running a focus group simulation. It orchestrates the simulation through distinct phases (Opening, Icebreaker, Engagement, Exploration, Closing) guided by a question script, manages agent interactions via a turn-taking flow, and provides methods for analysis and visualization of the conversation.

Value

An R6 generator. 'FocusGroup$new()' returns a session object; most analyses run through [run_focus_group()], which builds, runs, and returns one. Construction alone makes no model call.

Public fields

Methods

Public methods

• FocusGroup$new()

• FocusGroup$run_simulation()

• FocusGroup$summarize()

• FocusGroup$analyze()

• FocusGroup$analyze_topics()

• FocusGroup$analyze_tfidf()

• FocusGroup$analyze_readability()

• FocusGroup$analyze_themes()

• FocusGroup$analyze_statistics()

• FocusGroup$analyze_participation_balance()

• FocusGroup$analyze_response_patterns()

• FocusGroup$analyze_question_patterns()

• FocusGroup$analyze_key_phrases()

• FocusGroup$plot_participation_timeline()

• FocusGroup$plot_word_count_distribution()

• FocusGroup$plot_participation_by_agent()

• FocusGroup$plot_message_length_timeline()

• FocusGroup$clone()

Method new()

Initialize a new FocusGroup simulation.

Usage

FocusGroup$new(
  topic,
  purpose,
  agents,
  moderator_id,
  turn_taking_flow,
  question_script = list(),
  prompt_templates = list(),
  admin_config = NULL,
  max_tokens_config = list(),
  max_participant_responses = NULL
)

Arguments

Method run_simulation()

Run the full focus group simulation. Iterates through the 'question_script' phases or a specified number of rounds.

Usage

FocusGroup$run_simulation(num_rounds = NULL, verbose = FALSE)

Arguments

Returns

Invisibly returns the 'conversation_log'.

Method summarize()

Generate a summary of the conversation using an LLM.

Usage

FocusGroup$summarize(
  config,
  summary_level = 1,
  max_tokens = NULL,
  internal_call = FALSE,
  transcript_override = NULL,
  .runner = NULL
)

Arguments

Returns

Character string containing the generated summary.

Method analyze()

Basic analysis of the conversation log.

Usage

FocusGroup$analyze(message_ids = NULL, speaker_ids = NULL)

Arguments

Returns

A list with 'speaker_stats' (a tibble: speaker_id, utterance_count, total_words, avg_words_per_utterance) and 'full_transcript' (character string).

Method analyze_topics()

Perform LDA topic modeling on the conversation.

Usage

FocusGroup$analyze_topics(
  num_topics = 5,
  min_doc_length = 20,
  top_n_terms = 10,
  message_ids = NULL,
  speaker_ids = NULL,
  seed = 110,
  unit = c("message", "speaker"),
  ...
)

Arguments

Returns

A list with LDA model, topic terms, and document-topic proportions. 'NULL' on failure.

Method analyze_tfidf()

Calculate TF-IDF scores for terms per participant.

Usage

FocusGroup$analyze_tfidf(
  top_n_terms = 10,
  message_ids = NULL,
  speaker_ids = NULL,
  ...
)

Arguments

Returns

A tibble with TF-IDF scores.

Method analyze_readability()

Calculate readability scores for each participant's aggregated text.

Usage

FocusGroup$analyze_readability(
  measures = "Flesch",
  message_ids = NULL,
  speaker_ids = NULL
)

Arguments

Returns

A tibble with readability scores.

Method analyze_themes()

Perform LLM-assisted thematic analysis on the transcript.

Usage

FocusGroup$analyze_themes(
  config,
  message_ids = NULL,
  speaker_ids = NULL,
  .runner = NULL
)

Arguments

Returns

The thematic summary as a character string. An empty transcript returns 'character(0)'. Provider failures are propagated.

Method analyze_statistics()

Perform statistical analysis on conversation patterns.

Usage

FocusGroup$analyze_statistics(message_ids = NULL, speaker_ids = NULL)

Arguments

Returns

A list with ANOVA results, phase participation stats, and correlations.

Method analyze_participation_balance()

Analyze participation balance and dominance patterns.

Usage

FocusGroup$analyze_participation_balance(
  message_ids = NULL,
  speaker_ids = NULL
)

Arguments

Returns

A list with participation statistics and balance metrics.

Method analyze_response_patterns()

Analyze response patterns and interaction behaviors.

Usage

FocusGroup$analyze_response_patterns(message_ids = NULL, speaker_ids = NULL)

Arguments

Returns

A list with response and interaction pattern metrics.

Method analyze_question_patterns()

Analyze question asking patterns during the conversation.

Usage

FocusGroup$analyze_question_patterns(message_ids = NULL, speaker_ids = NULL)

Arguments

Returns

A list with question pattern analysis.

Method analyze_key_phrases()

Extract and analyze key phrases using n-grams.

Usage

FocusGroup$analyze_key_phrases(
  min_freq = 2,
  message_ids = NULL,
  speaker_ids = NULL
)

Arguments

Returns

A list with bigram and trigram analysis.

Method plot_participation_timeline()

Create a participation timeline of cumulative messages by participant across phases.

Usage

FocusGroup$plot_participation_timeline()

Returns

ggplot object

Method plot_word_count_distribution()

Create word count distribution plot showing message length patterns.

Usage

FocusGroup$plot_word_count_distribution()

Returns

ggplot object

Method plot_participation_by_agent()

Create a participation by agent plot showing total messages per participant.

Usage

FocusGroup$plot_participation_by_agent()

Returns

ggplot object

Method plot_message_length_timeline()

Create a timeline showing message length over message order.

Usage

FocusGroup$plot_message_length_timeline()

Returns

ggplot object

Method clone()

The objects of this class are cloneable with this method.

Usage

FocusGroup$clone(deep = FALSE)

Arguments

Examples

cfg <- LLMR::llm_config("groq", "openai/gpt-oss-20b",
                        api_key = LLMR::llm_api_key_env("GROQ_API_KEY"))
agents <- create_agents(
  n_participants = 2, config = cfg,
  direct_persona_descriptions = c("A retired teacher.",
                                  "A night-shift nurse."))
flow <- create_conversation_flow("round_robin", agents, "MOD")
fg <- FocusGroup$new(topic = "Neighborhood safety",
                     purpose = "Pilot the moderator guide.",
                     agents = agents,
                     moderator_id = "MOD",
                     turn_taking_flow = flow)
fg$topic

Description

Retrieves a list containing the default prompt templates used by the 'FocusGroup' package. These templates guide the behavior of LLM agents (participants and moderator) during different phases and actions within the simulation.

Usage

get_default_prompt_templates()

Details

Users can retrieve this list, modify specific templates, and then pass the modified list to ‘FocusGroup$new()' or higher-level wrapper functions to customize the simulation’s prompts.

Value

A named list where each element is a character string representing a prompt template. Placeholders like '{{topic}}', '{{persona_description}}', etc., are used within the templates and will be filled dynamically during the simulation.

Participant templates and message construction

Two participant templates ship here, and which one is used depends on the message construction (see the 'message_mode' argument of [run_focus_group()], or 'options(focusgroup.message_mode=)').

• 'participant_turn_instruction' is the canonical template for the default role-flipped construction. It carries only the current question and the turn cue, because the persona, standing rules, and the transcript are supplied structurally (a system message plus role-separated turns).

• 'participant_utterance_subtle_persona' is the flat template. It inlines the persona and the whole transcript into one user message. A custom template that contains '{{conversation_history}}' or '{{persona_description}}' is treated as a flat template and routed through the flat path.

Examples

default_prompts <- get_default_prompt_templates()
print(names(default_prompts))
print(default_prompts$participant_utterance_subtle_persona)

# To customize a prompt:
my_prompts <- get_default_prompt_templates()
my_prompts$moderator_opening <- "Welcome all! Let us talk about {{topic}} today."
# Then use `my_prompts` when creating a FocusGroup object.

Description

Constructs the agents, moderator guide, and turn-taking flow, then runs one focus group session. 'config' has no default; every agent and group-level call uses the one supplied. Before a live run, the function estimates the number of generated model outputs and applies the 'max_calls' limit unless 'confirm' is 'TRUE'.

Usage

run_focus_group(
  topic,
  config,
  n_participants = 6,
  guide = c(Opening = 1, Icebreaker = 1, Engagement = 2, Exploration = 3, Closing = 1),
  demographics = NULL,
  survey_responses = NULL,
  flow = "desire_based",
  seed = NULL,
  message_mode = c("roleflip", "flat"),
  verbose = TRUE,
  max_participant_responses = NULL,
  max_calls = 100L,
  confirm = FALSE,
  .runner = NULL
)

Arguments

Value

A 'focus_group_result' with the group, transcript, summary, participant table, token usage, and sanitized metadata.

Examples

## Not run: 
cfg <- LLMR::llm_config("openai", "gpt-4o-mini")
result <- run_focus_group(
  topic = "Library funding priorities",
  config = cfg,
  n_participants = 4,
  guide = list(
    Opening = "Welcome the participants and state the ground rules.",
    Exploration = "Which funding priority deserves attention first?",
    Closing = "Thank the participants and close the session."
  ),
  flow = "round_robin"
)

## End(Not run)

Description

A point-and-click front end with three tabs. Run a focus group starts a fresh moderated session live from a topic and a handful of participants, shows the transcript, and offers a complete .rds session and transcript CSV. Analyze accepts a finished run, saved session, CSV, or bundled example and runs the package's descriptive analyses offline; thematic analysis and a model summary are optional live actions. The continuation experiment takes a saved focus group up to a message and compares repeated next-message responses under one control history and several labeled treatment histories. Running and the continuation experiment generate text and need an API key; analysis works offline.

Usage

run_focus_studio(...)

Arguments

Details

The GUI is optional. It needs the suggested packages shiny, bslib, DT, and LLMR.shiny; install them first. Keys are read from environment variables only, never pasted into the app.

Value

Invisibly, the value of shiny::runApp(); called for the side effect of starting the app.

Examples

if (interactive() &&
    all(vapply(c("shiny", "bslib", "DT", "LLMR.shiny"),
               requireNamespace, logical(1), quietly = TRUE))) {
  run_focus_studio()
}