vis.connectome: Visualize a connectivity matrix as a connectome on a brain...
In fsbrain: Managing and Visualizing Brain Surface Data

vis.connectome

R Documentation

Visualize a connectivity matrix as a connectome on a brain surface.

Description

Draws the edges of a connectivity matrix as lines between region centroids, the nodes as spheres, and (optionally) a semi-transparent brain surface as context. This is the fsbrain equivalent of the plot_connectome function of the Python package yabplot. It can be used for any brain connectome, e.g., structural connectivity (tractography), functional connectivity (correlation), or any other square matrix that describes a relation between brain regions.

Note that this is a visualization function: it does not compute a connectivity matrix, and it does not check whether the data is a valid connectivity estimate.

Usage

vis.connectome(
  connectivity_matrix,
  node_coords = NULL,
  node_names = NULL,
  subjects_dir = NULL,
  template_id = "fs_LR_32",
  atlas = NULL,
  context = list(surface = "midthickness", alpha = 0.08, color = "#B0B0B0"),
  edge_threshold = NULL,
  edge_threshold_quantile = 0.95,
  edge_absolute = TRUE,
  edge_negative = FALSE,
  edge_width = 1,
  edge_width_range = c(0.5, 3),
  edge_scale = c("weight", "none"),
  edge_color = NULL,
  edge_makecmap_options = modifyList(mkco.div(), list(symm = FALSE)),
  node_radius = 2,
  node_radius_range = NULL,
  node_scale = c("none", "strength"),
  node_color = NULL,
  node_makecmap_options = mkco.seq(),
  views = c("sd_lateral_lh", "sd_medial_lh", "sd_lateral_rh", "sd_medial_rh"),
  rgloptions = rglo(),
  rglactions = list(),
  style = "default",
  draw_colorbar = FALSE,
  silent = FALSE
)

Arguments

