R/graphr.R

Defines functions .inform_groups_reduced .reduce_categories .as_group_matrix .add_data_arg .infer_node_group .infer_layout .infer_isolates .node_is_isolate .note_corresp_cos2 .broken_stick .note_corresp_inertia .note_corresp_fit .note_scaling_fit .note_fit graphr

Documented in graphr

#' Easily graph networks with sensible defaults
#' 
#' @description 
#'   This function provides users with an easy way to graph
#'   (m)any network data for exploration, investigation, inspiration, 
#'   and communication.
#'   
#'   `graphr()` builds upon `{ggplot2}` and `{ggraph}` to offer
#'   pretty, easy, and extensible graphing solutions.
#'   Just passing the function some network data
#'   will often be sufficient to return a reasonable-looking graph.
#'   
#'   The function also makes it easy to modify many of the most
#'   commonly adapted aspects of a graph, 
#'   including node and edge size, colour, and shape,
#'   as arguments rather than additional functions that you need to remember.
#'   These can be defined outright, e.g. `node_size = 8`, or
#'   in reference to an attribute of the network, e.g. `node_size = "wealth"`.
#'   
#'   Lastly, `graphr()` uses `{ggplot2}`-related theme information, so
#'   it is easy to make colour palette and fonts institution-specific and consistent.
#'   See e.g. `theme_iheid()` for more.
#'   
#'   To learn more about what can be done visually,
#'   try `run_tute("Visualisation")`.
#' @name plot_graphr
#' @family mapping
#' @param .data A manynet-consistent object.
#' @param layout An igraph, ggraph, or manynet layout algorithm.
#'   If not declared, defaults to "configuration" for networks of up to
#'   six nodes, "levels" for connected multilevel networks,
#'   "layered" for other two mode networks,
#'   and "stress" for all other networks.
#'   The "stress" layout of a network of more than 1000 nodes is run at a
#'   looser tolerance (`tolerance = 1e-3`) to save time;
#'   give `tolerance = 1e-4` for the finer layout.
#'   For "layered" layout, one can further split graph by
#'   declaring the "center" argument as the "events", "actors",
#'   or by declaring a node name.
#'   For "concentric" layout algorithm please declare the "membership" as an 
#'   extra argument.
#'   The "membership" argument expects either a quoted node attribute present
#'   in data or vector with the same length as nodes to draw concentric circles.
#'   For "levels" layout algorithm one may declare the "level"
#'   as extra argument.
#'   The "level" argument expects either a quoted node attribute present
#'   in data or vector with the same length as nodes to hierarchically
#'   order categories.
#'   If "level" is missing, the levels are taken from a 'lvl' node attribute
#'   where there is one, or else from the two modes of a two mode network.
#'   The layered layouts ("layered", "lineage", "railway" and "ladder")
#'   accept a "ranks" argument, which takes either one of the methods named
#'   at `?layout_layered` or a numeric node attribute to lay the layers out by,
#'   as a quoted attribute name or a vector with one value for each node.
#'   A "lineage" ranked by such values, such as `ranks = "year"`, is drawn as a
#'   timeline, as a historiograph of citations is: the x axis is broken at
#'   the values, with light vertical gridlines, the ties are curved,
#'   and the labels are repelled.
#'   Every "lineage" draws its ties curved and its mapped node sizes by area
#'   over a wider range.
#'   The "scaling" layout places the nodes by multidimensional scaling,
#'   so that the distance between two nodes approximates the number of steps
#'   between them. Since those coordinates can be read, this layout is drawn
#'   with labelled axes on one scale, and captioned with how well two
#'   dimensions hold the distances; see `?layout_scaling` and `check_stress()`.
#'   Note that those axes carry distances rather than named dimensions:
#'   the drawing can be turned or mirrored without fitting the network
#'   any better or any worse.
#'   The "correspondence" layout places the nodes by correspondence analysis,
#'   so that two nodes with similar ties are drawn together,
#'   whether or not they are tied to each other.
#'   It is the usual way to draw a two mode network, since it places both
#'   modes against the same pair of axes, and it accepts a "direction"
#'   argument for a directed network and a "double" argument for a signed
#'   one; see `?layout_correspondence`.
#'   Each axis names the share of the network's inertia that it holds.
#' @param labels Which nodes to label, if the network is labelled.
#'   `TRUE` (the default) labels every node and `FALSE` none of them,
#'   but a label for every node of a large network hides the network behind
#'   them, so a *selection* of the nodes can be given instead:
#'
#'   - a number, e.g. `labels = 5`, labels the nodes within the top five ranks
#'     by degree. Note that this is a depth of ranks rather than a count of
#'     nodes: nodes tied at the cut are labelled together, so more than five
#'     labels may appear.
#'   - a measure to rank by, e.g. `labels = "betweenness"`, labels just the
#'     node or nodes that measure singles out. `"degree"`, `"betweenness"`,
#'     `"cutpoints"` (every node the mark flags) and `"random"`
#'     (a small random sample) are available.
#'     The two can be combined by naming the number,
#'     as in `labels = c(betweenness = 5)`.
#'   - the name of a logical node attribute, e.g. `labels = "is_broker"`,
#'     labels the nodes it marks.
#'   - a logical vector, one value per node, e.g.
#'     `labels = netrics::node_is_cutpoint(net)`;
#'     or the names or positions of the nodes to label,
#'     e.g. `labels = c("Alice", "Betty")`.
#'
#'   Where a length-one string could mean more than one of these,
#'   a node attribute is preferred to a measure, and a measure to a node name.
#'   A single number is always read as a depth of ranks rather than as one
#'   node's position, so a lone node is best named, as in `labels = "Alice"`.
#'   For networks of more than 30 nodes, `labels` defaults to a selection
#'   rather than to every node; pass `labels = TRUE` for all of them.
#'   For a concept lattice from `manynet::to_concepts()`, `labels` defaults to
#'   the concepts at which a node of the original network first appears,
#'   so that each of those nodes is named once, as in a Hasse diagram,
#'   and the concepts named only by their position are left unlabelled.
#'   Ranking nodes uses the `{netrics}` package, which is suggested rather than
#'   required: without it installed, an automatic selection falls back to a
#'   random sample.
#'   Two-mode and multilevel networks are ranked within each mode or level,
#'   so that every level is labelled and not just the densest.
#' @param node_shape Node variable to be used for shaping the nodes.
#'   It is easiest if this is added as a node attribute to
#'   the graph before plotting.
#'   Nodes can also be shaped by declaring a shape instead.
#' @param node_size Node variable to be used for sizing the nodes.
#'   This can be any continuous variable on the nodes of the network.
#'   Since this function expects this to be an existing variable,
#'   it is recommended to calculate all node-related statistics prior
#'   to using this function.
#'   Nodes can also be sized by declaring a numeric size or vector instead.
#' @param node_color,node_colour Node variable to be used for coloring the nodes.
#'   It is easiest if this is added as a node attribute to
#'   the graph before plotting.
#'   A categorical variable gives one colour to each category.
#'   A measure, such as a centrality or coreness score, is drawn instead as a
#'   gradient from the theme's base colour to its highlight colour,
#'   with a colourbar in place of the legend.
#'   Nodes can also be colored by declaring a color instead.
#' @param node_group Node variable to be used for grouping the nodes.
#'   It is easiest if this is added as a hull over
#'   groups before plotting.
#'   Group variables should have a minimum of 3 nodes,
#'   if less, number groups will be reduced by
#'   merging categories with lower counts into one called "other".
#'   A membership vector can also be given here.
#'   Where nodes belong to several groups at once, as they can to several
#'   cliques, give a membership matrix instead: one row for each node,
#'   one column for each group, and a one wherever the node belongs to
#'   the group. One hull is then drawn for each column, and the hulls
#'   overlap where the groups do.
#'   A measure that returns such a matrix, such as
#'   `netrics::node_x_clique()`, can be named without its network,
#'   which is taken to be the network being drawn.
#' @param edge_color,edge_colour Tie variable to be used for coloring the nodes.
#'   It is easiest if this is added as an edge or tie attribute 
#'   to the graph before plotting.
#'   Edges can also be colored by declaring a color instead.
#' @param edge_size Tie variable to be used for sizing the edges.
#'   This can be any continuous variable on the nodes of the network.
#'   Since this function expects this to be an existing variable,
#'   it is recommended to calculate all edge-related statistics prior
#'   to using this function.
#'   Edges can also be sized by declaring a numeric size or vector instead.
#' @param isolates Character scalar, how to treat isolates.
#'   "keep"  will keep isolates in the graph as they are.
#'   "legend" (default) will remove isolates from the graph but note them in the legend.
#'   "caption" will remove isolates from the graph but note them in the caption.
#'   If there are no isolates, this argument will be ignored.
#'   The "lineage" layout defaults to "keep" instead, since it gives every
#'   node a place in its layers, such as a year;
#'   an `isolates` value that is given is used for it as for any other layout.
#'   If the default layout ("stress") is used,
#'   we recommend that the "legend" option is used to avoid isolates crowding
#'   out the giant component.
#' @param label_repel Where to put the labels.
#'   - `TRUE` (the default) repels the labels away from each other and from
#'     the nodes using `ggrepel` (via `ggraph`'s `repel` argument), leaving a
#'     small gap from each node's border: 5pt where every node is labelled,
#'     and 2pt where only a selection is, so that each label stays against
#'     the node it names. Node size is always accounted for.
#'   - A number, e.g. `label_repel = 10`, repels the labels with a gap of that
#'     many points instead, similar to `igraph`'s `vertex.label.dist`.
#'     Set to `0` for labels right at the node border.
#'   - `FALSE` places each label at a fixed offset from its node, in the
#'     direction the layout suits (outward in "circle" and "concentric",
#'     to the right in "lineage"), without the repelling algorithm, which
#'     can be slow and, for some layouts, differs between runs.
#'   - A direction, `"outside"`, `"above"`, `"below"`, `"left"`, or `"right"`,
#'     places every label at a fixed offset in that direction, whatever the
#'     layout. `"outside"` points away from the middle of the layout.
#'     A gap can be given with it, as in `label_repel = c(above = 3)`.
#'
#'   The layered layouts ("layered", "lineage", "railway" and "ladder")
#'   place each node in a layer, which is where the reader looks for it,
#'   so a repelled label there would say less about which node it labels
#'   than a fixed offset does. They offset the labels instead,
#'   unless a direction is given.
#' @param layout_snap Logical scalar, whether the layout should be snapped to a grid.
#'   Where the network repeats a structure, as a lattice does, the two steps it
#'   repeats are mapped onto the axes, which draws it as a rectangle of rows and
#'   columns. Where it does not, each node moves to the nearest vacant grid
#'   point. Layouts that already carry meaning in their coordinates, such as
#'   "layered" or "scaling", are left as they are.
#' @param edge_bundle Edge bundling, off by default (`FALSE`). When `TRUE` (or
#'   equivalently `"force"`), edges are bundled together using ggraph's
#'   force-directed edge bundling (`geom_edge_bundle_force()`), which pulls
#'   nearby edges into shared paths to reduce visual clutter in dense networks.
#'   Alternative non-hierarchical algorithms can be selected by name:
#'   `"path"` (`geom_edge_bundle_path()`) or `"minimal"`
#'   (`geom_edge_bundle_minimal()`). Bundling only makes a visible difference
#'   when a network has enough edges; for directed networks arrowheads are
#'   retained, but the slight reciprocal-tie curvature used for unbundled edges
#'   does not apply.
#' @param edge_arrows Whether, and at what size, to draw arrowheads on the ties
#'   of a directed network.
#'   By default (`NULL`) this is decided by the network:
#'   a directed network is drawn with arrowheads,
#'   except for a concept lattice from `manynet::to_concepts()` in the
#'   "layered" (its default) or "railway" layout.
#'   That is read as a Hasse diagram, where the direction of each tie is
#'   already given by which of its ends is drawn higher.
#'   In any other layout a concept lattice keeps its arrowheads.
#'   `TRUE` draws arrowheads whatever the network, and `FALSE` none.
#'   Arrowheads follow the width the ties are drawn at:
#'   2mm long at the default `edge_size` of 0.5, and longer on wider ties,
#'   up to 4mm. Where the widths vary, as when they are mapped from a tie
#'   attribute, one size is chosen for all of the arrowheads from the mean
#'   width drawn.
#'   A number, e.g. `edge_arrows = 3`, draws arrowheads of that length in
#'   millimetres instead, whatever the width of the ties.
#'   This is the unit that `{ggplot2}` sizes are given in, as `node_size` is,
#'   so an arrowhead of 3 is a little longer than a node of 3 is wide.
#'   Ties that are not drawn, as with `edge_size = 0`, have no arrowheads.
#'   An undirected network has no direction to show,
#'   so the argument is ignored there.
#' @param backbone How to treat the network's backbone: the ties that a local
#'   null model keeps, because they carry more weight, or sit in more
#'   triangles, than chance alone would put there.
#'   Where a backbone is used, those ties are drawn as the shortest, so that
#'   the layout pulls apart the groups they hold together, and every tie is
#'   still drawn, with the ties the filter does not keep faded well back.
#'   This is what to reach for when a network is dense enough to draw as a
#'   hairball.
#'   By default (`NULL`) this is decided by the network: a network of at least
#'   50 nodes and a mean degree of at least 8 is drawn this way, and reported.
#'   `FALSE` draws every tie alike, and `TRUE` asks for a backbone whatever the
#'   network's size.
#'   One of `manynet`'s filters can be named instead: "disparity", "lans",
#'   "noise", "mlf", or "simmelian". Where none is named, `manynet` uses "lans"
#'   for a weighted network and "simmelian" for an unweighted one.
#'   A number between 0 and 1 sets the threshold instead of the filter:
#'   a smaller number keeps fewer ties.
#'   Only the layouts that read tie lengths -- "stress" (the default), "fr",
#'   "drl" and "kk" -- are laid out this way. Every other layout, including
#'   those that already carry meaning in their coordinates such as "layered"
#'   or "scaling", keeps its coordinates and only fades its ties.
#'   Does not apply to signed networks.
#' @param snap,label_dist Deprecated. Use `layout_snap` instead of `snap`,
#'   and give the gap to `label_repel` instead of `label_dist`.
#' @param ... Extra arguments to pass on to the layout algorithm, if necessary.
#' @return A `ggplot2::ggplot()` object.
#'   The last plot can be saved to the file system using `ggplot2::ggsave()`.
#' @importFrom ggraph geom_edge_link geom_node_text
#' @importFrom ggraph geom_edge_bundle_force geom_edge_bundle_path 
#' @importFrom ggraph geom_edge_bundle_minimal geom_node_label
#' @importFrom ggraph geom_node_point scale_edge_width_continuous 
#' @importFrom ggplot2 aes arrow unit scale_color_brewer scale_fill_brewer
#' @examples
#' graphr(ison_adolescents)
#' ison_adolescents |>
#'   mutate_nodes(color = rep(c("introvert","extrovert"), times = 4),
#'          size = c(3, 6, 3, 3, 3, 6, 6, 3)) |>
#'   mutate_ties(ecolor = rep(c("friends", "acquaintances"), times = 5)) |>
#'   graphr(node_color = "color", node_size = "size",
#'          edge_size = 1.5, edge_color = "ecolor")
#' graphr(ison_southern_women, labels = TRUE, label_repel = 10)
#' # Label a selection of the nodes rather than all of them
#' graphr(ison_southern_women, labels = 2)
#' graphr(ison_adolescents, labels = c("Alice", "Betty"))
#' \donttest{
#' graphr(ison_southern_women, labels = TRUE, label_repel = FALSE)
#' graphr(ison_karateka, label_repel = "outside")
#' graphr(ison_southern_women, labels = "betweenness")
#' graphr(manynet::generate_random(40, 0.1), edge_bundle = TRUE)
#' # Larger arrowheads than the width of the ties would give, or none at all
#' graphr(ison_networkers, edge_arrows = 4)
#' graphr(ison_networkers, edge_arrows = FALSE)
#' graphr(manynet::generate_random(80, 0.2), backbone = TRUE)
#' }
#' @export
graphr <- function(.data, layout = NULL, labels = TRUE,
                   node_color, node_shape, node_size, node_group,
                   edge_color, edge_size,
                   isolates = c("legend","caption","keep"), layout_snap = FALSE,
                   label_repel = TRUE, edge_bundle = FALSE,
                   edge_arrows = NULL, backbone = NULL, ...,
                   node_colour, edge_colour, snap, label_dist) {
  # A list of networks is handed to graphs(). The call is forwarded as written,
  # rather than argument by argument, because the aesthetic arguments have no
  # defaults: naming them here would force promises that are still missing.
  if(manynet::is_list(.data)) {
    cl <- match.call()
    # The function itself rather than its name, since the call is evaluated in
    # the caller's environment, where `graphs` is only visible if the package
    # happens to be attached (it is not for `autograph::graphr(mylist)`).
    cl[[1L]] <- graphs
    names(cl)[names(cl) == ".data"] <- "netlist"
    return(eval(cl, parent.frame()))
  }
  # `graphs()` passes the scales it found across its networks down to each
  # panel as `.shared`, which is no business of the layout's, so it is taken
  # out here and the rest of `...` handed on to the layout.
  dots <- list(...)
  .shared <- dots[[".shared"]]
  dots[[".shared"]] <- NULL
  # Deprecated arguments ----
  if (!missing(snap)) {
    manynet::snet_warn(
      "The {.arg snap} argument of {.fn graphr} is deprecated.",
      "Please use {.arg layout_snap} instead.")
    if (missing(layout_snap)) layout_snap <- snap
  }
  if (!missing(label_dist)) {
    manynet::snet_warn(
      "The {.arg label_dist} argument of {.fn graphr} is deprecated.",
      "Please give the gap to {.arg label_repel} instead,",
      "as in {.code label_repel = {label_dist}}.")
  } else label_dist <- NULL
  label_place <- .check_label_repel(label_repel, label_dist)
  labels_missing <- missing(labels)
  g <- .check_network(.data)
  # Checked here, before isolates are dropped below, so that a vector selecting
  # which nodes to label is measured against the network as the user gave it.
  # It comes back as node names, which survive that change of node positions.
  labels <- .check_labels(g, labels)

  # Separate isolates ----
  # `isolates` is checked on its own line rather than inside .infer_isolates(),
  # which does not always force its argument: an unrecognised `isolates` would
  # otherwise be caught or ignored depending on whether the network happens to
  # have isolates.
  # A "lineage" places each node at its own layer, a date say, so an isolate
  # still has a place to be drawn, and a reader looks for it there rather than
  # in the legend. The layout is checked here for that reason, before the
  # isolates are dropped. An `isolates` the user gave is theirs.
  layout <- .check_layout(layout)
  if (missing(isolates) && .keeps_isolates(layout)) isolates <- "keep"
  isolates <- .check_choice(isolates, c("legend", "caption", "keep"), "isolates")
  isolates <- .infer_isolates(g, isolates)
  if(isolates != "keep"){
    if(manynet::is_labelled(g)){
      isos <- manynet::node_names(g)[.node_is_isolate(g)]
    } else {
      isos <- which(.node_is_isolate(g))
    }
    g <- manynet::delete_isolates(g)
  }
  # A label for every node of a large network hides the network behind them,
  # so unless labelling was asked for outright, fall back to labelling the
  # nodes that stand out. Decided here rather than above so that the count
  # reflects the nodes actually drawn, once any isolates have been dropped.
  n <- as.numeric(manynet::net_nodes(g))
  # A concept lattice says for itself which of its nodes to label, whatever
  # its size: those at which a node of the original network first appears.
  # The rest are named only by their position, which is no help to a reader.
  introduces <- if (labels_missing && isTRUE(labels)) .concept_is_labelled(g)
  if (!is.null(introduces)) {
    labels <- manynet::node_names(g)[introduces]
    manynet::snet_info(
      "Labelling the {length(labels)} of {n} concepts at which a node of the",
      "original network first appears.",
      "Use {.code labels = TRUE} to label all of them.")
    if (!length(labels)) labels <- FALSE
  } else if (labels_missing && isTRUE(labels) && n > 30) {
    labels <- structure(5L, criterion = "degree", automatic = TRUE)
    n_lab <- sum(.infer_labels(g, labels))
    manynet::snet_info(
      "Labelling the {n_lab} most central of {n} nodes.",
      "Use {.code labels = TRUE} to label all of them,",
      "{.code labels = 25} to label more, or {.code labels = FALSE} for none.")
  }

  layout <- .infer_layout(g, layout)
  # Substituted here rather than in graph_layout(), since `layout` is also
  # passed to graph_edges(), graph_nodes() and graph_labels(), which would
  # otherwise style the plot for a layout that was not the one drawn.
  layout <- do.call(.check_layout_applies, c(list(g, layout), dots))
  if (missing(node_color) && missing(node_colour)) {
    node_color <- NULL
  } else if (missing(node_color)) {
    node_color <- .check_node_color(g, as.character(substitute(node_colour)),
                                    "node_colour")
  } else {
    node_color <- .check_node_color(g, as.character(substitute(node_color)))
  }
  if (missing(node_shape)) node_shape <- NULL else
    node_shape <- .check_node_shape(g, as.character(substitute(node_shape)))
  if (missing(node_size)) node_size <- NULL else if (!is.numeric(node_size)) {
    node_size <- .check_node_size(g, as.character(substitute(node_size)))
  }
  if (missing(node_group)) node_group <- NULL else {
    node_group <- .infer_node_group(g, substitute(node_group), parent.frame())
    if (!is.matrix(node_group)) {
      if (is.character(node_group) && length(node_group) == 1L) {
        node_group <- .check_node_group(g, node_group)
      } else {
        # A membership vector is held on the network, so that it is treated as
        # any other node attribute from here on.
        g <- manynet::mutate_nodes(g, .group = node_group)
        node_group <- ".group"
      }
      g <- manynet::mutate_nodes(g,
                                 node_group = .reduce_categories(g, node_group))
    }
  }
  if (missing(edge_color) && missing(edge_colour)) {
    edge_color <- NULL
  } else if (missing(edge_color)) {
    edge_color <- .check_edge_color(g, as.character(substitute(edge_colour)),
                                    "edge_colour")
  } else {
    edge_color <- .check_edge_color(g, as.character(substitute(edge_color)))
  }
  if (missing(edge_size)) edge_size <- NULL else if (!is.numeric(edge_size)) {
    edge_size <- .check_edge_size(g, as.character(substitute(edge_size)))
  }
  # After the isolates are dropped, so that the network read is the one drawn.
  # After the layout is settled too, since a concept lattice goes without
  # arrowheads only where the layout draws it as a Hasse diagram.
  manual <- all(c("x", "y") %in% names(dots))
  # A "lineage" ranked by values, such as years, is a timeline: a
  # historiograph, when the network is one of citations. See `.is_timeline()`.
  timeline <- !manual && .is_timeline(layout, dots)
  edge_arrows <- .infer_edge_arrows(
    g, .check_edge_arrows(edge_arrows),
    hasse = do.call(.is_hasse_layout, c(list(layout, manual), dots)))
  # Find the backbone ----
  # After the layout is settled, since a layout that carries meaning in its
  # coordinates keeps them and fades its ties only, and after the isolates are
  # dropped, so that the filter reads the network that is drawn.
  backbone <- .infer_backbone(g, .check_backbone(backbone), layout, edge_bundle,
                              manual = manual)
  # Add layout ----
  p <- do.call(graph_layout, c(list(g, layout, labels, node_group, layout_snap,
                                    backbone), dots))
  # Read where the layout left it, since the later steps have no use for it
  # and no reason to carry it. See `layout_scaling()`.
  fit <- attr(p[["data"]], "fit")
  # Add edges ----
  p <- graph_edges(p, g, edge_color, edge_size, node_size, edge_bundle, layout,
                   .shared, backbone, edge_arrows)
  # Add nodes ----
  p <- graph_nodes(p, g, node_color, node_shape, node_size, layout, .shared)
  # Add labels ----
  if (!isFALSE(labels) && manynet::is_labelled(g)) {
    p <- graph_labels(p, g, layout, label_place$gap, label_place$repel,
                      node_size = .drawn_nsize(g, node_size, layout),
                      labels = labels,
                      label_direction = label_place$direction,
                      timeline = timeline)
  }
  # Add the time axis ----
  # After the labels, which may set the x scale this gives its breaks to.
  if (timeline) p <- .add_time_axis(p, g, dots[["ranks"]] %||% dots[["rank"]])

  # Give the edge nodes room ----
  # After the labels, since a layered or lineage layout sets its own expansion
  # there and this widens that rather than replacing it.
  p <- .pad_for_nodes(p, .drawn_nsize(g, node_size, layout))

  # Note isolates ----
  if(isolates == "legend"){
    if (length(isos) > 3) label_text <- paste(c(utils::head(isos, 3),"..."), collapse = "\n") else 
      label_text <- paste(isos, collapse = "\n")
    p <- p + ggplot2::geom_point(aes(x=rep(0, manynet::net_nodes(g)), y=0, 
                                     alpha = "Isolates"), 
                                 size = 0) +
      ggplot2::scale_alpha_manual(name = "+ Isolates", 
                                  values = c("Isolates" = 0.5), 
                                  labels = label_text)
  } else if(isolates == "caption"){
    p <- .add_caption(p, paste("Isolates:", paste(isos, collapse = ", ")))
  }

  # Note the fit ----
  # A scaled layout draws distances that can be read, so how well two
  # dimensions hold those distances is part of the drawing rather than an
  # aside. See `check_stress()` for how to read the score.
  p <- .note_fit(p, fit)
  
  # Add legends ----
  p <- graph_legends(p, g, 
                     node_color, node_shape, node_size,
                     edge_color, edge_size)
  
  # assign("last.warning", NULL, envir = baseenv()) # to avoid persistent ggrepel
  p
}

