Package {sideview}

Create a New Sideview Canvas State Object

Description

Constructs a structured sideview_state object containing canvas transform, card configurations, table join connections, and pipeline script state.

Usage

new_sideview_state(
  version = "0.3.0",
  canvas = list(zoom = 1, pan_x = 0, pan_y = 0),
  cards = list(),
  connections = list(),
  pipeline = list(code = "", active_tab = "pipeline")
)

Arguments

Details

The canvas writes this shape when you click Save in the toolbar, and sideview(..., state = ) / sideview_widget(..., state = ) restore it. Cards are matched to tables by name.

Value

An object of class c("sideview_state", "list").

Examples

st <- new_sideview_state()
print(st)

Print Method for Sideview State Objects

Description

Displays a concise summary of the canvas state including version, card count, and active connections.

Usage

## S3 method for class 'sideview_state'
print(x, ...)

Arguments

Value

Invisibly returns x.

Shiny Render Function for Sideview Widget

Description

Shiny Render Function for Sideview Widget

Usage

renderSideview(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

An S3 object of class c("shiny.render.function", "function").

Save Sideview Widget to a Standalone HTML File

Description

Exports a sideview htmlwidget or table objects to a self-contained HTML file with all styles, fonts, and JavaScript embedded.

Usage

save_sideview(
  widget,
  file,
  selfcontained = TRUE,
  title = "Sideview",
  background = "white",
  ...
)

Arguments

Value

The normalized path to the saved file (invisibly).

Examples

out <- tempfile(fileext = ".html")
save_sideview(mtcars, file = out)
unlink(out)

Multi-Table 2D Infinite Canvas Interactive Gadget

Description

Launches an interactive Shiny gadget containing an infinite 2D canvas with mouse-wheel zoom, pan, draggable table cards, interactive column mapping, discrepancy recoding, and LLM-assisted tidyverse code generation.

Usage

sideview(
  ...,
  title = "Sideview Canvas",
  viewer = if (requireNamespace("rstudioapi", quietly = TRUE) &&
    rstudioapi::isAvailable()) {
     shiny::dialogViewer("Sideview Canvas", width =
    1400, height = 900)
 } else {
     shiny::paneViewer(minHeight = 500)
 },
  theme = "auto",
  state = NULL,
  env = parent.frame(),
  run = interactive()
)

Arguments

Value

If run = TRUE, the generated code (invisibly) when you click Done, or NULL after Cancel or closing the window. If run = FALSE, returns a shiny.appobj with the normalized cards attached.

Keyboard and navigation

Single-key shortcuts work when the canvas has the keyboard and you are not typing: F fit all cards, 0 reset zoom, +/- zoom, M show or hide the minimap, D the drawer, T light/dark, / the AI prompt and ⁠?⁠ the full list. Ctrl+K finds a card or column, Ctrl+Z/Ctrl+Y undo and redo a pipeline step, and Esc cancels a connection or closes a popover. Double-click a card title, a minimap rectangle or a search result to zoom to that card.

Options

sideview.session_grace

Seconds the gadget waits after its last browser session closes before stopping (default 5), so reloading the page does not end the app.

sideview.llm_backend

"ollama" (default, or the SIDEVIEW_LLM_BACKEND variable) or "openai" for any OpenAI-compatible server.

sideview.llm_model

Model name. Defaults to SIDEVIEW_OLLAMA_MODEL or "llama3.2" for Ollama, and SIDEVIEW_OPENAI_MODEL or "gpt-4o-mini" otherwise. sv_llm_models() lists what is available.

sideview.llm_endpoint

Base URL. Defaults to OLLAMA_HOST or ⁠http://localhost:11434⁠, and OPENAI_BASE_URL or ⁠https://api.openai.com/v1⁠.

sideview.llm_api_key

API key for OpenAI-compatible servers (default: the OPENAI_API_KEY variable).

sideview.llm_think

TRUE lets Ollama reasoning models "think" before answering. Default FALSE, so they answer promptly.

Only schema summaries (column names, types and simple profiles) are sent to the model, never raw rows.

Examples

if (interactive()) {
  sideview(mtcars, iris)
}

Shiny Output Container for Sideview Widget

Description

Shiny Output Container for Sideview Widget

Usage

sideviewOutput(outputId, width = "100%", height = "600px")

Arguments

Value

A shiny.tag object representing the widget container.

RStudio Addin for Sideview

Description

Automatically discovers tabular datasets in the user's active environment and launches the Sideview interactive multi-table canvas gadget.

Usage

sideview_addin(
  env = .GlobalEnv,
  viewer = if (requireNamespace("rstudioapi", quietly = TRUE) &&
    rstudioapi::isAvailable()) {
     shiny::dialogViewer("Sideview Canvas", width =
    1400, height = 900)
 } else {
     shiny::paneViewer(minHeight = 500)
 },
  run = interactive()
)

Arguments

Value

Result of sideview(...), invisibly when the gadget was run.

Sideview Server Logic

Description

Orchestrates bi-directional Shiny reactivity between the infinite 2D canvas and the R session. Handles field mapping (column_mapped), column renaming (column_renamed), discrepancy calculations (discrepancy_check), natural language AI prompts (run_ai_prompt), RStudio script injection (inject_script), and RStudio console execution (send_console).

Usage

sideview_server(
  cards = list(),
  ...,
  llm_fn = sv_call_llm,
  insert_fn = sv_insert_code,
  console_fn = sv_send_to_console,
  gadget = FALSE,
  run_env = parent.frame()
)

Arguments

Value

A Shiny server function ⁠function(input, output, session)⁠.

Sideview User Interface

Description

Builds the complete 2D infinite canvas user interface for Sideview, containing the draggable table cards, panzoom canvas, SVG connector overlay, action drawer, and natural language AI bar with all HTML dependencies attached.

Usage

sideview_ui(
  cards = list(),
  title = "Sideview Canvas",
  gadget = FALSE,
  theme = "auto",
  state = NULL
)

Arguments

Value

A shiny.tag.list UI definition.

Create a Standalone Sideview HTMLWidget

Description

Normalizes passed table objects (data.frame, tibble, table, gt, flextable, htmlwidgets) and creates an interactive 2D infinite canvas htmlwidget suitable for rendering in R Markdown, Quarto, Shiny, or exporting via save_sideview().

Usage

sideview_widget(
  ...,
  width = NULL,
  height = NULL,
  elementId = NULL,
  options = list(),
  theme = "auto",
  state = NULL
)

Arguments

Value

An S3 object of class c("sideview", "htmlwidget").

Examples

if (interactive()) {
  sideview_widget(mtcars, iris)
}

Generate tidyverse Code for Automatic Discrepancy Cleaning and Crosswalks

Description

Inspects discrepancy detection output or pairwise column discrepancies (exact matches, fuzzy near-matches, and missing levels), automatically synthesizing clean recoding rules using dplyr::case_when(). Handles casing differences, leading/trailing whitespace discrepancies, and fuzzy string distance variations (Levenshtein distance <= 2).

Usage

sv_auto_clean_rules(
  discrepancy_result,
  df_name = "df",
  col = "status",
  default = col,
  pipe = FALSE
)

sv_code_auto_clean(
  discrepancy_result,
  df_name = "df",
  col = "status",
  default = col,
  pipe = FALSE
)

Arguments

Value

A character string of tidyverse code, or NULL if no discrepancies require cleaning.

Examples

disc <- sv_detect_discrepancies(c("male", "Female"), c("Male", "Female"))
sv_auto_clean_rules(disc, df_name = "patients", col = "gender")

Build Structured Multi-Turn Prompt for Conversational Copilot

Description

Formats a multi-turn conversational prompt for the Sideview AI Copilot drawer. Preserves database/table schema context, active pipeline R code, and previous dialogue turns (user/assistant). Instructs the model to output updated executable tidyverse R code within code fences.

Usage

sv_build_chat_prompt(
  user_message,
  history = list(),
  current_code = NULL,
  schema_context = NULL
)

Arguments

Value

A list of class c("sideview_chat_prompt", "sideview_prompt", "list") containing system_message, user_message, history, messages, and prompt.

Build Structured Prompt for Tidyverse LLM Code Generation

Description

Formats system instructions emphasizing pure, executable tidyverse R code enclosed in markdown code fences (⁠```r ... ```⁠) and packages user task description alongside privacy-safe table schemas.

Usage

sv_build_prompt(user_prompt, schema_context = NULL)

Arguments

Value

A list of class sideview_prompt containing system_message, user_message, and prompt.

Build a Privacy-Safe Schema Context from Sideview Cards

Description

Summarizes the metadata of sideview cards (table names, dimensions, column names, types, value ranges for numerics/dates, sample levels for factors, and unique samples for characters) without leaking full raw row data or records. Non-tabular widget cards and NULL data are handled safely.

Usage

sv_build_schema_context(cards, max_categories = 5L)

Arguments

Value

A character string containing the privacy-safe schema summary.

Call Local Ollama or OpenAI-Compatible LLM Endpoint

Description

Sends prompt requests to local Ollama (⁠http://localhost:11434⁠) or OpenAI-compatible endpoints via httr2. Supports model selection, customizable endpoints, API key authentication, and clean error reporting for network or HTTP status failures.

Usage

sv_call_llm(
  prompt,
  backend = c("ollama", "openai"),
  model = NULL,
  endpoint = NULL,
  api_key = NULL,
  timeout = 60,
  extract_code = FALSE,
  resolve_model = TRUE,
  ...
)

Arguments

Value

Character string containing the LLM response text (or extracted code if extract_code = TRUE).

Generate tidyverse Code for Arranging (Sorting) Rows

Description

Generate tidyverse Code for Arranging (Sorting) Rows

Usage

sv_code_arrange(df_name, col, desc = FALSE, pipe = FALSE)

Arguments

Value

A character string of R code.

Generate tidyverse Code for Filtering Rows

Description

Generate tidyverse Code for Filtering Rows

Usage

sv_code_filter(df_name, condition, pipe = FALSE)

Arguments

Value

A character string of R code.

Generate tidyverse Code for Grouping and Aggregating Data

Description

Constructs syntactically valid dplyr::group_by() and dplyr::summarise() pipelines with identifier escaping, customizable summary metrics, and reproducible grouping behavior via .groups = 'drop'.

Usage

sv_code_group_summarize(
  df_name = NULL,
  group_cols,
  summary_exprs,
  pipe = FALSE
)

Arguments

Value

A character string of R code.

Generate tidyverse Code for Relational Table Joins

Description

Generate tidyverse Code for Relational Table Joins

Usage

sv_code_join(df1, df2, col1, col2 = col1, join_type = "left", pipe = FALSE)

Arguments

Value

A character string of R code.

Generate tidyverse Code for Column Mutation

Description

Generate tidyverse Code for Column Mutation

Usage

sv_code_mutate(df_name, new_col, expr, pipe = FALSE)

Arguments

Value

A character string of R code.

Generate tidyverse Code for Reshaping Data from Wide to Long

Description

Constructs syntactically valid tidyr::pivot_longer() calls with proper identifier escaping and support for both piped workflows and direct calls.

Usage

sv_code_pivot_longer(
  df_name = NULL,
  cols,
  names_to = "name",
  values_to = "value",
  pipe = FALSE
)

Arguments

Value

A character string of R code.

Generate tidyverse Code for Reshaping Data from Long to Wide

Description

Constructs syntactically valid tidyr::pivot_wider() calls with proper identifier escaping and optional aggregation functions.

Usage

sv_code_pivot_wider(
  df_name = NULL,
  names_from,
  values_from,
  values_fn = NULL,
  pipe = FALSE
)

Arguments

Value

A character string of R code.

Generate tidyverse Code for Categorical Recoding and Discrepancy Crosswalks

Description

Generate tidyverse Code for Categorical Recoding and Discrepancy Crosswalks

Usage

sv_code_recode(
  df_name,
  col,
  crosswalk,
  default = NULL,
  method = c("case_when", "case_match", "fct_recode"),
  pipe = FALSE
)

Arguments

Value

A character string of R code.

Generate tidyverse Code for Column Renaming

Description

Generate tidyverse Code for Column Renaming

Usage

sv_code_rename(df_name, old_col, new_col, pipe = FALSE)

Arguments

Value

A character string of R code.

Generate tidyverse Code for Selecting Columns

Description

Generate tidyverse Code for Selecting Columns

Usage

sv_code_select(df_name, cols, pipe = FALSE)

Arguments

Value

A character string of R code.

Codebook (Data Dictionary)

Description

One row per column across one or more tables: type, label, missingness, distinct values, whether the column is a unique key, range and quartiles, mean and SD, the most common values and data-quality flags. Write it to CSV or Excel to document a dataset or check it before analysis.

Usage

sv_codebook(..., top_n = 5L, file = NULL)

Arguments

Value

A data frame with columns table, column, position, class, label, n, n_missing, pct_missing, n_distinct, unique_key, min, q1, median, q3, max (as text, so dates fit), mean, sd, top_values and issues.

Examples

patients <- data.frame(id = 1:4, sex = c("M", "F", "f", NA), age = c(40, 51, 62, 999))
sv_codebook(patients)
visits <- data.frame(id = c(1, 1, 2, 5), sbp = c(120, 135, 128, 141))
out <- tempfile(fileext = ".csv")
sv_codebook(patients, visits, file = out)
unlink(out)

Column Profile

Description

Summarises one column for the column inspector: counts, missingness, distinct values, whether it could serve as a unique key, quartiles and a histogram for numbers, the most common values for text, and data-quality flags (stray spaces, values that differ only in case, numbers stored as text, empty strings, extreme values).

Usage

sv_column_profile(x, top_n = 10L, bins = 20L)

Arguments

Value

A list with kind ("numeric", "character", "logical", "date", "datetime" or "other"), class, label (the "label" attribute, if any), n, n_missing, pct_missing, n_distinct (non-missing), unique_key, stats (named list: min, q1, median, q3, max, and mean, sd for numbers), histogram (breaks, counts), top (data frame of value, n), n_other (distinct values not in top) and issues (character).

Examples

sv_column_profile(c(" Male", "male", "Female", NA))
sv_column_profile(c(54, 61, 47, 999, NA))$issues

Detect Exact Matches, Discrepancies, and Fuzzy Near-Matches

Description

Compares distinct values between two vectors (e.g. columns mapped across tables), computing exact matches, values only in x, values only in y, fuzzy/near-matches using Levenshtein distance (adist), and comprehensive match statistics.

Usage

sv_detect_discrepancies(x, y, max_distance = 2)

Arguments

Value

A list with elements:

• exact_matches: character vector of values present in both x and y.

• fuzzy_matches: data.frame with columns x, y, distance.

• only_in_x: character vector of values present only in x.

• only_in_y: character vector of values present only in y.

• stats: list of match statistics (counts, NA counts, match rate).

• match_stats: alias to stats.

Escape R Identifiers with Backticks If Non-Syntactic

Description

Escape R Identifiers with Backticks If Non-Syntactic

Usage

sv_escape_ident(x)

Arguments

Value

Character vector of identifiers, escaped with backticks if necessary.

Extract Executable R Code from LLM Response Text

Description

Parses code fence blocks (⁠```r ... ```⁠, ⁠```R ... ```⁠, ⁠``` ... ```⁠) out of LLM responses. If multiple fences exist, concatenates them. If no fence is found, falls back to the trimmed raw text. Strips extraneous whitespace and returns valid R code.

Usage

sv_extract_code(response_text)

Arguments

Value

A character string of extracted R code.

Find Tabular Data Objects in an Environment

Description

Scans an environment for tabular objects, including data.frame, tibble, matrix, table, gt, flextable, and sideview_card objects.

Usage

sv_find_tables(env = parent.frame())

Arguments

Value

A named list of tabular objects found in the environment.

Insert Generated Code into the Active RStudio Editor

Description

Inserts tidyverse pipelines or generated code directly into the user's active document buffer at the current cursor location via rstudioapi::insertText(). If RStudio is unavailable, running headless, or if no document is currently open, falls back gracefully by returning a structured status list containing the code.

Usage

sv_insert_code(code, location = NULL, ...)

Arguments

Value

A named list with:

Examples

res <- sv_insert_code("library(dplyr)")

Check if RStudio API is Available

Description

Safely tests whether the RStudio API is running and operational in the current session without raising errors in headless, testing, or CI environments.

Usage

sv_is_rstudio_available()

Value

Logical scalar (TRUE if RStudio is running and accessible, FALSE otherwise).

Examples

sv_is_rstudio_available()

Join Diagnostics

Description

Checks a join before you run it: how many rows match in each direction, the key relationship (one-to-one, one-to-many, many-to-many), how many rows each join type returns, missing and duplicated keys, a sample of unmatched keys, and fixes that would match more rows, each measured on its own (trimming whitespace, ignoring case, dropping leading zeros). Keys are compared the way dplyr joins compare them by default, so NA matches NA.

Usage

sv_join_diagnostics(x, y, by, sample_n = 5L, x_name = "x", y_name = "y")

Arguments

Details

The canvas runs this whenever two columns are connected and shows the result on the join step and in the Discrepancy tab.

Value

An object of class sv_join_diagnostics: a list with by (data frame of x/y columns), n_x, n_y, distinct_x, distinct_y, distinct_matched, matched_x, matched_y (rows with a partner), match_rate_x, match_rate_y, na_x, na_y (rows with a missing key), dup_keys_x, dup_keys_y (keys that occur more than once), relationship, rows (named list of row counts per join type), unmatched_x, unmatched_y (sample keys), type_issues, hints (list of fix, label, extra_x, extra_y), warnings and status ("ok", "warn" or "error").

Examples

patients <- data.frame(id = c(1, 2, 3, 4), age = c(40, 51, 62, 33))
visits <- data.frame(id = c(1, 1, 2, 5), visit = 1:4)
sv_join_diagnostics(patients, visits, by = "id")

List the models available from an LLM backend

Description

Queries a local Ollama server (⁠/api/tags⁠) or an OpenAI-compatible server (⁠/models⁠) for the installed or available model names. Useful for choosing options(sideview.llm_model = ...).

Usage

sv_llm_models(
  backend = c("ollama", "openai"),
  endpoint = NULL,
  api_key = NULL,
  timeout = 5
)

Arguments

Value

A character vector of model names.

Load Canvas State from File

Description

Deserializes a previously saved Sideview canvas workspace from a .json or .rds file and returns a sideview_state object. Optionally launches an interactive session.

Usage

sv_load_state(file, tables = NULL, launch = FALSE, format = NULL, ...)

Arguments

Value

A sideview_state object of class c("sideview_state", "list"), or the gadget result if launch = TRUE in an interactive session.

Examples

st <- new_sideview_state()
tf <- tempfile(fileext = ".json")
sv_save_state(st, tf)
loaded <- sv_load_state(tf)
print(loaded)
unlink(tf)

Universal Normalization Engine for Sideview Cards

Description

Converts various R table formats (data.frame, tibble, table, gt, flextable, htmlwidgets) into a standardized sideview_card S3 object for rendering on the 2D infinite canvas.

Usage

sv_normalize(x, name = NULL, id = NULL, ...)

Arguments

Value

An object of class sideview_card.

Save Canvas State to File

Description

Serializes the active Sideview canvas state (cards, positions, filters, connections, and pipeline code) to either .json or .rds format.

Usage

sv_save_state(state, file, format = NULL)

Arguments

Value

Invisibly returns the path of the saved file.

Examples

st <- new_sideview_state()
tf <- tempfile(fileext = ".json")
sv_save_state(st, tf)
unlink(tf)

Send Generated Code to the RStudio Console

Description

Sends R code to the RStudio console for immediate evaluation or user inspection. Falls back gracefully without crashing if RStudio is unavailable or running in a headless environment.

Usage

sv_send_to_console(code, execute = TRUE, ...)

Arguments

Value

A named list with:

Examples

res <- sv_send_to_console("1 + 1", execute = FALSE)

Suggest Foreign Key Mappings Across Canvas Cards

Description

Evaluates pairwise heuristic column relationships across loaded sideview_card objects or tabular data structures, computing a 3-part composite confidence score based on name similarity (40%), data type compatibility (20%), and Jaccard value overlap (40%).

Usage

sv_suggest_mappings(cards, ..., min_confidence = 0.6)

Arguments

Value

A data.frame with columns:

from_table

Source table or card name.

from_col

Source column name.

to_table

Destination table or card name.

to_col

Destination column name.

confidence

Composite confidence score in ⁠[0, 1]⁠.

reason

Human-readable justification describing similarity components.

Examples

df1 <- data.frame(patient_id = 1:5, age = c(20, 30, 40, 50, 60))
df2 <- data.frame(patient_id = 3:7, score = c(10, 20, 30, 40, 50))
sv_suggest_mappings(list(patients = df1, visits = df2))

Canvas Theme

Description

Builds a theme for sideview() and sideview_widget(): a light/dark mode plus optional overrides of the canvas design tokens (the ⁠--sv-*⁠ CSS custom properties in inst/www/sideview.css).

Usage

sv_theme(
  mode = c("auto", "light", "dark"),
  primary = NULL,
  font = NULL,
  font_mono = NULL,
  radius = NULL,
  ...
)

Arguments

Value

An object of class sv_theme.

Examples

sv_theme("dark")
sv_theme(primary = "#0f766e", radius = "4px")
if (interactive()) sideview(mtcars, theme = sv_theme("dark", primary = "#f59e0b"))