---
title: "Getting Started with bidux"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with bidux}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

## Introduction

The `{bidux}` package helps Shiny developers create more effective dashboards using the **Behavioral Insight Design (BID) Framework**. If you've ever wondered why users struggle with your carefully crafted dashboards, or why your beautifully visualized data doesn't drive the decisions you expected, this package is for you.

**The core insight**: Technical excellence ≠ User success. Even the most sophisticated analysis can fail if users can't quickly understand and act on it.

The BID framework bridges this gap by integrating behavioral science, UX best practices, and data storytelling techniques into a systematic 5-stage process. Think of it as applying the same rigor you use for data validation to user experience design.

```{r setup}
library(bidux)
library(dplyr)
```

## The BID Framework: A Data-Driven Approach to UX

The BID framework consists of 5 sequential stages that mirror how you might approach a data analysis project:

1. **Interpret** the User's Need - Like defining your research question and understanding your data
2. **Notice** the Problem - Like identifying data quality issues or analytical bottlenecks
3. **Anticipate** User Behavior - Like checking for statistical biases that could skew results
4. **Structure** the Dashboard - Like choosing the right visualization or model architecture
5. **Validate** & Empower the User - Like testing your model and ensuring stakeholders can act on results

**Key insight for data professionals**: Just as you wouldn't skip exploratory data analysis before modeling, don't skip understanding user cognition before building interfaces.

Each stage builds on insights from previous stages, creating a systematic approach to dashboard design that's both evidence-based and user-centered.

## Exploring the Concept Dictionary

The BID framework is built on established science and design principles. To explore these concepts, use `bid_concepts()` to list all available concepts, or search for specific terms:

```{r concepts}
# List all concepts
all_concepts <- bid_concepts()
head(select(all_concepts, concept, category, description), 3)

# Search for specific concepts
bid_concepts("cognitive") |>
  select(concept, description, implementation_tips)
```

For detailed information about a specific concept, use `bid_concept()`:

```{r concept_detail}
# Get information about a specific concept
bid_concept("Processing Fluency") |>
  select(concept, description, implementation_tips)
```

The `bid_concept()` function supports case-insensitive and partial matching:

```{r concept_matching}
# Case-insensitive matching
bid_concept("hick's law") |>
  select(concept, description)

# Partial matching
bid_concept("proximity") |>
  select(concept, description)
```

You can also explore concepts that are new to the BID framework:

```{r new_concepts}
# Explore new concepts from user-centric design
bid_concepts("visual hierarchy|breathable|gherkin") |>
  select(concept, description)
```

## Documenting a Dashboard Project with BID

Let's walk through a complete example of using the BID framework to document and improve a dashboard project.

### Stage 1: Interpret the User's Need

Start by clarifying the central question your dashboard needs to answer and structure the data story:

```{r interpret}
# Document the user's need
interpret_result <- bid_interpret(
  central_question = "How are our marketing campaigns performing across different channels?",
  data_story = list(
    hook = "Recent campaign performance varies significantly across channels",
    context = "We've invested in 6 different marketing channels over the past quarter",
    tension = "ROI metrics show inconsistent results, with some channels underperforming",
    resolution = "Identify top-performing channels and key performance drivers",
    audience = "Marketing team and executives",
    metrics = c("Channel ROI", "Conversion Rate", "Cost per Acquisition"),
    visual_approach = "Comparative analysis with historical benchmarks"
  ),
  user_personas = list(
    list(
      name = "Marketing Manager",
      goals = "Optimize marketing spend across channels",
      pain_points = "Difficulty comparing performance across different metrics",
      technical_level = "Intermediate"
    ),
    list(
      name = "CMO",
      goals = "Strategic oversight of marketing effectiveness",
      pain_points = "Needs high-level insights without technical details",
      technical_level = "Basic"
    )
  )
)

interpret_result |>
  select(central_question, hook, tension, resolution)
```

The function evaluates our data story elements and provides suggestions for improvement (in the `suggestions` column). We've also added user personas to better target our design.

### Stage 2: Notice the Problem

Now identify the specific problems users are encountering with your dashboard or interface:

```{r notice}
# Document the problem
notice_result <- bid_notice(
  previous_stage = interpret_result,
  problem = "Users are overwhelmed by too many filter options and struggle to find relevant insights",
  evidence = "User testing shows 65% of first-time users fail to complete their intended task within 2 minutes"
)

notice_result |>
  select(problem, theory, evidence)
```

Notice that the function automatically selected an appropriate theory based on our problem description. It also provides suggestions for addressing cognitive load which you can access from the `suggestions` column.

### Stage 3: Anticipate User Behavior

Next, identify potential cognitive biases that might affect how users interpret your dashboard:

```{r anticipate}
# Document bias mitigation strategies
anticipate_result <- bid_anticipate(
  previous_stage = notice_result,
  bias_mitigations = list(
    anchoring = "Include previous period performance as reference points",
    framing = "Provide toggle between ROI improvement vs. ROI gap views",
    confirmation_bias = "Highlight unexpected patterns that contradict common assumptions"
  )
)

anticipate_result |>
  select(bias_mitigations)
```

The function evaluates our bias mitigation strategies, providing implementation suggestions.

### Stage 4: Structure the Dashboard

Now determine the layout and key design principles to implement:

```{r structure}
# Document the dashboard structure
structure_result <- bid_structure(previous_stage = anticipate_result)

structure_result |>
  select(layout, concepts, suggestions)
```

The function automatically selects an appropriate layout based on the content from previous stages and provides ranked, actionable suggestions organized by UX concepts. The layout selection is transparent with clear rationale for why a particular layout was chosen.

### Stage 5: Validate & Empower the User

Finally, document how you'll ensure users leave with clear insights and the ability to collaborate:

```{r validate}
# Document validation approach
validate_result <- bid_validate(
  previous_stage = structure_result,
  summary_panel = "Executive summary highlighting top and bottom performers, key trends, and recommended actions for the next marketing cycle",
  collaboration = "Team annotation capability allowing marketing team members to add context and insights to specific data points",
  next_steps = c(
    "Review performance of bottom 2 channels",
    "Increase budget for top-performing channel",
    "Schedule team meeting to discuss optimization strategy",
    "Export findings for quarterly marketing review"
  )
)

validate_result |>
  select(summary_panel, collaboration, next_steps)
```

The validate function acknowledges our implementation of the Peak-End Rule through next steps and provides suggestions for refining our approach.

## Generating Implementation Suggestions

Once you've documented your dashboard with the BID framework, you can generate concrete suggestions for implementing the principles using common R packages:

```{r suggestions}
# Get {bslib} component suggestions
bid_suggest_components(structure_result, package = "bslib") |>
  select(component, description) |>
  head(2)

# Get {reactable} suggestions for showing data
bid_suggest_components(structure_result, package = "reactable") |>
  select(component, description) |>
  head(2)

# Get suggestions from all supported packages
all_suggestions <- bid_suggest_components(validate_result, package = "all")
table(all_suggestions$package)
```

## Creating a Complete BID Report

You can generate a complete report summarizing all stages of your BID process:

```{r report, eval=FALSE}
# Generate a text report (default)
report <- bid_report(validate_result)
cat(report)

# Generate an HTML report
html_report <- bid_report(validate_result, format = "html")

# Generate a markdown report
md_report <- bid_report(validate_result, format = "markdown")
```

## Using BID in Your Shiny Development Workflow

Here's how to integrate the BID framework into your development process:

1. **Planning Phase**
  - Use the BID framework to document your design decisions before writing code
  - Identify key user needs and potential friction points
  - Define user personas to guide your design choices
  - Consider accessibility requirements early

2. **Development Phase**
  - Reference your BID documentation to implement appropriate UI patterns
  - Use `bid_suggest_components()` to get package-specific implementation ideas
  - Implement bias mitigation strategies in your interface
  - Build in progressive disclosure for complex interfaces

3. **Testing Phase**
  - Validate that your implementation addresses the issues identified in Stage 1
  - Test with actual users representing your defined personas
  - Specifically test bias mitigation strategies and accessibility features
  - Gather feedback on the effectiveness of your validation approach

4. **Iteration Phase**
  - Update your BID documentation as you refine the dashboard
  - Use `bid_report()` to maintain comprehensive documentation
  - Focus improvements on areas with the greatest impact on user experience
  - Continue to apply BID principles as you add new features

## Conclusion

The `{bidux}` package makes it easier to apply behavioral science and UX best practices to your Shiny dashboards. By following the 5-stage BID framework, you can create applications that are more intuitive, engaging, and effective for your users.

Future versions of `{bidux}` will include:

- User stories workflow integration following the Gherkin method
- Enhanced design patterns library
- Accessibility framework integration with WCAG guidelines
- A UI component library implementing BID principles
- Testing and validation tools for dashboard evaluation

## Integrating Telemetry Data (New in 0.3.1)

If you have telemetry data from user interactions, `{bidux}` can help transform it into actionable BID insights:

```{r telemetry_workflow}
# Modern telemetry workflow (0.3.1+)
# Process telemetry data into organized issues
issues <- bid_telemetry("path/to/telemetry.sqlite")

# Triage and review issues
print(issues)  # Shows organized issue summary

# Convert high-priority issues to Notice stages
critical_issues <- issues |>
  filter(severity == "critical") |>
  slice_head(n = 3)

notices <- bid_notices(
  issues = critical_issues,
  previous_stage = interpret_result
)

# Extract telemetry flags for structure optimization
flags <- bid_flags(issues)

# Use flags to inform layout selection
structure_result <- bid_structure(
  previous_stage = anticipate_result,
  telemetry_flags = flags
)
```

The hybrid object returned by `bid_ingest_telemetry()` maintains backward compatibility while providing enhanced functionality:

```{r legacy_compatibility}
# Legacy approach still works
legacy_notices <- bid_ingest_telemetry("path/to/telemetry.sqlite")
length(legacy_notices)  # Behaves like list of Notice stages

# But now also provides enhanced features
as_tibble(legacy_notices)  # Tidy issues view
bid_flags(legacy_notices)  # Extract global flags
```

Visit [github.com/jrwinget/bidux](https://github.com/jrwinget/bidux) for updates and to contribute to the package development. We welcome feedback and suggestions to help make the BID framework even more effective for Shiny developers.

Remember that good dashboard design is an iterative process that benefits from continuous user feedback. The BID framework provides structure to this process while ensuring common principles are incorporated throughout your development workflow.