# A scaled layout draws distances that can be read, so how well two dimensions
# hold what the layout scaled is part of the drawing rather than an aside.
# Each layout that reports a fit says so in its own terms. See
# `layout_scaling()` and `layout_correspondence()`.
.note_fit <- function(p, fit) {
  if (is.null(fit)) return(p)
  switch(fit[["type"]] %||% "scaling",
         scaling = .note_scaling_fit(p, fit),
         correspondence = .note_corresp_fit(p, fit),
         p)
}

.note_scaling_fit <- function(p, fit) {
  if (!is.finite(fit[["stress"]])) return(p)
  txt <- paste0("Stress: ", round(fit[["stress"]] * 100), "%.")
  if (!is.na(fit[["variance"]])) txt <- paste0(
    txt, " Two dimensions hold ", round(fit[["variance"]] * 100),
    "% of the distance variance.")
  p <- .add_caption(p, txt)
  # Kruskal read a stress of 20% as poor, but that figure was set for
  # psychometric data: most pairs of nodes in a network sit two or three
  # steps apart, which no plane holds well, so most networks would be
  # reported on at 20% and the message would say nothing.
  if (fit[["stress"]] > 0.3) manynet::snet_info(
    "Two dimensions hold these path distances poorly",
    "(stress: {round(fit[['stress']] * 100)}%),",
    "so read the clusters rather than the distances.",
    "See {.fn check_stress}.")
  p
}

