1. API Key Setup

Add your API key to .Renviron file:

# Open .Renviron file
usethis::edit_r_environ()

# Add one of the following lines:
# ANTHROPIC_API_KEY=your_key_here
# OPENAI_API_KEY=your_key_here
# GOOGLE_API_KEY=your_key_here

# Save and restart R session

2. Basic Usage

library(jsmodule)

# Launch gadget with AI Assistant included
jsBasicGadget()

# Navigate to "AI Assistant" tab

library(shiny)
library(jsmodule)
library(survival)

ui <- fluidPage(
  titlePanel("AI Statistical Assistant"),
  aiAssistantUI("ai")
)

server <- function(input, output, session) {
  data <- reactive(colon)
  data.label <- reactive(jstable::mk.lev(colon))

  callModule(aiAssistant, "ai",
    data = data,
    data_label = data.label
  )
}

shinyApp(ui, server)

Code Generation

• Statistical analysis code (regression, survival analysis, descriptive statistics)
• Visualization code (ggplot2, jskm, forestplot)
• Table generation (jstable, DT)
• Follows jsmodule conventions and best practices

Multiple AI Providers

• Anthropic Claude (default): claude-3-7-sonnet, claude-3-5-sonnet, claude-3-opus
• OpenAI GPT: gpt-4o, gpt-4-turbo, gpt-3.5-turbo
• Google Gemini: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash

Export Options

• Word (.docx): Tables with formatted layout
• PowerPoint (.pptx): Plots as editable vector graphics
• Excel (.xlsx): Tables with data preservation
• R Script (.R): Complete reproducible code

Safety Features

• Sandboxed code execution (only allowed packages)
• Pre-execution code review and editing
• Error handling with AI-assisted fixes
• No file system or network access

Data Access

• The AI can only access data provided through the data parameter
• Data is referred to as out in generated code
• File upload data is automatically reactive

Allowed Packages

Generated code can only use these packages:

jstable, jskm, jsmodule, survival, ggplot2, ggpubr,
pROC, data.table, DT, gridExtra, GGally, forestploter,
MatchIt, timeROC

Variable Structure

The module automatically generates variable structure information: - Factor variables - Numeric variables - Custom structures (if provided via data_varStruct parameter)

API Key Resolution Order

1. Explicit api_key argument in callModule()
2. UI input (if show_api_config = TRUE)
3. Environment variables (.Renviron file)

API Configuration Modes

The show_api_config parameter controls how API keys are managed:

# Development mode - users can configure in UI
aiAssistantUI("ai", show_api_config = TRUE)  # Default

callModule(aiAssistant, "ai",
  data = data,
  data_label = data.label,
  show_api_config = TRUE
)

# Production mode - API key from .Renviron only
aiAssistantUI("ai", show_api_config = FALSE)

callModule(aiAssistant, "ai",
  data = data,
  data_label = data.label,
  show_api_config = FALSE
)

Custom Variable Structure

server <- function(input, output, session) {
  data <- reactive(lung)
  data.label <- reactive(jstable::mk.lev(lung))

  # Define custom variable roles
  var_struct <- reactive({
    list(
      variable = names(lung),
      Base = c("age", "sex", "ph.ecog"),
      Event = "status",
      Time = "time"
    )
  })

  callModule(aiAssistant, "ai",
    data = data,
    data_label = data.label,
    data_varStruct = var_struct
  )
}

Analysis Context

Provide background information to improve AI responses:

callModule(aiAssistant, "ai",
  data = data,
  data_label = data.label,
  analysis_context = reactive({
    "NCCTG lung cancer trial data.
     Primary outcome: time to death (status/time).
     Focus on performance status (ph.ecog) as predictor."
  })
)

Production Deployment

Hide API configuration UI for production:

ui <- fluidPage(
  aiAssistantUI("ai", show_api_config = FALSE)
)

server <- function(input, output, session) {
  callModule(aiAssistant, "ai",
    data = data,
    data_label = data.label,
    show_api_config = FALSE  # Use only .Renviron
  )
}

API Key Not Found

Problem: “API key not configured” error

Solution:

1. Check .Renviron file has correct variable name
2. Restart R session after editing .Renviron
3. Verify key is valid (test in terminal: Sys.getenv("ANTHROPIC_API_KEY"))

Code Execution Errors

Problem: Generated code fails to execute

Solution:

1. Click “Ask AI to Fix” button for automatic correction
2. Review code in editor before execution
3. Check data has required variables
4. Verify packages are installed

Summary Results Too Fragmented

Problem: summary() results split into many pieces

Solution: This is now fixed in the latest version. Update jsmodule package.

Text Output Shows Escape Sequences

Problem: \n visible instead of line breaks

Solution: This is now fixed in the latest version. Update jsmodule package.

1. Be Specific in Questions

❌ Bad: “analyze this data”

✅ Good: “perform linear regression with wt.loss as outcome and age, sex, ph.ecog as predictors”

2. Review Generated Code

Always review code in the editor before clicking “Run Code”

3. Provide Context

Use analysis_context parameter to give AI background about your data

4. Use Appropriate Model

• Use faster models (Sonnet, GPT-4o) for simple tasks
• Use advanced models (Opus, GPT-4) for complex analyses

5. Iterative Refinement

Ask follow-up questions to refine code rather than starting over

Example 1: Descriptive Statistics

Q: "Create a Table 1 comparing baseline characteristics by treatment group (rx)"

Example 2: Survival Analysis

Q: "Perform Cox regression with time and status as survival outcome,
    adjusting for age, sex, and ph.ecog"

Example 3: Visualization

Q: "Create a Kaplan-Meier plot stratified by treatment group with risk table"

Example 4: Model Diagnostics

Q: "Check VIF for multicollinearity in the linear model with wt.loss ~ age + sex + ph.ecog"

Code Execution Security

# No setup needed - defaults to development mode
# Or explicitly set in .Renviron:
# DEPLOYMENT_ENV=development

# Add to .Renviron file:
# DEPLOYMENT_ENV=production

# In your app directory
touch .production

# Install AppArmor
sudo apt-get install apparmor apparmor-utils libapparmor-dev

# Install R package
R -e "install.packages('RAppArmor')"

API Key Security

⚠️ IMPORTANT: API Key Handling

How API Keys are Used:

• API keys are read from environment variables (.Renviron) or UI input
• When entered in UI, keys exist only in the current R session memory
• API calls are made using the httr package to AI provider APIs

This is Open Source:

• All code is publicly available and auditable at https://github.com/jinseob2kim/jsmodule
• No hidden API key storage or transmission
• You can review the code yourself

✅ What this module does NOT do with API keys:

• Never saves them anywhere
• Never logs them
• Never transmits them except to the AI provider

✅ What IS sent to AI providers:

• Your prompts and questions
• Data structure information (variable names, types, sample statistics)
• Previous conversation history
• Generated code (for error fixing)

NOT sent:

• Raw data values (unless explicitly included in your question)
• File system information

# Store API key in .Renviron (user's home directory)
# This keeps the key private to your user account
# ANTHROPIC_API_KEY=your_key_here

Recommended Security Setup

For Maximum Security:

# 1. Store API key in .Renviron (never in code)
usethis::edit_r_environ()
# Add: ANTHROPIC_API_KEY=your_key

# 2. Use show_api_config = FALSE in production
aiAssistantUI("ai", show_api_config = FALSE)

# 3. Never commit .Renviron to version control
# Add to .gitignore:
# .Renviron
# .Renviron.local

# 4. Rotate API keys regularly (every 90 days recommended)

# 5. Monitor API usage through provider's dashboard