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 ORCID iD [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

logo

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:

See Also

Useful links:

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

x

An edge_vec.

i

Indices to select, as for `[`.

...

Passed on.

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

x

A node_vec.

i

Indices to select, as for `[`.

...

Passed on.

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

...

Named agg_vec columns, all the same length.

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

x

The vector of values.

aggregated

A logical vector to identify which values are ⁠<aggregated>⁠.

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

x

A node_vec, agg_vec, agg_df, or edge_vec object.

...

Additional arguments (currently unused).

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

from

Integer vector of 'from' node indices. Hyperedges (multiple 'from' nodes per edge) are not yet supported.

to

Integer vector of 'to' node indices.

...

Named edge attribute vectors (e.g. weight = c(1, 2, 5)), recycled to the number of edges. from and to are reserved and cannot be used as attribute names. Attribute columns are stored on the edge table itself, so they slice, replicate, and reorient with the edges they belong to (see nodes()/edges()).

nodes

Vector of node data (any vector, including a data frame of node attributes). Its size should be at least the maximum value in from and to.

directed

A single logical value: is incidence ordered (from -> to) or symmetric?

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

x

An object.

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

from

Integer vector of 'from' node indices.

to

Integer vector of 'to' node indices.

...

Named edge attribute fields, already recycled to the number of edges.

nodes

Vector of node data (any vector, including a data frame of node attributes).

directed

A single logical value: is incidence ordered (from -> to) or symmetric?

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

x

A vector representing the nodes in the graph.

edges

A data frame with columns from and to representing the edges

directed

A single logical value: is incidence ordered (from -> to) or symmetric?

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

x

A vector representing the nodes in the graph.

from

Integer vector of 'from' node positions into x. Hyperedges (multiple 'from' nodes per edge) are not yet supported.

to

Integer vector of 'to' node positions into x.

...

Named edge attribute vectors (e.g. weight = c(1, 2, 5)), recycled to the number of edges. from and to are reserved and cannot be used as attribute names. Attribute columns are stored on the edge table itself, so they slice, replicate, and reorient with the edges they belong to (see nodes()/edges()).

directed

A single logical value: is incidence ordered (from -> to) or symmetric?

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

x

A node_vec or edge_vec.

...

Passed on to methods.

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))