# The share of inertia each dimension holds is already named on its axis, so
# nothing is added to the caption here. What the axes cannot say is which
# nodes those two dimensions place badly, and those are exactly the nodes a
# reader would otherwise read too much into.
.note_corresp_fit <- function(p, fit) {
  .note_corresp_inertia(fit)
  .note_corresp_cos2(fit)
  p
}

# The axes name the share of inertia, but a share means nothing without the
# number of dimensions it was won from, and an axis has no room for that. Two
# dimensions of a small table hold a good deal whatever the network, so the
# share is checked against what the same two dimensions would hold if the
# inertia were divided at random. See `.broken_stick()`.
.note_corresp_inertia <- function(fit) {
  drawn <- sum(fit[["inertia"]])
  k <- length(fit[["scree"]])
  if (!is.finite(drawn) || k < 3L) return(invisible(NULL))
  if (drawn > .broken_stick(k)) return(invisible(NULL))
  manynet::snet_info(
    "These two dimensions hold no more of the inertia than dividing it at",
    "random would give them ({round(drawn * 100)}% of {k} dimensions),",
    "so read the clusters rather than the positions.")
}

# The broken stick model: the share the first two of `k` dimensions would hold
# if the inertia were broken at random into `k` pieces. A far harder baseline
# than an even share, since inertia is never spread evenly, and the one worth
# warning against (Jackson 1993, \doi{10.2307/1939574}).
.broken_stick <- function(k) sum(vapply(1:2, function(i) mean(1 / (i:k)), 1))

