bidux 0.3.2: Leaner, Quieter, More Intuitive BID Workflows

The {bidux} 0.3.2 release streamlines BID workflows with intuitive flat APIs, built-in telemetry presets, and a quieter, leaner experience, helping you focus on insights rather than overhead.

I’m excited to announce that {bidux} 0.3.2 is now available on CRAN!

This update is a polishing release that focuses on API ergonomics and package optimization. We’ve flattened out old complexities (goodbye nested lists!), added knobs to fine-tune telemetry with ease, and even given you a “mute button” for verbose output. All these changes maintain 100% backward compatibility, so you get smoother workflows without breaking your existing code.

Flattening the Story: Intuitive Data Stories

Crafting a BID data story in 0.3.2 is more intuitive. The new_data_story() function now uses a flat API with four straightforward arguments (hook, context, tension, resolution), instead of nesting parts of the story inside.

In other words, you can directly specify the key elements of your story without the cognitive overhead of wrapping them in variables and relationships lists. This covers about 80% of use cases with a cleaner syntax:

# Before (nested format, now deprecated)
story_old <- new_data_story(
  context = "Dashboard usage dropped",
  variables = list(hook = "User engagement declining"),
  relationships = list(resolution = "Analyze telemetry")
)

# After (flat format, 0.3.2+)
story <- new_data_story(
  hook = "User engagement declining",
  context = "Dashboard usage dropped 30%",
  tension = "Unsure if UX or user needs are causing the drop",
  resolution = "Analyze telemetry for friction points"
)

The new flat syntax is not only easier to read, it’s also future-proof. The old nested format still works for now, but will trigger a deprecation warning and is slated for removal in 0.4.0.

I recommend updating your code to the flat style soon. Your future self will thank you.

On the bright side, all other BID functions seamlessly accept the new bid_data_story objects, and printing a story now neatly lists out the hook, context, tension, and resolution for a quick overview.

Telemetry Tuning Made Easy

If you’ve been ingesting telemetry data to inform your designs, {bidux} 0.3.2 introduces a welcome convenience: telemetry sensitivity presets.

The new bid_telemetry_presets() function gives you pre-configured threshold sets ("strict", "moderate", "relaxed") for flagging UX issues. This means you no longer need to hand-tweak what counts as an “unused input” or a “delay” in user interactions. Just pick a preset that fits your scenario:

• Strict: Use for brand-new or mission-critical dashboards to catch even minor friction (e.g. flags inputs used by < 2% of sessions and delays over ~20 seconds).
• Moderate: The default balance for most applications, offering a good signal-to-noise ratio (e.g. flags inputs under ~5% usage, delays over ~30 seconds).
• Relaxed: For mature, stable dashboards where only major issues merit attention (e.g. flags inputs under ~10% usage, delays over ~60 seconds).

These presets let you adapt to your app’s context with one line of code. For example, a brand new internal app might start with bid_telemetry_presets("strict") to catch early pain points, whereas a long-running product dashboard might use "relaxed" to focus only on high-impact issues. Under the hood, each preset just supplies a list of threshold values to the thresholds argument of bid_telemetry(), so you retain full control if you ever need a custom tweak.

Enjoy the Silence: Quiet Mode

Do you ever feel inundated by informational messages when running BID analyses or pipelines? In 0.3.2, quiet mode is here to help.

Every BID stage function (from bid_interpret() through bid_validate()) gains a new quiet parameter. Set quiet = TRUE and those friendly yet noisy console messages will be suppressed. This can make a huge difference when running complex pipelines or rendering Shiny apps where clean logs are gold.

For example, you can wrap an entire sequence of stages in silence:

library(bidux)

# Globally turn on quiet mode for the whole workflow
bid_set_quiet(TRUE)  # new helper to set quietness across all functions

result <- bid_interpret(..., quiet = TRUE) |>
  bid_notice(..., quiet = TRUE) |>
  bid_anticipate(..., quiet = TRUE) |>
  bid_structure(..., quiet = TRUE) |>
  bid_validate(..., quiet = TRUE)

Rather not sprinkle quiet = TRUE everywhere? You can also use bid_with_quiet() to temporarily suppress messages within a block of code, or configure the default with bid_set_quiet() and bid_get_quiet() at a global level.

Now you’re in charge of the verbosity. Run noisy when debugging, then go quiet when integrating into a polished Shiny app or R Markdown report.

NoteShiny Developers: Leaner, Quieter Apps

If you use {bidux} in Shiny, this release makes life easier. Removing heavy dependencies like {purrr} and {stringr} has slimmed down the package, which means lighter-weight deployments. And with the new quiet mode, you can keep your app logs clean: No more spamming the console with messages during user sessions. Focus on your users, not the chatter!

New S3 Helpers and Print Enhancements

To further modernize the API, 0.3.2 introduces new S3 constructors for key BID components. You can now create user personas and bias mitigation sets with dedicated functions: new_user_personas() and new_bias_mitigations(). These expect a data frame with the appropriate columns (e.g. name, goals, pain_points, etc. for personas) and return structured S3 objects.

