Package {graphvec}

Version:	0.1.0
Title:	Vectorised Graph Data Structures
Description:	Extends vectors to include graph relationships between their elements, and offers tools to compute useful summaries of the graph structure for use in summarising, filtering, and otherwise manipulating the graph. Node identity is positional rather than value-based, so isolated nodes and repeated values are represented without special handling. Three complementary data structures are provided, each an ordinary vector that stays a column in a data frame and slices consistently with it: 'node_vec' is vectorised along the nodes of a graph, 'edge_vec' is vectorised along its edges, and 'agg_vec' (with the tabular 'agg_df') represents the aggregation structure common in data analysis, such as a total row over a set of categories. This makes graph relationships a native part of tidy rectangular data analysis workflows, alongside tools such as those in 'dplyr'. Each of these can also be converted to 'igraph' objects for further analysis.
License:	MIT + file LICENSE
Imports:	tibble
Suggests:	crayon, dplyr, igraph, pillar, testthat (≥ 3.0.0)
Config/testthat/edition:	3
Encoding:	UTF-8
Config/roxygen2/version:	8.0.0
URL:	https://pkg.mitchelloharawild.com/graphvec/, https://github.com/mitchelloharawild/graphvec
BugReports:	https://github.com/mitchelloharawild/graphvec/issues
NeedsCompilation:	no
Packaged:	2026-08-20 13:54:47 UTC; mitchell
Author:	Mitchell O'Hara-Wild [aut, cre]
Maintainer:	Mitchell O'Hara-Wild <mail@mitchelloharawild.com>
Repository:	CRAN
Date/Publication:	2026-09-03 12:40:02 UTC

graphvec: Vectorised graph data structures

Description

Extends vectors to include graph relationships between their elements, and offers tools to compute useful summaries of the graph structure for use in summarising, filtering, and otherwise manipulating the graph.

Author(s)

Maintainer: Mitchell O'Hara-Wild mail@mitchelloharawild.com (ORCID)

Authors:

• Mitchell O'Hara-Wild mail@mitchelloharawild.com (ORCID)

See Also

Useful links:

• https://pkg.mitchelloharawild.com/graphvec/

• https://github.com/mitchelloharawild/graphvec

• Report bugs at https://github.com/mitchelloharawild/graphvec/issues

Subset an edge_vec

Description

Slicing an edge_vec selects edges directly: dropping or reordering edges never invalidates a node reference, so nodes/directed are unaffected – unlike slicing a node_vec(), no remap is needed.

Usage

## S3 method for class 'edge_vec'
x[i, ...]

Arguments

Value

An edge_vec containing only the selected edges.

Examples

g <- edge_vec(
  from = c(1L, 2L, 1L, 3L),
  to = c(2L, 3L, 3L, 1L),
  nodes = data.frame(label = c("A", "B", "C"))
)
g[1:2]

Subset a node_vec

Description

Slicing a node_vec is an induced subgraph: edges that lose an endpoint are dropped, surviving edges are remapped to the new positions, and replicated nodes (e.g. x[c(1, 1, 2)]) clone the edges incident to the original.

Usage

## S3 method for class 'node_vec'
x[i, ...]

Arguments

Value

A node_vec containing only the selected nodes, with edges restricted to the induced subgraph.

Examples

g <- node_vec(
  x = c("A", "B", "C"),
  from = c(1L, 2L),
  to = c(2L, 3L)
)
g[1:2]

Create an aggregation table

Description

An agg_df is a table of agg_vec() columns, one row per level of a (possibly crossed) aggregation structure – e.g. Purpose and State columns where some rows total one dimension, some the other, some both. nodes()/edges() reorient it into a graph: a row is a child of another row whenever the parent aggregates exactly one more column and matches on every other column's disaggregated value.

Usage

agg_df(...)

Arguments

Value

An agg_df object.

Examples

agg_df(
  Purpose = agg_vec(c(NA, "Business", "Holiday"), c(TRUE, FALSE, FALSE)),
  State = agg_vec(c("NSW", NA, NA), c(FALSE, TRUE, TRUE))
)

Create an aggregation vector

Description

An aggregation vector is a special type of node_vec() consisting of a single parent (the 'aggregated' value) and its children. Aggregated values are identified by a logical vector passed to the aggregated argument, and disaggregated values are provided in x. Aggregated values are displayed as ⁠<aggregated>⁠ by default.

Usage

agg_vec(x = character(), aggregated = logical(NROW(x)))

Arguments

Value

An agg_vec object.