.note_corresp_cos2 <- function(fit) {
  cos2 <- fit[["cos2"]]
  poor <- names(cos2)[!is.na(cos2) & cos2 < 0.3]
  # Only where more than one node is placed badly: a single one is as likely
  # to be a node with few ties as a sign that the drawing is not to be read.
  if (length(poor) < 2L) return(invisible(NULL))
  shown <- if (length(poor) > 5) c(utils::head(poor, 5), "...") else poor
  manynet::snet_info(
    "{length(poor)} nodes sit far off the plane drawn",
    "({.val {shown}}), so read their positions with care.")
}

# Helper functions for graphr() ----
.node_is_isolate <- function(g) {
  if (manynet::is_directed(g)) {
    in_degree <- igraph::degree(g, mode = "in")
    out_degree <- igraph::degree(g, mode = "out")
    isolates <- (in_degree == 0) & (out_degree == 0)
  } else {
    degree <- igraph::degree(g)
    isolates <- degree == 0
  }
  isolates
}

.infer_isolates <- function(g, isolates){
  # Keep isolates when there are none to remove, or when removing them
  # would empty the graph (e.g. tie-less motif networks)
  if(!any(.node_is_isolate(g)) || all(.node_is_isolate(g))) isolates <- "keep"
  isolates
}

