---
title: "Getting Started with grip"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with grip}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 8.5,
  fig.height = 5.2
)
```

## What this vignette covers

`grip` has four main user workflows:

- `grip()` for ordinary unweighted or topology-first graphs,
- `weighted.grip()` when edge lengths carry geometry you want to keep,
- `compare.layouts()` and `score.layout()` when you want a
  disciplined real-data shortlist,
- `trace.grip()` and `trace.weighted.grip()` when you need
  diagnostics rather than just a final picture.

This vignette is the shortest path through the default workflow. It shows how
to:

- compute a first unweighted layout,
- score it,
- compare a few plausible candidates,
- and decide when to switch to the specialist guides.

For weighted layouts, real-data search, tracing, and interactive exploration,
the later guides go deeper. Advanced GKK/LGKK tools are public, but they are
treated as later-stage experimental helpers rather than the default starting
point.

```{r}
library(grip)
```

## A first unweighted layout

For an ordinary unweighted graph, `grip()` is the default starting
point. Here is a small mesh in 2D.

```{r}
mesh.edges <- edges.mesh(5, 5)
mesh.coords <- grip(
  mesh.edges,
  n = 25,
  dim = 2,
  preset = "mesh",
  seed = 1
)

mesh.score <- score.layout(mesh.coords, edges = mesh.edges, n = 25)
knitr::kable(mesh.score[, c(
  "sampled.stress",
  "edge.length.cv",
  "sampled.nonedge.sep.ratio"
)], digits = 3)
```

```{r fig.width=5.2, fig.height=4.6}
plot.layout(
  mesh.coords,
  mesh.edges,
  main = "grip() on a 5x5 mesh",
  pch = 16,
  cex = 0.65,
  edge.col = "gray82"
)
```

For small and medium unweighted graphs, that is often all you need:

- choose `dim = 2` or `dim = 3`,
- optionally start from a preset,
- and score or compare a few candidate settings if the graph is important.

## Compare a few plausible candidates

If the first picture matters, it is usually better to compare a short candidate
list than to tune blindly. `compare.layouts()` runs several seeds and
summarizes the results in a score table.

```{r}
mesh.cmp <- compare.layouts(
  edges = mesh.edges,
  n = 25,
  dim = 2,
  candidates = c("default", "mesh", "tree"),
  seeds = 1:2,
  sample.size.stress = 500L,
  sample.size.nonedge = 1000L,
  edge.crossings = "never"
)

knitr::kable(mesh.cmp$summary[, c(
  "candidate",
  "sampled.stress.mean",
  "edge.length.cv.mean",
  "sampled.nonedge.sep.ratio.mean",
  "score.composite"
)], digits = 3)
```

That same pattern scales to real graphs:

- shortlist a few plausible presets,
- run several seeds,
- inspect the summary table before choosing a favorite picture,
- then search locally only if the graph is important enough to justify it.

## What if the graph is weighted?

If a graph has edge weights but those weights are mostly metadata, a
topology-first `grip()` run can still be a useful baseline. When the
edge lengths represent geometry that the layout should preserve, the default
path changes:

- start from `weighted.grip()`,
- prefer 3D when the graph geometry is genuinely three-dimensional,
- and add GKK/LGKK only later if you need advanced geodesic-aware scoring or
  polish on a smaller weighted candidate set.

## When should you switch workflows?

Start with `grip()` when the graph is fundamentally unweighted and you
mainly care about its combinatorial structure.

Switch to the other guides when the task changes:

- use `weighted.grip()` when edge lengths encode geometry you care
  about,
- use `compare.layouts()` on real graphs when you want a disciplined
  shortlist rather than a single run,
- use `trace.grip()` or `trace.weighted.grip()` when you want to
  inspect how a solve evolves,
- use GKK/LGKK only after you already have weighted candidate layouts and need
  advanced experimental geodesic-aware scoring or polish,
- use `run_gripui()` or `run_gripui_family()` in an interactive R session when
  you want app-based exploration.

## Where to go next

- `Weighted Graph Layouts with grip` covers weighted solving, geodesic scoring,
  and 2D-versus-3D decisions.
- `Choosing Layouts for Real Data` focuses on candidate shortlisting, local
  search, and real-data evaluation.
- `Tracing and Diagnosing Layouts` covers trace objects and per-frame
  diagnostics.
- `Interactive Exploration with gripui` is a website article about the
  package's Shiny tools.
- `Synthetic Graph Families and Geometries` is a website article about the
  benchmark and geometry library.