learn-R by fortune9/agent

Overview

This skill provides guidance on using the btw package to generate context for learning R packages and functions. The btw::btw() function creates plain-text descriptions of R objects (data frames, functions, package documentation) that can be used as prompts for AI agents.

Key use cases:

Learning how to use specific R functions or packages
Generating contextual prompts for AI assistants
Documenting computational environments for LLM interactions
Creating reproducible context for code generation tasks

Basic Usage

Describe Objects in Your Environment

# Describe all objects in your workspace
btw::btw()

Describe Specific Functions and Data

# Describe a function and a dataset
btw::btw(dplyr::mutate, mtcars)

# Describe multiple objects
btw::btw(dplyr::across, dplyr::starwars, tidyr::pivot_longer)

Include Vignettes and Documentation

# Include package vignettes
btw::btw(vignette("colwise", "dplyr"))

# Include help pages
btw::btw(help = "dplyr::across")

Interactive Workflow

# Copy context to clipboard for pasting into chat interface
btw::btw(dplyr::mutate, mtcars, clipboard = TRUE)
# Result is automatically copied to clipboard

btw Tool Functions

Use specialized btw_tool_*() functions for fine-grained control:

Package Help Topics

# Get help topics for a package
btw::btw_tool_docs_package_help_topics("dplyr")

Help Pages

# Get specific help page
btw::btw_tool_docs_help_page("dplyr::across")

Function Documentation

# Get function documentation
btw::btw_tool_docs_function("dplyr", "across")

Vignettes

# Get vignette content
btw::btw_tool_docs_vignette("dplyr", "colwise")

Common Patterns

Learning a New Package

# Get comprehensive context for learning a package
btw::btw(
  btw_tool_docs_package_help_topics("tidyr"),
  tidyr::pivot_longer,
  tidyr::pivot_wider,
  "Explain the key concepts of tidyr and when to use pivot operations"
)

Understanding Function Relationships

# Compare related functions
btw::btw(
  dplyr::summarise,
  dplyr::mutate,
  "What is the difference between summarise() and mutate()? When should I use each?"
)

Getting Examples

# Request examples with context
btw::btw(
  ggplot2::ggplot,
  ggplot2::aes,
  mtcars,
  "Show me 3 different ways to visualize the relationship between mpg and wt"
)

Debugging Help

# Get help with debugging
btw::btw(
  my_function,
  error_condition,
  "Why am I getting this error and how can I fix it?"
)

Advanced Usage

Custom Context Building

# Build complex context programmatically
context <- c(
  btw_tool_docs_help_page("dplyr::filter"),
  btw_tool_docs_help_page("dplyr::select"),
  "Create a workflow that combines filtering and selecting"
)

btw::btw(!!!context)

Multiple Packages

# Learn about package interactions
btw::btw(
  dplyr::filter,
  tidyr::drop_na,
  ggplot2::ggplot,
  "Show me a complete workflow from data cleaning to visualization"
)

Clipboard Control

# Disable clipboard copying
result <- btw::btw(mtcars, clipboard = FALSE)

# Access the text content
content <- as.character(result)

Best Practices

1. Be Specific About What You Want to Learn

# Good: Specific learning goal
btw::btw(
  dplyr::group_by,
  dplyr::summarise,
  "Show me how to calculate summary statistics by group"
)

# Less helpful: Too vague
btw::btw(dplyr, "Teach me dplyr")

2. Include Relevant Data

# Good: Include the actual data you're working with
btw::btw(my_data_frame, dplyr::filter, "How do I filter this data?")

# Less helpful: No context
btw::btw(dplyr::filter, "How do I filter?")

3. Combine Documentation with Examples

# Good: Documentation + data + specific question
btw::btw(
  help = "tidyr::pivot_longer",
  my_wide_data,
  "Convert my data from wide to long format"
)

4. Use Incremental Learning

# Start with basics
btw::btw(dplyr::select, "Explain the basics of select()")

# Then explore advanced features
btw::btw(
  dplyr::select,
  dplyr::starts_with,
  dplyr::ends_with,
  "Show me helper functions for selecting multiple columns"
)

Workflow Examples

Learning Data Transformation

library(btw)

# Get context for learning dplyr transformations
chat_prompt <- btw(
  vignette("base", "dplyr"),
  dplyr::mutate,
  dplyr::filter,
  dplyr::select,
  mtcars,
  "Create a step-by-step tutorial for data transformation with dplyr"
)

Learning Visualization

# Get context for learning ggplot2
chat_prompt <- btw(
  ggplot2::ggplot,
  ggplot2::geom_point,
  ggplot2::geom_smooth,
  ggplot2::facet_wrap,
  mtcars,
  "Teach me the grammar of graphics using ggplot2"
)

Learning Statistical Modeling

# Get context for learning modeling
chat_prompt <- btw(
  stats::lm,
  stats::glm,
  broom::tidy,
  broom::glance,
  mtcars,
  "Explain linear modeling in R and how to interpret results"
)

Troubleshooting

Objects Not Found

# Ensure packages are loaded
library(dplyr)
btw::btw(dplyr::across)

# Or use :: notation
btw::btw(dplyr::across)

Large Output

# Focus on specific functions rather than entire packages
btw::btw(dplyr::filter, dplyr::select)  # Good
btw::btw(dplyr)  # May be too much

Clipboard Issues

# Disable clipboard and capture output
result <- btw::btw(mtcars, clipboard = FALSE)
print(result)

Related Resources

btw package documentation: ?btw::btw
btw GitHub: https://posit-dev.github.io/btw/
ellmer package: For AI chat integration
R for Data Science: https://r4ds.hadley.nz/

Quick Reference

Task	Command
Describe workspace	`btw::btw()`
Describe function	`btw::btw(dplyr::mutate)`
Describe data	`btw::btw(mtcars)`
Include vignette	`btw::btw(vignette("name", "pkg"))`
Copy to clipboard	`btw::btw(..., clipboard = TRUE)`
Chat with context	`chat$chat(btw(...))`
Package help topics	`btw_tool_docs_package_help_topics("pkg")`
Help page	`btw_tool_docs_help_page("pkg::func")`

Tips for AI Agent Learning

Start with fundamentals: Begin with core functions before advanced features
Include your data: AI can provide more relevant help with actual data context
Ask for examples: Request multiple examples with varying complexity
Iterate: Use follow-up questions to deepen understanding
Save good prompts: Keep effective btw() calls for future learning sessions