.infer_layout <- function(g, layout) {
  if (is.null(layout)) {
    if(manynet::is_list(g))
      g <- g[[1]]
    # A spatial network's nodes already have their places, which say more
    # than any arrangement of the ties could.
    if (manynet::is_spatial(g)) {
      layout <- "spatial"
    } else if (manynet::net_nodes(g) <= 6) {
      layout <- "configuration"
    } else if (manynet::is_multilevel(g) && manynet::is_connected(g)) {
      # Checked before `is_twomode()`, which is also TRUE for these networks.
      # A "layered" layout would place each level along a single row, which
      # collapses the within-level ties that make the network multilevel.
      # Only where the network is connected, since the levels layout
      # orients its levels by the distances between them and so cannot place
      # components that have no distance to each other.
      layout <- "levels"
    } else if (manynet::is_twomode(g)) {
      layout <- "layered"
    } else if (manynet::is_directed(g) && manynet::is_acyclic(g)) {
      # A directed acyclic network ranks its nodes: every tie points from an
      # earlier layer to a later one. A force-directed layout throws that
      # away, so a parent can be drawn below its own child.
      layout <- "layered"
    } else layout <- "stress"
  }
  layout
}

# `node_group` names one node attribute, which can put each node in one group
# only. A node can belong to several groups at once, though, as it can to
# several cliques, and a single attribute cannot record that. A membership
# matrix can: one row for each node, one column for each group, and a one
# wherever the node belongs to the group. `netrics::node_x_clique()` returns
# such a matrix, and graph_layout() draws one hull for each of its columns,
# so that the hulls overlap where the groups do.