Examples

agg_vec(
  x = c(NA, "A", "B"),
  aggregated = c(TRUE, FALSE, FALSE)
)

Convert a graph vector to an igraph object

Description

Methods for converting node_vec, agg_vec, agg_df, and edge_vec objects to igraph::igraph() objects using igraph::graph_from_edgelist().

Usage

## S3 method for class 'agg_vec'
as.igraph(x, ...)

## S3 method for class 'agg_df'
as.igraph(x, ...)

## S3 method for class 'node_vec'
as.igraph(x, ...)

## S3 method for class 'edge_vec'
as.igraph(x, ...)

Arguments

Value

An igraph::igraph() object.

See Also

node_vec(), agg_vec(), agg_df(), edge_vec()

Examples

if (requireNamespace("igraph", quietly = TRUE)) {
  g <- node_vec(
    x = c("A", "B", "C"),
    from = c(1L, 2L),
    to = c(2L, 3L)
  )
  igraph::as.igraph(g)
}

Graph vector along edges

Description

An edge_vec is a vector of graph edges with associated node data stored as attributes.

Usage

edge_vec(
  from = integer(),
  to = integer(),
  ...,
  nodes = data.frame(),
  directed = TRUE
)

Arguments

Value

An edge_vec object.

Examples

g <- edge_vec(
  from = c(1L, 2L, 1L, 3L),
  to = c(2L, 3L, 3L, 1L),
  weight = c(1, 2, 5, 3),
  nodes = data.frame(
    id = 1:3,
    label = c("A", "B", "C")
  )
)

# Access node data via `$`
g$from$label
g$to$label

# Access an edge attribute via `$`
g$weight

Is the element an aggregation of smaller data

Description

Is the element an aggregation of smaller data

Usage

is_aggregated(x)

Arguments

Value

A logical vector indicating which elements are aggregated.

See Also

agg_vec()

Examples

v <- agg_vec(c(NA, "A", "B"), c(TRUE, FALSE, FALSE))
is_aggregated(v)

Constructor function for edge_vec

Description

Constructor function for edge_vec

Usage

new_edge_vec(
  from = integer(),
  to = integer(),
  ...,
  nodes = data.frame(),
  directed = TRUE
)

Arguments

Value

An edge_vec object.

Examples

new_edge_vec(
  from = c(1L, 2L),
  to = c(2L, 3L),
  nodes = data.frame(label = c("A", "B", "C"))
)

Constructor function for node_vec

Description

Constructor function for node_vec

Usage

new_node_vec(
  x = list(),
  edges = data.frame(from = integer(), to = integer()),
  directed = TRUE
)

Arguments

Value

A node_vec object.

Examples

new_node_vec(
  x = c("A", "B", "C"),
  edges = data.frame(from = c(1L, 2L), to = c(2L, 3L))
)

Graph vector along nodes

Description

A node_vec is a vector of graph nodes with associated edges stored as attributes.

Usage

node_vec(x = list(), from = integer(), to = integer(), ..., directed = TRUE)

Arguments

Value

A node_vec object.

Examples

g <- node_vec(
 x = factor(c("A", "B", "C")),
 from = c(1L, 2L, 1L),
 to = c(2L, 3L, 1L),
 weight = c(1, 2, 5)
)
g

if (requireNamespace("igraph", quietly = TRUE)) {
  igraph::as.igraph(g)
}

Reorient a graph vector

Description

nodes() and edges() return the same underlying graph, enumerated along the node or edge axis respectively, regardless of which orientation x started in. Both directions are lossless and involutive: node attributes, isolated nodes, and directed all survive, because both orientations carry the same logical graph — reorientation only changes which table the result is indexed by.

Usage

## S3 method for class 'agg_df'
nodes(x, ...)

## S3 method for class 'agg_df'
edges(x, ...)

## S3 method for class 'agg_vec'
nodes(x, ...)

## S3 method for class 'agg_vec'
edges(x, ...)

## S3 method for class 'edge_vec'
edges(x, ...)

## S3 method for class 'edge_vec'
nodes(x, ...)

## S3 method for class 'node_vec'
nodes(x, ...)

## S3 method for class 'node_vec'
edges(x, ...)

nodes(x, ...)

edges(x, ...)

Arguments

Value

nodes() returns a node_vec. edges() returns an edge_vec.

Examples

g <- node_vec(
  x = c("A", "B", "C"),
  from = c(1L, 2L),
  to = c(2L, 3L)
)
edges(g)
nodes(edges(g))