Interactive Exploration with gripui

Supported interactive workflows

For the first public release, grip documents two supported Shiny-based exploration workflows:

the original project explorer, launched with run_gripui(), for browsing realized layout catalogs;
the graph-family geometry explorer, launched with run_gripui_family(), for interactively generating and viewing synthetic graph families.

They solve different problems:

use run_gripui() when you already have layout results and want to compare, filter, and inspect them;
use run_gripui_family() when you want to browse the package’s synthetic graph-geometry library and its parameter space.

library(grip)

Optional dependencies

These two documented apps rely on packages listed in Suggests:

shiny
bslib
DT
htmltools
rgl

If any of these are missing, the app constructors stop with a clear message.

Part 1: the project explorer

The project explorer is built around a normalized gripui_project object. The usual workflow is:

generate layouts,
wrap them into a project,
launch the app.

Building a project from `compare.layouts()`

The shortest path is gripui_project_from_compare().

edges <- edges.mesh(5, 5)
n <- 25L

cmp <- compare.layouts(
  edges = edges,
  n = n,
  dim = 2,
  candidates = list(
    default = list(),
    tuned = list(
      preset = "mesh",
      rounds = 48L,
      final_rounds = 96L
    )
  ),
  seeds = 1:2,
  return.layouts = TRUE
)

knitr::kable(
  cmp$summary[, c("candidate", "sampled.stress.mean",
                  "edge.length.cv.mean", "score.composite")],
  digits = 4
)

candidate	sampled.stress.mean	edge.length.cv.mean	score.composite
tuned	9.1941	0.0554	0
default	18.9094	0.1655	1

adj <- vector("list", n)
for (i in seq_len(nrow(edges))) {
  adj[[edges[i, 1L]]] <- c(adj[[edges[i, 1L]]], edges[i, 2L])
  adj[[edges[i, 2L]]] <- c(adj[[edges[i, 2L]]], edges[i, 1L])
}
graph <- list(adj_list = lapply(adj, function(x) sort(unique(as.integer(x)))))

project <- gripui_project_from_compare(
  cmp,
  graph = graph,
  title = "5x5 mesh comparison"
)

project$meta$title
#> [1] "5x5 mesh comparison"
knitr::kable(project$layouts[, c(
  "layout_id", "candidate", "stage", "seed", "status", "availability"
)])

layout_id	candidate	stage	seed	status	availability
compare_default_seed_001	default	compare	1	ok	interactive
compare_default_seed_002	default	compare	2	ok	interactive
compare_tuned_seed_001	tuned	compare	1	ok	interactive
compare_tuned_seed_002	tuned	compare	2	ok	interactive

Building a project by hand

When the layouts come from another source, use gripui_project() directly.

layouts_df <- data.frame(
  candidate = c("run_a", "run_b"),
  stage = c("layout", "layout"),
  seed = c(1L, 2L),
  status = c("ok", "ok"),
  my_score = c(0.42, 0.37),
  stringsAsFactors = FALSE
)

manual_project <- gripui_project(
  graph = NULL,
  layouts = layouts_df,
  title = "Manual example"
)

manual_project$meta$title
#> [1] "Manual example"

Validation and directory loading

Two helpers round out the project workflow:

gripui_validate_project() checks structure and consistency,
gripui_project_from_dir() assembles a project from saved artifacts on disk.

gripui_validate_project(project)

# Not run: requires a saved output directory
project <- gripui_project_from_dir(
  root = "/path/to/saved/outputs",
  title = "My saved search"
)
run_gripui(project)

Launching the project explorer

gripui_app() builds the app object, while run_gripui() launches it.

project.app <- gripui_app(project)
inherits(project.app, "shiny.appobj")
#> [1] TRUE

run_gripui(project)

The project explorer is the right tool when you want:

a catalog table of realized layouts,
a score landscape,
a synchronized 2D or 3D viewer,
and artifact-aware browsing of saved search results.

That applies to both unweighted and weighted layout catalogs once you have already generated the candidate runs.

Part 2: the graph-family geometry explorer

The second app is geometry-first. Instead of browsing a catalog of realized layouts, it lets you interactively generate the synthetic graph families that support the package’s testing and benchmark workflows.

Its main entry points are:

The family catalog

The catalog is a registry of family descriptors used by the geometry explorer. Each descriptor records the family name, category, presets, parameter controls, builder call, and source references.

catalog <- gripui_graph_family_catalog()

length(catalog)
#> [1] 30
head(names(catalog))
#> [1] "mesh"                "irregular_rectangle" "sampled_rectangle"  
#> [4] "cylinder"            "torus"               "sphere"
catalog$mesh$function_name
#> [1] "mesh.surface.graph"

What the family explorer is for

The family explorer is useful when you want to:

browse the synthetic family collection,
change family parameters without writing code,
inspect 2D and 3D embeddings interactively,
compare several family presets side by side,
and recover the corresponding R call for a chosen example.

This app is particularly helpful when designing benchmark suites or reviewing which graph families belong in a paper, test, or demo.

Launching the family explorer

family.app <- gripui_family_app()
inherits(family.app, "shiny.appobj")
#> [1] TRUE

run_gripui_family()

The geometry explorer includes:

an Explore mode for one family at a time,
a Compare mode for side-by-side family or preset panels,
a dynamic parameter sidebar that adapts to the current family,
interactive 3D viewing through rgl,
and graph/weight/geometry summaries for the generated example.

Which app should you use?

Use run_gripui() when:

you already have layout results,
you want to compare candidates or saved searches,
you care about score tables and layout catalogs.

Use run_gripui_family() when:

you want to inspect the synthetic family collection,
you are choosing benchmark families,
you want to understand or demo the package’s geometry generators,
you need a quick interactive way to recover family-building calls.

Practical notes

The apps are optional-package features, so they are best launched in an interactive R session rather than inside a scripted report.
run_gripui_family() is self-contained because it builds its own synthetic examples from the family catalog.
run_gripui() is best thought of as a viewer for a prepared gripui_project.

Where to go next

Getting Started with grip introduces the main layout APIs.
Synthetic Graph Families and Geometries describes the family collection that powers the geometry explorer.
Choosing Layouts for Real Data shows how the project explorer fits into a real-data layout-selection workflow.