# Resolves what the user gave to `node_group` into either the name of a node
# attribute, as before, or a membership matrix. A call such as
# `node_x_clique()` is evaluated on the network being drawn, so that the user
# does not need to name the network twice.
.infer_node_group <- function(g, expr, env) {
  # A name or a string is a node attribute, as it has always been. Only where
  # it names no attribute is it evaluated, which is how a matrix held in a
  # variable reaches the branch below.
  if (is.character(expr) || is.name(expr)) {
    value <- as.character(expr)
    if (length(value) != 1L || value %in% igraph::vertex_attr_names(g))
      return(value)
    out <- tryCatch(eval(expr, env), error = function(e) NULL)
    # Nothing of that name to evaluate, so the mismatch is reported against
    # the node attributes. A single string is a node attribute name too,
    # whether it was written out or held in a variable.
    if (is.null(out)) return(value)
    if (is.character(out) && length(out) == 1L) return(out)
  } else out <- eval(.add_data_arg(expr, g, env), env)
  if (is.matrix(out) || is.array(out) || inherits(out, "data.frame"))
    return(.as_group_matrix(g, out))
  # A vector of memberships is returned as it is, for graphr() to hold on the
  # network and treat as any other node attribute.
  if (length(out) == as.numeric(manynet::net_nodes(g))) return(out)
  manynet::snet_abort(
    "{.arg node_group} should name a node attribute, or give a membership",
    "vector or matrix with one row for each of the {manynet::net_nodes(g)} nodes.")
}