The benefit? Type-safe, validated objects that play nicely with BID workflows. If you’ve been using raw lists for personas or biases, these helpers provide a clear migration path to a more robust format (and they’ll warn you if required fields are missing or misformatted).

Printing of BID objects also got a polish. For example, printing a bid_data_story now shows a tidy summary with each element on its own line, rather than a raw list dump. Likewise, bid_user_personas and bid_bias_mitigations objects print with a concise header (e.g. “bidux user personas (3 personas):”) followed by a tibble of the contents. This makes inspecting these objects in the console much more reader-friendly. Little quality-of-life improvements like this help you quickly verify that your inputs are set up correctly.

Under the Hood: Leaner and Cleaner

This release also trims some fat and cleans up behind the scenes to make the package more efficient:

• Reduced dependencies: We removed unused packages {purrr} and {stringr} from our imports, opting for base R solutions. This reduces installation size and the risk of version conflicts, so your projects load a bit faster and ship with fewer baggage.
• Better error messages: We’ve adopted the glue and cli packages for error handling. Now errors come with clearer context and suggestions (using cli::cli_abort() with our new standard_error_msg() helper). When something goes wrong, the feedback will be more informative and actionable than the old generic stop() messages.
• Text normalization: Various text-processing utilities in bidux have been refined to handle whitespace and special characters more gracefully. This means more reliable matching when generating suggestions or interpreting inputs, especially in edge cases.
• Code refactoring: We reorganized internal code into domain-specific modules (messaging, validation, stages, safe access). While invisible to you as a user, this modular structure makes bidux easier to maintain and test, which ultimately leads to more robust features.
• Telemetry constants: All those “magic numbers” for telemetry thresholds are now named constants at the top of the telemetry module. This cleanup makes the logic more transparent and sets the stage for easier tuning (for us and adventurous contributors).

Crucially, none of these changes break existing functionality. They either improve performance, clarity, or developer experience without altering how you call the functions. It’s all gain, no pain.

Documentation and Resources

To help you get the most out of these updates, we’ve expanded and refreshed the documentation:

• New “API Modernization” vignette: A comprehensive guide for migrating from legacy list-based usage to the new S3 classes and flat APIs. This is a great starting point if you’re upgrading from an older version and want to adopt best practices (with plenty of examples for data_story, user_personas, and bias_mitigations).
• Simplified “Advanced Workflows” vignette: We’ve updated our advanced examples to showcase these new features in action. This includes how to use telemetry presets in different contexts and how to utilize quiet mode in complex pipelines. If you’re pushing bidux to its limits (e.g. analyzing dozens of dashboards in batch), check out this vignette for patterns and tips.
• Updated “Getting Started” vignette: New users will find the getting started guide now uses the flat new_data_story() and data frame-based personas from the outset. We’ve also ensured the examples reflect the current recommended usage (no outdated list formats) and highlighted the corrected BID stage ordering that was fixed in 0.3.1.
• Function reference examples: Key functions like bid_interpret() now include examples demonstrating both the modern usage and how to handle legacy inputs. Our goal is to guide users toward the new approaches while still acknowledging the old way for those in transition.

As always, the reference documentation is available and has been updated with all new parameters (like quiet) and functions. And behind the scenes, we bolstered test coverage for all these changes, so you can upgrade with confidence.

Migration and Backward Compatibility

Upgrading to 0.3.2 should be seamless. All your code from 0.3.1 (and even 0.3.0) will continue to run, thanks to careful backward compatibility. If you do use any now-deprecated patterns, bidux will politely prod you with warnings and guidance:

• Nested data_story format: If you pass variables or relationships into new_data_story(), you’ll get a deprecation warning. The function will still return a valid story object (so your pipeline won’t break), but consider this your nudge to switch to the flat syntax before 0.4.0.
• Legacy telemetry ingestion: The old bid_ingest_telemetry() function remains available for those who haven’t migrated to the new bid_telemetry() workflow. It continues to return the hybrid list-like object as before. However, we signaled in 0.3.1 that a shift toward bid_telemetry() is the future, and that remains true. Plan to update to the tidy tibble approach when convenient.
• List-based personas and mitigations: You can still supply user personas as plain lists of lists, and bias mitigations as raw lists. Internally, bidux will convert or migrate these to the new S3 objects on the fly. You might see messages suggesting to use new_user_personas() or new_bias_mitigations() going forward, but your results will be the same. This gentle transition means you can adopt the new helpers at your own pace.

In short, no breaking changes in 0.3.2. We’ve laid the groundwork for 0.4.0 deprecations but provided a smooth on-ramp.

If you run into any issues while upgrading, please check the API Modernization vignette or reach out on the GitHub repo.

Install the Latest Release

You can install {bidux} 0.3.2 from CRAN today:

install.packages("bidux")

As a minor release after 0.3.1, this version focuses on refining your experience: Making the API more intuitive, reducing friction from extraneous output, and keeping the package lean and efficient.

The goal is to let you spend less time wrangling the tool and more time applying Behavioral Insight Design to build better Shiny apps and dashboards. We hope these improvements make your BID workflows smoother and more enjoyable.

Happy designing! 🚀