`connectivity_matrix`	numeric square matrix, the connectivity matrix. The rows and columns are the nodes (brain regions). The names of the rows/columns (or the parameter `node_names`) define the nodes, see the parameter `node_coords`. Alternatively, an edge list as a data.frame with the columns 'source', 'target' and 'weight'.
`node_coords`	(n, 3) numeric matrix, the coordinates of the nodes (brain regions), in the same order as the matrix rows. If `NULL`, the nodes are looked up by name in the atlas given in parameter `atlas`, see the parameter `subjects_dir` and the function `subject.region.centroids`. The row names of the matrix (or the parameter `node_names`) must then match the atlas region names.
`node_names`	vector of character strings, the node names. Only used if `node_coords` is given and the matrix has no row names. Defaults to NULL.
`subjects_dir`	character string or NULL. The FreeSurfer `SUBJECTS_DIR`, see `subject.region.centroids`. Defaults to NULL, which searches the standard locations for the template subject `template_id`.
`template_id`	character string, the identifier of the template (or subject) whose atlas and surface define the nodes and the context surface. Defaults to 'fs_LR_32'. Ignored if `node_coords` is given and `context` is NULL.
`atlas`	character string or NULL, the atlas whose regions are the nodes, e.g., 'schaefer400'. Not required if `node_coords` is given.
`context`	named list or NULL, the semi-transparent brain surface drawn behind the connectome. The list can have the entries: 'surface' (character string, the surface to use, defaults to 'midthickness'), 'alpha' (numeric, the transparency of the surface, defaults to 0.08), and 'color' (character string, the color of the surface, defaults to '#B0B0B0'). Set to NULL to draw the connectome without any brain surface, which is much faster and gives a 'spring layout' style figure (the camera then frames the nodes).
`edge_threshold`	numeric or NULL, an absolute threshold on the edge weight. Edges with a lower magnitude are not drawn. Defaults to NULL (no absolute threshold).
`edge_threshold_quantile`	numeric or NULL, a quantile (in the range 0 to 1) of the edge magnitudes. Only edges with a magnitude above that quantile are drawn, i.e., the quantile selects the strongest edges. Defaults to 0.95, i.e., the strongest 5 percent of the edges are drawn. Set to NULL to use all edges.
`edge_absolute`	logical, whether the magnitude of the edge weights is used for thresholding and for the line widths. Defaults to TRUE, i.e., a strong negative edge is drawn like a strong positive one (but see the parameter `edge_negative`).
`edge_negative`	logical, whether to draw the negative edges instead of the positive ones. Defaults to FALSE, i.e., only positive edges are considered. To show both the positive and the negative edges of a signed matrix in one figure, call this function twice and combine the results (the second call can be rendered on top of the first).
`edge_width`	positive number, the line width in pixels. Defaults to 1.0 (a thin line, which is what hardware line rendering supports best).
`edge_width_range`	numeric vector of length 2 or NULL, the range of the line widths used when `edge_scale` is 'weight'. Defaults to c(0.5, 3.0).
`edge_scale`	character string, one of 'weight' (the line width encodes the edge weight) or 'none' (all edges have the width `edge_width`). Defaults to 'weight'.
`edge_color`	vector of hex color strings or NULL. A single color for all edges, or one color per edge. If NULL (the default), the edges are colored by their weight, using the colormap defined by `edge_makecmap_options`.
`edge_makecmap_options`	named list of parameters to pass to `makecmap`, see `mkco.div`. Used to color the edges by weight and to draw the colorbar. Defaults to a diverging colormap which spans the weights of the drawn edges (note the 'symm' setting: only one sign of edges is drawn per call, so a symmetric range would waste half of the colormap).
`node_radius`	positive number, the radius of the node spheres, in the units of the surface coordinates (millimeters). Defaults to 2.0.
`node_radius_range`	numeric vector of length 2 or NULL, the range of the node radii used when `node_scale` is 'strength'. Defaults to NULL, which uses 0.5 and 1.5 times `node_radius`.
`node_scale`	character string, one of 'none' (all nodes have the radius `node_radius`) or 'strength' (the node radius encodes the node strength, i.e., the sum of the absolute weights of all its edges). Defaults to 'none'.
`node_color`	vector of hex color strings or NULL. A single color for all nodes, or one color per node. If NULL (the default), the nodes are colored by their strength (see `node_scale`), using the colormap defined by `node_makecmap_options`.
`node_makecmap_options`	named list of parameters to pass to `makecmap`, see `mkco.seq`. Used to color the nodes by strength and to draw the colorbar. Defaults to `mkco.seq()`.
`views`	vector of character strings, the views to render, see `get.view.angle.names`. Defaults to the 4 standard views.
`rgloptions`	option list passed to `par3d`, see `rglo`.
`rglactions`	named list. A list in which the names are from a set of pre-defined actions, see `rglactions`.
`style`	a rendering style for the surface meshes, see `get.rglstyle`. Note that the style of the context surface and of the nodes is not affected by this, only the style requested for the edges (which is of little relevance, as lines are drawn unlit by default).
`draw_colorbar`	logical or one of the character strings 'vertical' or 'horizontal', whether to draw a colorbar for the edges. Defaults to FALSE. Note that a colorbar is only drawn for the edges, not for the nodes: if you want to draw a colorbar for the node strengths, use `coloredmesh.plot.colorbar.separate` on the nodes (the entry 'nodes' of the return value). Also note that the headless scimesh renderer backend does not support colorbars in this function, use `export` instead (see the return value).
`silent`	logical, whether to suppress the status messages. Defaults to FALSE.

Value

named list of renderables, invisibly: the entries 'edges' (an fs.coloredpaths instance), 'nodes' (an fs.coloredmesh instance) and 'context_lh'/'context_rh' (the context surface, if requested). This list can be passed to export to create a publication quality figure with a colorbar, which is also the recommended way to use the scimesh renderer backend.

Examples

## Not run: 
  # Use the fs_LR_32 template (see subject.region.centroids for the download commands).
  centroids = subject.region.centroids(subjects_dir = NULL, subject_id = "fs_LR_32",
    atlas = "schaefer400", surface = "midthickness");
  set.seed(42);
  mat = matrix(runif(nrow(centroids)^2), nrow = nrow(centroids),
    dimnames = list(rownames(centroids), rownames(centroids)));
  mat = (mat + t(mat)) / 2;
  diag(mat) = 0;

  # Render the connectome in 3 views:
  cm = vis.connectome(mat, atlas = "schaefer400",
    views = c("sd_lateral_lh", "sd_dorsal", "sd_caudal"));

  # Or create a publication quality image with a colorbar for the edges:
  export(cm, draw_colorbar = "horizontal",
    output_img = "connectome.png", colorbar_legend = "Edge weight");

## End(Not run)

fsbrain documentation built on Sept. 27, 2026, 1:07 a.m.