# Adds the network as the `.data` argument of a call that does not give one,
# e.g. `node_x_clique()` or `node_x_clique(min_clique_size = 4)`. A call that
# names its own network, e.g. `node_x_clique(ison_adolescents)`, is left alone.
.add_data_arg <- function(expr, g, env) {
  if (!is.call(expr)) return(expr)
  fun <- tryCatch(eval(expr[[1L]], env), error = function(e) NULL)
  if (!is.function(fun) || !".data" %in% names(formals(fun))) return(expr)
  args <- as.list(expr)[-1]
  given <- names(args)
  if (".data" %in% given) return(expr)
  # An unnamed argument would be matched to `.data` positionally.
  if (length(args) && (is.null(given) || !all(nzchar(given)))) return(expr)
  expr[[".data"]] <- g
  expr
}

# Normalises a membership matrix onto the nodes of `g`: one row for each node,
# in the order the network holds them, and one named column for each group.
.as_group_matrix <- function(g, value) {
  if (inherits(value, "data.frame")) {
    ischr <- vapply(value, function(x) is.character(x) || is.factor(x),
                    logical(1))
    labels <- if (any(ischr)) as.character(value[[which(ischr)[1]]]) else NULL
    value <- as.matrix(value[!ischr])
    if (!is.null(labels)) rownames(value) <- labels
  } else value <- as.matrix(unclass(value))
  n <- as.numeric(manynet::net_nodes(g))
  # Isolates are dropped before this point, so a matrix calculated on the
  # network as the user holds it can have more rows than there are nodes to
  # draw. Node names say which rows those are.
  if (!is.null(rownames(value)) && manynet::is_labelled(g)) {
    nms <- manynet::node_names(g)
    if (all(nms %in% rownames(value))) value <- value[nms, , drop = FALSE]
  }
  if (nrow(value) != n)
    manynet::snet_abort(
      "{.arg node_group} was given a membership matrix with {nrow(value)} rows,",
      "but the network has {n} nodes.")
  if (is.null(colnames(value)))
    colnames(value) <- paste0("G", seq_len(ncol(value)))
  value <- value > 0
  # A group no node belongs to has no hull to draw.
  value <- value[, colSums(value) > 0, drop = FALSE]
  if (ncol(value) == 0)
    manynet::snet_abort("{.arg node_group} was given no groups to draw.")
  if (any(colSums(value) <= 2))
    manynet::snet_info(
      "Groups of two nodes or fewer can be difficult to draw a hull around,",
      "so this plot may look uneven.")
  value
}

