Title: | Behavior Insight Design: A Toolkit for Integrating Behavioral Science in UI/UX Design |
Version: | 0.3.0 |
Description: | Provides a framework and toolkit to guide 'shiny' developers in implementing the Behavior Insight Design (BID) framework. The package offers functions for documenting each of the five stages (Notice, Interpret, Structure, Anticipate, and Validate), along with a comprehensive concept dictionary. |
License: | MIT + file LICENSE |
Encoding: | UTF-8 |
Depends: | R (≥ 4.1.0) |
RoxygenNote: | 7.3.2 |
Imports: | cli, DBI, dplyr, jsonlite, readr (≥ 2.1.5), RSQLite, stats, stringdist (≥ 0.9.15), stringr (≥ 1.5.1), tibble (≥ 3.2.1), utils |
Suggests: | DiagrammeR, knitr, rmarkdown, spelling, testthat (≥ 3.0.0) |
VignetteBuilder: | knitr |
Config/testthat/edition: | 3 |
Language: | en-US |
URL: | https://jrwinget.github.io/bidux/ |
NeedsCompilation: | no |
Packaged: | 2025-08-29 21:12:31 UTC; user |
Author: | Jeremy Winget |
Maintainer: | Jeremy Winget <contact@jrwinget.com> |
Repository: | CRAN |
Date/Publication: | 2025-08-29 21:30:02 UTC |
bidux: Behavior Insight Design: A Toolkit for Integrating Behavioral Science in UI/UX Design
Description
Provides a framework and toolkit to guide 'shiny' developers in implementing the Behavior Insight Design (BID) framework. The package offers functions for documenting each of the five stages (Notice, Interpret, Structure, Anticipate, and Validate), along with a comprehensive concept dictionary.
Author(s)
Maintainer: Jeremy Winget contact@jrwinget.com (ORCID)
See Also
Useful links:
Apply context-based scoring adjustments
Description
Apply context-based scoring adjustments
Usage
adjust_suggestion_score(suggestion, previous_stage, chosen_layout, concept)
Convert bid_stage to tibble
Description
Convert bid_stage to tibble
Usage
## S3 method for class 'bid_stage'
as_tibble(x, ...)
Arguments
x |
A bid_stage object |
... |
Additional arguments (unused) |
Value
A tibble
Document User Behavior Anticipation Stage in BID Framework
Description
This function documents the anticipated user behavior by listing bias mitigation strategies related to anchoring, framing, confirmation bias, etc. It also supports adding interaction hints and visual feedback elements.
Usage
bid_anticipate(
previous_stage,
bias_mitigations = NULL,
include_accessibility = TRUE,
...
)
Arguments
previous_stage |
A tibble or list output from an earlier BID stage function. |
bias_mitigations |
A named list of bias mitigation strategies. If NULL, the function will suggest bias mitigations based on information from previous stages. |
include_accessibility |
Logical indicating whether to include accessibility mitigations. Default is TRUE. |
... |
Additional parameters. If 'interaction_principles' is provided, it will be ignored with a warning. |
Value
A tibble containing the documented information for the "Anticipate" stage.
Examples
structure_info <- bid_structure(
bid_interpret(
bid_notice(
"Issue with dropdown menus",
evidence = "User testing indicated delays"
),
central_question = "How can we improve selection efficiency?",
data_story = list(
hook = "Too many options",
context = "Excessive choices",
tension = "User frustration",
resolution = "Simplify menu"
)
),
concepts = c("principle_of_proximity", "default_effect")
)
# Basic usage
bid_anticipate(
previous_stage = structure_info,
bias_mitigations = list(
anchoring = "Use context-aware references",
framing = "Toggle between positive and negative framing"
)
)
# Let the function suggest bias mitigations based on previous stages
bid_anticipate(
previous_stage = structure_info
)
# with accessibility included (default)
bid_anticipate(
previous_stage = structure_info,
bias_mitigations = list(
anchoring = "Use context-aware references",
framing = "Toggle between positive and negative framing"
),
include_accessibility = TRUE
)
Get detailed information about a specific concept
Description
Returns detailed information about a specific BID framework concept, including implementation recommendations based on the concept's stage.
Usage
bid_concept(concept_name, add_recommendations = TRUE)
Arguments
concept_name |
A character string with the exact or partial concept name |
add_recommendations |
Logical indicating whether to add stage-specific recommendations |
Value
A tibble with detailed concept information
Search BID Framework Concepts
Description
Search for behavioral science and UX concepts used in the BID framework. Returns concepts matching the search term along with their descriptions, categories, and implementation guidance.
Usage
bid_concepts(search = NULL, fuzzy_match = TRUE, max_distance = 2)
Arguments
search |
A character string to search for. If NULL or empty, returns all concepts. |
fuzzy_match |
Logical indicating whether to use fuzzy string matching (default: TRUE) |
max_distance |
Maximum string distance for fuzzy matching (default: 2) |
Value
A tibble containing matching concepts with their details
Ingest telemetry data and identify UX friction points
Description
This function ingests telemetry data from shiny.telemetry output (SQLite or JSON) and automatically identifies potential UX issues, translating them into BID framework Notice stages. It analyzes user behavior patterns to detect friction points such as unused inputs, delayed interactions, frequent errors, and navigation drop-offs.
Usage
bid_ingest_telemetry(path, format = NULL, thresholds = list())
Arguments
path |
File path to telemetry data (SQLite database or JSON log file) |
format |
Optional format specification ("sqlite" or "json"). If NULL, auto-detected from file extension. |
thresholds |
Optional list of threshold parameters: - unused_input_threshold: percentage of sessions below which input is considered unused (default: 0.05) - delay_threshold_seconds: seconds of delay considered problematic (default: 30) - error_rate_threshold: percentage of sessions with errors considered problematic (default: 0.1) - navigation_threshold: percentage of sessions visiting a page below which it's considered underused (default: 0.2) - rapid_change_window: seconds within which multiple changes indicate confusion (default: 10) - rapid_change_count: number of changes within window to flag as confusion (default: 5) |
Value
A list containing bid_stage objects for each identified issue in the "Notice" stage. Each element is named by issue type (e.g., "unused_input_region", "delayed_interaction", etc.)
Examples
## Not run:
# Analyze SQLite telemetry database
issues <- bid_ingest_telemetry("telemetry.sqlite")
# Analyze JSON log with custom thresholds
issues <- bid_ingest_telemetry(
"telemetry.log",
format = "json",
thresholds = list(
unused_input_threshold = 0.1,
delay_threshold_seconds = 60
)
)
# Use results in BID workflow
if (length(issues) > 0) {
# Take first issue and continue with BID process
interpret_result <- bid_interpret(
previous_stage = issues[[1]],
central_question = "How can we improve user engagement?"
)
}
## End(Not run)
Document User Interpretation Stage in BID Framework
Description
This function documents the interpretation of user needs, capturing the central question and the data storytelling narrative. It represents stage 2 in the BID framework.
Usage
bid_interpret(
previous_stage,
central_question = NULL,
data_story = NULL,
user_personas = NULL
)
Arguments
previous_stage |
A tibble or list output from an earlier BID stage function. |
central_question |
A character string representing the main question to be answered. If NULL, will be suggested based on previous stage information. |
data_story |
A list containing elements such as |
user_personas |
Optional list of user personas to consider in the design. |
Value
A tibble containing the documented information for the "Interpret" stage.
Examples
notice <- bid_notice(
problem = "Users struggle with complex data",
evidence = "Test results indicate delays"
)
# Basic usage
bid_interpret(
previous_stage = notice,
central_question = "What drives the decline in user engagement?",
data_story = list(
hook = "Declining trend in engagement",
context = "Previous high engagement levels",
tension = "Unexpected drop",
resolution = "Investigate new UI changes",
audience = "Marketing team",
metrics = c("Daily Active Users", "Session Duration"),
visual_approach = "Comparison charts showing before/after UI change"
)
)
# Let the function suggest content based on previous stage
bid_interpret(
previous_stage = notice
)
# With user personas
bid_interpret(
previous_stage = notice,
central_question = "How can we improve data discovery?",
data_story = list(
hook = "Users are missing key insights",
context = "Critical data is available but overlooked",
tension = "Time-sensitive decisions are delayed",
resolution = "Highlight key metrics more effectively"
),
user_personas = list(
list(
name = "Sara, Data Analyst",
goals = "Needs to quickly find patterns in data",
pain_points = "Gets overwhelmed by too many visualizations",
technical_level = "Advanced"
),
list(
name = "Marcus, Executive",
goals = "Wants high-level insights at a glance",
pain_points = "Limited time to analyze detailed reports",
technical_level = "Basic"
)
)
)
Document User Notice Stage in BID Framework
Description
This function documents the initial observation and problem identification stage. It represents stage 1 in the BID framework and now returns a structured bid_stage object with enhanced metadata and external mapping support.
Usage
bid_notice(problem, theory = NULL, evidence = NULL, ...)
Arguments
problem |
A character string describing the observed user problem. |
theory |
A character string describing the behavioral theory that might explain the problem. If NULL, will be auto-suggested using external theory mappings. |
evidence |
A character string describing evidence supporting the problem. |
... |
Additional parameters. Deprecated parameters like 'target_audience' will generate warnings if provided. |
Value
A bid_stage object containing the documented information for the "Notice" stage with enhanced metadata and validation.
Examples
# Basic usage with auto-suggested theory
notice_result <- bid_notice(
problem = "Users struggling with complex dropdowns and too many options",
evidence = "User testing shows 65% abandonment rate on filter selection"
)
# Print shows human-friendly summary
print(notice_result)
# Access underlying data
summary(notice_result)
# Check stage and metadata
get_stage(notice_result)
get_metadata(notice_result)
# with explicit theory
notice_explicit <- bid_notice(
problem = "Mobile interface is difficult to navigate",
theory = "Fitts's Law",
evidence = "Mobile users report frustration with small touch targets"
)
Generate BID Framework Report
Description
Creates a comprehensive report from a completed BID framework process. This report summarizes all stages and provides recommendations for implementation.
Usage
bid_report(
validate_stage,
format = c("text", "html", "markdown"),
include_diagrams = TRUE
)
Arguments
validate_stage |
A tibble output from |
format |
Output format: "text", "html", or "markdown" |
include_diagrams |
Logical, whether to include ASCII diagrams in the report (default: TRUE) |
Value
A formatted report summarizing the entire BID process
Examples
if (interactive()) {
# After completing all 5 stages
validation_result <- bid_validate(...)
# Generate a text report
bid_report(validation_result)
# Generate an HTML report
bid_report(validation_result, format = "html")
# Generate a markdown report without diagrams
bid_report(
validation_result,
format = "markdown",
include_diagrams = FALSE
)
}
Constructor for BID result collection objects
Description
Constructor for BID result collection objects
Usage
bid_result(stages)
Arguments
stages |
List of bid_stage objects |
Value
Object of class 'bid_result'
Constructor for BID stage objects
Description
Constructor for BID stage objects
Usage
bid_stage(stage, data, metadata = list())
Arguments
stage |
Character string indicating the stage name |
data |
Tibble containing the stage data |
metadata |
List containing additional metadata |
Value
Object of class 'bid_stage'
Document Dashboard Structure Stage in BID Framework
Description
This function documents the structure of the dashboard with automatic layout selection and generates ranked, concept-grouped actionable UI/UX suggestions. Layout is intelligently chosen based on content analysis of previous stages using deterministic heuristics. Returns structured recommendations with specific component pointers and implementation rationales.
Usage
bid_structure(previous_stage, concepts = NULL, ...)
Arguments
previous_stage |
A tibble or list output from an earlier BID stage function. |
concepts |
A character vector of additional BID concepts to include. Concepts can be provided in natural language (e.g., "Principle of Proximity") or with underscores (e.g., "principle_of_proximity"). The function uses fuzzy matching to identify the concepts. If NULL, will detect relevant concepts from previous stages automatically. |
... |
Additional parameters. If |
Details
Layout Auto-Selection: Uses deterministic heuristics to analyze content from previous stages and select the most appropriate layout:
-
breathable: For information overload/confusion patterns
-
dual_process: For overview vs detail needs
-
grid: For grouping/comparison requirements
-
card: For modular/chunked content
-
tabs: For categorical organization (unless telemetry shows issues)
Suggestion Engine: Generates ranked, actionable recommendations grouped by UX concepts. Each suggestion includes specific Shiny/bslib components, implementation details, and rationale. Suggestions are scored based on relevance, layout appropriateness, and contextual factors.
Value
A bid_stage object containing:
stage |
"Structure" |
layout |
Auto-selected layout type |
suggestions |
List of concept groups with ranked suggestions |
concepts |
Comma-separated string of all concepts used |
Examples
interpret <- bid_notice(
problem = "Users struggle with information overload",
evidence = "Survey results indicate delays"
) |>
bid_interpret(
central_question = "How can we simplify data presentation?",
data_story = list(
hook = "Data is too complex",
context = "Overloaded with charts",
tension = "Confusing layout",
resolution = "Introduce clear grouping"
)
)
# Auto-selected layout with concept-grouped suggestions
structure_result <- bid_structure(previous_stage = interpret)
print(structure_result$layout) # Auto-selected layout
print(structure_result$suggestions) # Ranked suggestions by concept
Suggest UI Components Based on BID Framework Analysis
Description
This function analyzes the results from BID framework stages and suggests appropriate UI components from popular R packages like shiny, bslib, DT, etc. The suggestions are based on the design principles and user needs identified in the BID process.
Usage
bid_suggest_components(bid_stage, package = NULL)
Arguments
bid_stage |
A tibble output from any BID framework stage function |
package |
Optional character string specifying which package to focus suggestions on. Options include "shiny", "bslib", "DT", "plotly", "reactable", "htmlwidgets". If NULL, suggestions from all packages are provided. |
Value
A tibble containing component suggestions with relevance scores
Examples
if (interactive()) {
# After completing BID stages
notice_result <- bid_notice(
problem = "Users struggle with complex data",
theory = "Cognitive Load Theory"
)
# Get all component suggestions
bid_suggest_components(notice_result)
# Get only bslib suggestions
bid_suggest_components(notice_result, package = "bslib")
# Get shiny-specific suggestions
bid_suggest_components(notice_result, package = "shiny")
}
Document User Validation Stage in BID Framework
Description
This function documents the validation stage, where the user tests and refines the dashboard. It represents stage 5 in the BID framework.
Usage
bid_validate(
previous_stage,
summary_panel = NULL,
collaboration = NULL,
next_steps = NULL,
include_exp_design = TRUE,
include_telemetry = TRUE,
include_empower_tools = TRUE
)
Arguments
previous_stage |
A tibble or list output from an earlier BID stage function. |
summary_panel |
A character string describing the final summary panel or key insight presentation. |
collaboration |
A character string describing how the dashboard enables collaboration and sharing. |
next_steps |
A character vector or string describing recommended next steps for implementation and iteration. |
include_exp_design |
Logical indicating whether to include experiment design suggestions. Default is TRUE. |
include_telemetry |
Logical indicating whether to include telemetry tracking and monitoring suggestions. Default is TRUE. |
include_empower_tools |
Logical indicating whether to include context-aware empowerment tool suggestions. Default is TRUE. |
Value
A tibble containing the documented information for the "Validate" stage.
Examples
structure_input <- bid_notice(
problem = "Issue with dropdown menus",
evidence = "User testing indicated delays"
) |>
bid_interpret(
central_question = "How can we improve selection efficiency?",
data_story = list(
hook = "Too many options",
context = "Excessive choices",
tension = "User frustration",
resolution = "Simplify menu"
)
)
structure_result <- bid_structure(
previous_stage = structure_input,
concepts = c("Principle of Proximity", "Default Effect")
)
anticipate <- bid_anticipate(
previous_stage = structure_result,
bias_mitigations = list(
anchoring = "Provide reference points",
framing = "Use gain-framed messaging"
)
)
bid_validate(
previous_stage = anticipate,
summary_panel = "Clear summary of key insights with action items",
collaboration = "Team annotation and sharing features",
next_steps = c(
"Conduct user testing with target audience",
"Implement accessibility improvements",
"Add mobile responsiveness"
)
)
Build suggestions for a specific concept
Description
Build suggestions for a specific concept
Usage
build_concept_group(concept, chosen_layout, previous_stage)
Arguments
concept |
Name of the concept to generate suggestions for |
chosen_layout |
Selected layout type |
previous_stage |
Previous stage data |
Value
List with concept name and suggestions
Build suggestion groups organized by concept
Description
Build suggestion groups organized by concept
Usage
build_groups_with_suggestions(concepts_final, chosen_layout, previous_stage)
Arguments
concepts_final |
Final list of concepts to generate suggestions for |
chosen_layout |
Selected layout type |
previous_stage |
Previous stage data for context |
Value
List of concept groups with suggestions
Create notice stage for confusion patterns
Description
Create notice stage for confusion patterns
Usage
create_confusion_notice(confusion_info, total_sessions)
Arguments
confusion_info |
List with confusion pattern information |
total_sessions |
Total number of sessions |
Value
bid_stage object
Create notice stage for delayed interactions
Description
Create notice stage for delayed interactions
Usage
create_delay_notice(delay_info, total_sessions, threshold)
Arguments
delay_info |
List with delay statistics |
total_sessions |
Total number of sessions |
threshold |
Threshold used for analysis |
Value
bid_stage object
Create notice stage for error patterns
Description
Create notice stage for error patterns
Usage
create_error_notice(error_info, total_sessions)
Arguments
error_info |
List with error pattern information |
total_sessions |
Total number of sessions |
Value
bid_stage object
Create notice stage for navigation issues
Description
Create notice stage for navigation issues
Usage
create_navigation_notice(nav_info, total_sessions)
Arguments
nav_info |
List with navigation pattern information |
total_sessions |
Total number of sessions |
Value
bid_stage object
Create notice stage for unused input
Description
Create notice stage for unused input
Usage
create_unused_input_notice(input_info, total_sessions)
Arguments
input_info |
List with input usage information |
total_sessions |
Total number of sessions |
Value
bid_stage object
Auto-detect telemetry format from file extension
Description
Auto-detect telemetry format from file extension
Usage
detect_telemetry_format(path)
Arguments
path |
File path |
Value
Format string ("sqlite" or "json")
Extract specific stage from bid_result
Description
Extract specific stage from bid_result
Usage
extract_stage(workflow, stage)
Arguments
workflow |
A bid_result object |
stage |
Character string with stage name |
Value
A bid_stage object or NULL if not found
Extract theory concepts from Stage 1 (Notice)
Description
Extract theory concepts from Stage 1 (Notice)
Usage
extract_stage1_theory(previous_stage)
Arguments
previous_stage |
Previous stage data |
Value
Character vector of theory-based concepts
Find confusion patterns (rapid repeated changes)
Description
Find confusion patterns (rapid repeated changes)
Usage
find_confusion_patterns(events, window_seconds = 10, min_changes = 5)
Arguments
events |
Telemetry events data frame |
window_seconds |
Time window in seconds |
min_changes |
Minimum changes to flag as confusion |
Value
List of confusion patterns
Find sessions with delayed first interaction
Description
Find sessions with delayed first interaction
Usage
find_delayed_sessions(events, threshold_seconds = 30)
Arguments
events |
Telemetry events data frame |
threshold_seconds |
Delay threshold in seconds |
Value
List with delay statistics
Find error patterns in telemetry
Description
Find error patterns in telemetry
Usage
find_error_patterns(events, threshold_rate = 0.1)
Arguments
events |
Telemetry events data frame |
threshold_rate |
Error rate threshold |
Value
List of error patterns
Find navigation drop-offs or underused pages
Description
Find navigation drop-offs or underused pages
Usage
find_navigation_dropoffs(events, threshold = 0.2)
Arguments
events |
Telemetry events data frame |
threshold |
Minimum visit rate threshold |
Value
List of navigation issues
Find unused or under-used inputs
Description
Find unused or under-used inputs
Usage
find_unused_inputs(events, threshold = 0.05)
Arguments
events |
Telemetry events data frame |
threshold |
Percentage threshold for considering input unused |
Value
List of unused input information
Format field label based on output format
Description
Format field label based on output format
Usage
format_label(label, format, type = "field")
Arguments
label |
Base label text |
format |
Output format ("markdown" or "text") |
type |
Label type ("header", "field", or "section") |
Value
Formatted label string
Get accessibility recommendations for a given context
Description
Get accessibility recommendations for a given context
Usage
get_accessibility_recommendations(context = "", guidelines = NULL)
Arguments
context |
Character string describing the interface context |
guidelines |
Optional custom accessibility guidelines |
Value
Character vector of relevant accessibility recommendations
Generate Cognitive Load Theory suggestions
Description
Generate Cognitive Load Theory suggestions
Usage
get_cognitive_load_suggestions(chosen_layout, previous_stage)
Get bias mitigation strategies for concepts
Description
Get bias mitigation strategies for concepts
Usage
get_concept_bias_mappings(concepts, mappings = NULL)
Arguments
concepts |
Character vector of concept names |
mappings |
Optional custom concept-bias mappings |
Value
Data frame with relevant bias mappings
Internal function to get concepts data from external files
Description
Internal function to get concepts data from external files
Usage
get_concepts_data()
Value
A tibble with all BID framework concepts
Get default concepts data (fallback when external file unavailable)
Description
Get default concepts data (fallback when external file unavailable)
Usage
get_default_concepts_data()
Value
A tibble with default BID framework concepts
Get default layout mappings (fallback)
Description
Get default layout mappings (fallback)
Usage
get_default_layout_mappings()
Value
Data frame with default layout mappings
Get default theory mappings (fallback)
Description
Get default theory mappings (fallback)
Usage
get_default_theory_mappings()
Value
Data frame with default theory mappings
Generate Dual-Processing Theory suggestions
Description
Generate Dual-Processing Theory suggestions
Usage
get_dual_processing_suggestions(chosen_layout, previous_stage)
Generate generic suggestions for unrecognized concepts
Description
Generate generic suggestions for unrecognized concepts
Usage
get_generic_suggestions(concept, chosen_layout, previous_stage)
Generate Information Scent suggestions
Description
Generate Information Scent suggestions
Usage
get_information_scent_suggestions(chosen_layout, previous_stage)
Get concepts recommended for a layout
Description
Get concepts recommended for a layout
Usage
get_layout_concepts(layout, mappings = NULL)
Arguments
layout |
Character string indicating layout type |
mappings |
Optional custom layout mappings |
Value
Character vector of recommended concepts
Get metadata from bid_stage object
Description
Get metadata from bid_stage object
Usage
get_metadata(x)
Arguments
x |
A bid_stage object |
Value
List with metadata
Generate User Onboarding suggestions
Description
Generate User Onboarding suggestions
Usage
get_onboarding_suggestions(chosen_layout, previous_stage)
Generate Progressive Disclosure suggestions
Description
Generate Progressive Disclosure suggestions
Usage
get_progressive_disclosure_suggestions(chosen_layout, previous_stage)
Generate Principle of Proximity suggestions
Description
Generate Principle of Proximity suggestions
Usage
get_proximity_suggestions(chosen_layout, previous_stage)
Get stage name from bid_stage object
Description
Get stage name from bid_stage object
Usage
get_stage(x)
Arguments
x |
A bid_stage object |
Value
Character string with stage name
Generate Visual Hierarchy suggestions
Description
Generate Visual Hierarchy suggestions
Usage
get_visual_hierarchy_suggestions(chosen_layout, previous_stage)
Infer concepts from Stage 2 (Interpret) story elements
Description
Infer concepts from Stage 2 (Interpret) story elements
Usage
infer_concepts_from_story(previous_stage)
Arguments
previous_stage |
Previous stage data |
Value
Character vector of story-inferred concepts
Check if object is a bid_stage
Description
Check if object is a bid_stage
Usage
is_bid_stage(x)
Arguments
x |
Object to test |
Value
Logical indicating if object is bid_stage
Check if workflow is complete (has all 5 stages)
Description
Check if workflow is complete (has all 5 stages)
Usage
is_complete(x)
Arguments
x |
A bid_result object |
Value
Logical indicating if workflow is complete
Generate layout selection rationale
Description
Provides a concise explanation for why a particular layout was chosen based on the content analysis of the previous stage.
Usage
layout_rationale(previous_stage, chosen)
Arguments
previous_stage |
A tibble or list output from an earlier BID stage |
chosen |
Character string with the chosen layout type |
Value
Character string with explanation for the layout choice
Load accessibility guidelines
Description
Load accessibility guidelines
Usage
load_accessibility_guidelines(custom_guidelines = NULL)
Arguments
custom_guidelines |
Optional custom guidelines data frame |
Value
Data frame with accessibility guidelines
Load concept-bias mappings
Description
Load concept-bias mappings
Usage
load_concept_bias_mappings(custom_mappings = NULL)
Arguments
custom_mappings |
Optional custom mappings data frame |
Value
Data frame with concept-bias mappings
Load layout-concept mappings
Description
Load layout-concept mappings
Usage
load_layout_mappings(custom_mappings = NULL)
Arguments
custom_mappings |
Optional custom mappings data frame |
Value
Data frame with layout-concept mappings
Load theory mappings from external file or use defaults
Description
Load theory mappings from external file or use defaults
Usage
load_theory_mappings(custom_mappings = NULL)
Arguments
custom_mappings |
Optional custom mappings data frame |
Value
Data frame with theory mappings
Create a BID result collection object (internal constructor)
Description
Create a BID result collection object (internal constructor)
Usage
new_bid_result(stages)
Arguments
stages |
List of bid_stage objects |
Value
Object of class 'bid_result'
Create a BID stage result object (internal constructor)
Description
Create a BID stage result object (internal constructor)
Usage
new_bid_stage(stage, data, metadata = list())
Arguments
stage |
Character string indicating the stage name |
data |
Tibble containing the stage data |
metadata |
List containing additional metadata |
Value
Object of class 'bid_stage'
Normalize telemetry column names
Description
Normalize telemetry column names
Usage
normalize_telemetry_columns(events)
Arguments
events |
Raw events data frame |
Value
Normalized data frame
Print method for BID result objects
Description
Print method for BID result objects
Usage
## S3 method for class 'bid_result'
print(x, ...)
Arguments
x |
A bid_result object |
... |
Additional arguments |
Value
Returns the input bid_result
object invisibly (class:
c("bid_result", "list")
). The method is called for its side
effects: printing a workflow overview to the console showing
completion status, stage progression, and key information from each
completed BID stage. The invisible return supports method chaining
while emphasizing the console summary output.
Print method for BID stage objects
Description
Print method for BID stage objects
Usage
## S3 method for class 'bid_stage'
print(x, ...)
Arguments
x |
A bid_stage object |
... |
Additional arguments |
Value
Returns the input bid_stage
object invisibly (class:
c("bid_stage", "tbl_df", "tbl", "data.frame")
). The method is
called for its side effects: printing a formatted summary of the BID
stage to the console, including stage progress, key stage-specific
information, and usage suggestions. The invisible return allows for
method chaining while maintaining the primary purpose of console
output.
Rank and sort suggestions within each group
Description
Rank and sort suggestions within each group
Usage
rank_and_sort_suggestions(groups, previous_stage, chosen_layout)
Arguments
groups |
List of concept groups with suggestions |
previous_stage |
Previous stage data for scoring adjustments |
chosen_layout |
Selected layout type |
Value
List of groups with ranked suggestions
Read telemetry data from file
Description
Read telemetry data from file
Usage
read_telemetry_data(path, format)
Arguments
path |
File path |
format |
Format ("sqlite" or "json") |
Value
Data frame of events
Read telemetry from JSON log file
Description
Read telemetry from JSON log file
Usage
read_telemetry_json(path)
Arguments
path |
JSON log file path |
Value
Data frame of events
Read telemetry from SQLite database
Description
Read telemetry from SQLite database
Usage
read_telemetry_sqlite(path)
Arguments
path |
SQLite database path |
Value
Data frame of events
Safely convert text to lowercase with null handling
Description
Helper function that safely converts text to lowercase while handling NULL, NA, and non-character values gracefully.
Usage
safe_lower(x)
Arguments
x |
Input value to convert to lowercase string |
Value
Character string in lowercase, or empty string if input is NULL/NA
Safe access to data_story elements from previous stage
Description
Safe access to data_story elements from previous stage
Usage
safe_stage_data_story_access(previous_stage, element)
Arguments
previous_stage |
Previous stage data |
element |
Name of data_story element to access |
Value
Character string or empty string if not found
Generate ranked, concept-grouped, actionable UI/UX suggestions
Description
Creates structured suggestions organized by UX concepts with specific component recommendations and rationales. Suggestions are ranked by relevance and grouped by concept for systematic implementation.
Usage
structure_suggestions(previous_stage, chosen_layout, concepts = NULL)
Arguments
previous_stage |
A tibble or list output from an earlier BID stage |
chosen_layout |
Character string with the selected layout type |
concepts |
Optional character vector of additional concepts to include |
Details
The function combines concepts from multiple sources:
Stage 1 theory (from Notice)
Stage 2 inferred concepts (from keywords in story)
Optional user-provided concepts
Each suggestion includes:
title: Brief actionable description
details: Specific implementation guidance
components: Shiny/bslib component recommendations
rationale: 1-2 sentence explanation
score: Relevance ranking (0-1)
Value
List of concept groups with ranked suggestions
Suggest layout based on previous stage content using heuristics
Description
Automatically suggests an appropriate layout type based on content analysis of previous BID stages. Uses deterministic heuristics to match keywords in problem descriptions, evidence, data story, and other contextual information to layout types that best address the identified issues.
Usage
suggest_layout_from_previous(previous_stage)
Arguments
previous_stage |
A tibble or list output from an earlier BID stage function containing stage data with potential fields like problem, evidence, central_question, data_story, etc. |
Details
The heuristics follow a priority order:
-
breathable - if content suggests information overload, confusion, or cognitive load issues
-
dual_process - if content mentions overview vs detail, quick vs deep, or two-mode interactions
-
grid - if content focuses on grouping, clustering, visual hierarchy, or comparing related metrics
-
card - if content mentions cards, chunks, tiles, modular blocks, or per-item summaries
-
tabs - if content suggests sections, categories, progressive disclosure, but avoids tabs if telemetry shows tab drop-off
-
breathable - fallback for any unmatched cases
Value
Character string indicating the suggested layout type ("breathable", "dual_process", "grid", "card", "tabs", or fallback)
Suggest theory based on problem and evidence using mappings
Description
Suggest theory based on problem and evidence using mappings
Usage
suggest_theory_from_mappings(problem, evidence = NULL, mappings = NULL)
Arguments
problem |
Character string describing the problem |
evidence |
Optional character string with supporting evidence |
mappings |
Optional custom theory mappings |
Value
Character string with suggested theory
Summary method for BID result objects
Description
Summary method for BID result objects
Usage
## S3 method for class 'bid_result'
summary(object, ...)
Arguments
object |
A bid_result object |
... |
Additional arguments |
Value
Returns the input bid_result
object invisibly (class:
c("bid_result", "list")
). The method is called for its side
effects: printing a detailed workflow analysis to the console
including completion statistics, duration metrics, and comprehensive
stage-by-stage breakdowns with key data from each BID framework
stage. The invisible return facilitates method chaining while
focusing on comprehensive console reporting.
Summary method for BID stage objects
Description
Summary method for BID stage objects
Usage
## S3 method for class 'bid_stage'
summary(object, ...)
Arguments
object |
A bid_stage object |
... |
Additional arguments |
Value
Returns the input bid_stage
object invisibly (class:
c("bid_stage", "tbl_df", "tbl", "data.frame")
). The method is
called for its side effects: printing a comprehensive summary to the
console including stage metadata, all non-empty data columns, and
timestamp information. The invisible return enables method chaining
while prioritizing the detailed console output display.
Validate BID result object
Description
Validate BID result object
Usage
validate_bid_result(x)
Arguments
x |
Object to validate |
Value
TRUE if valid, throws error otherwise
Validate BID stage object
Description
Validate BID stage object
Usage
validate_bid_stage(x)
Arguments
x |
Object to validate |
Value
TRUE if valid, throws error otherwise