% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/70-plotting.R
\name{plot_structure}
\alias{plot_structure}
\title{Plot the Internal Finger-Tree Structure}
\usage{
plot_structure(
  t1,
  vertex.size = 15,
  vertex.shape = "rounded_rect",
  edge.width = 1,
  label_edges = FALSE,
  title = NULL,
  node_label = "value",
  label.cex = NULL,
  asp = NA,
  legend = TRUE,
  ...
)
}
\arguments{
\item{t1}{A finger-tree-backed immutables structure.}

\item{vertex.size}{Passed to \code{igraph::plot.igraph}. Ignored by the default
\code{"rounded_rect"} shape, which sizes each box to its own label text.}

\item{vertex.shape}{Vertex shape. Defaults to \code{"rounded_rect"}, a custom
shape registered on first call that auto-sizes every box to fit its
label (so multi-line labels render cleanly without tuning
\code{vertex.size}). Any built-in igraph shape (\code{"circle"}, \code{"rectangle"},
\code{"none"}, ...) also works and is passed through unchanged.}

\item{edge.width}{Edge width passed to \code{igraph::plot.igraph}.}

\item{label_edges}{If \code{TRUE}, draw the child slot name on each edge
(\code{"prefix"}/\code{"middle"}/\code{"suffix"} for \code{Deep} nodes, or the numeric
position for \code{Digit}/\code{Node2}/\code{Node3}).}

\item{title}{Optional plot title.}

\item{node_label}{Either one of the preset modes \code{"value"} (default;
payload for elements, blank for structural), \code{"type"} (node class
name), \code{"both"} (type + value on separate lines), \code{"none"}, or a
user-supplied function \verb{function(node)} returning a single character
string per vertex. The \code{node} argument is a list with fields:
\describe{
\item{\code{id}}{Internal graph vertex id (string).}
\item{\code{type}}{Node class: \code{"Element"}, \code{"Digit"}, \code{"Deep"},
\code{"Node2"}, \code{"Node3"}, \code{"Single"}, or \code{"Empty"}.}
\item{\code{label}}{The default label string.}
\item{\code{measures}}{Named list of accumulated monoid values for the
subtree rooted at this node. For structural nodes these are the
cached values; for element leaves, each entry is the monoid's
\code{measure()} applied to the leaf entry. Keys include built-ins
(\code{.size}, \code{.named_count}, and any structure-specific ones like
\code{.pq_min}) plus any custom name added via \code{\link[=add_monoids]{add_monoids()}}.}
\item{\code{element}}{For element nodes, the raw leaf entry. Shape
depends on the structure type; see \code{\link[=measure_monoid]{measure_monoid()}} for the
entry contract. \code{NULL} for structural nodes.}
}
Measure values are exposed as-is, including list-valued measures
(e.g. the built-in \code{.pq_min} is \code{list(has, priority)}).}

\item{label.cex}{Numeric scalar controlling label text size (passed as
\code{vertex.label.cex} to igraph). If \code{NULL} (default), scales
automatically from ~1.0 on small trees down to ~0.55 on dense ones so
the auto-sized \code{"rounded_rect"} boxes don't collide. Override with a
fixed value for finer control.}

\item{asp}{Plot aspect ratio (physical y-unit / physical x-unit).
Default \code{NA} lets the tree fill the device without aspect constraint.
Set to a numeric (e.g. \code{0.4}) to enforce horizontal stretching,
or \code{1} for a square plot region.}

\item{legend}{If \code{TRUE} (default), draws a horizontal legend below the
tree mapping node-type names to their fill colors, restricted to
types actually present.}

\item{...}{Additional arguments passed to \code{igraph::plot.igraph} (e.g.
\code{vertex.label.color}, \code{vertex.frame.color}).}
}
\value{
Invoked for its side effect (draws to the active graphics
device). Returns \code{NULL} invisibly.
}
\description{
Developer-facing visualizer for the finger-tree backing any immutables
structure (\code{flexseq}, \code{ordered_sequence}, \code{priority_queue},
\code{interval_index}). The S3 \code{plot()} methods on those classes forward to
this function, but \code{plot_structure()} is also callable directly and gives
access to the full \code{node_label} API for custom label formatting. Requires
the \code{igraph} package (listed in \code{Suggests}).
}
\examples{
if (requireNamespace("igraph", quietly = TRUE)) {
\donttest{
t <- as_flexseq(letters[1:8])
plot_structure(t, title = "Finger tree")

# Label every node with its subtree size (leaves contribute 1).
plot_structure(as_flexseq(1:10), node_label = function(node) {
  paste0(node$type, "\n.size=", node$measures$.size)
})

# Custom monoid: subtree sum of numeric payloads. Structural nodes show
# the accumulated total; leaves show their own contribution.
sum_monoid <- measure_monoid(`+`, 0, function(el) el)
xs <- add_monoids(as_flexseq(c(3, 1, 4, 1, 5, 9, 2, 6)),
                  list(sum = sum_monoid))
plot_structure(xs, node_label = function(node) {
  if(node$type == "Element") sprintf("\%g\nsum=\%g", node$element, node$measures$sum)
  else sprintf("\%s\nsum=\%g", node$type, node$measures$sum)
})

# List-valued built-in measure: priority_queue's .pq_min tracks the min
# priority seen in a subtree as list(has, priority). Unpack in the label.
pq <- priority_queue("task-a", "task-b", "task-c",
                     priorities = c(5, 1, 3))
plot_structure(pq, node_label = function(node) {
  m <- node$measures$.pq_min
  if(node$type == "Element") {
    sprintf("\%s\np=\%g", node$element$value, node$element$priority)
  } else if(isTRUE(m$has)) {
    sprintf("\%s\nmin=\%g", node$type, m$priority)
  } else {
    node$type
  }
})
}
}
}
\seealso{
\code{\link[=measure_monoid]{measure_monoid()}}, \code{\link[=add_monoids]{add_monoids()}}
}