.reduce_categories <- function(g, node_group) {
  limit <- toCondense <- NULL
  if (sum(table(manynet::node_attribute(g, node_group)) <= 2) > 2 &
      length(unique(manynet::node_attribute(g, node_group))) > 2) {
    toCondense <- names(which(table(manynet::node_attribute(g, node_group)) <= 2))
    out <- ifelse(manynet::node_attribute(g, node_group) %in% toCondense,
                  "Other", manynet::node_attribute(g, node_group))
    .inform_groups_reduced(toCondense)
  } else if (sum(table(manynet::node_attribute(g, node_group)) <= 2) == 2 &
             length(unique(manynet::node_attribute(g, node_group))) > 2) {
    limit <- stats::reorder(manynet::node_attribute(g, node_group),
                            manynet::node_attribute(g, node_group),
                            FUN = length, decreasing = TRUE)
    if (sum(utils::tail(attr(limit, "scores"), 2))) {
      toCondense <- utils::tail(levels(limit), 3)
    } else {
      toCondense <- utils::tail(levels(limit), 2)
    }
    out <- ifelse(manynet::node_attribute(g, node_group) %in% toCondense, "Other",
                  manynet::node_attribute(g, node_group))
    .inform_groups_reduced(toCondense)
  } else if (sum(table(manynet::node_attribute(g, node_group)) <= 2) == 1 &
             length(unique(manynet::node_attribute(g, node_group))) > 2) {
    limit <- stats::reorder(manynet::node_attribute(g, node_group),
                            manynet::node_attribute(g, node_group),
                            FUN = length, decreasing = TRUE)
    toCondense <- utils::tail(levels(limit), 2)
    out <- ifelse(manynet::node_attribute(g, node_group) %in% toCondense, "Other",
                  manynet::node_attribute(g, node_group))
    .inform_groups_reduced(toCondense)
  } else if (sum(table(manynet::node_attribute(g, node_group)) <= 2) == 1 &
             length(unique(manynet::node_attribute(g, node_group))) == 2) {
    out <- as.factor(manynet::node_attribute(g, node_group))
    manynet::snet_info(
      "Groups of two nodes or fewer can be difficult to draw a hull around,",
      "so this plot may look uneven.")
  } else out <- as.factor(manynet::node_attribute(g, node_group))
  out
}

# Groups too small to draw a hull around are folded into an "Other" group.
# Said in one place so the three branches above cannot drift apart.
.inform_groups_reduced <- function(condensed) {
  manynet::snet_info(
    "Grouped {.val {condensed}} together as {.val Other},",
    "since {?it holds/they hold} two nodes or fewer,",
    "which is too few to draw a group around.")
}

Try the autograph package in your browser

Any scripts or data that you put into this service are public.

autograph documentation built on Nov. 16, 2026, 5:08 p.m.