5  Reference

API documentation

Compact reference for every exported function. Conventions:

6 Connected components

6.1 find_connected_components

find_connected_components(edges, n_nodes = NULL, compress = TRUE)

All connected components for a dense, small-integer node space.

Argument Description
edges Two-column edge list.
n_nodes Total node count. If NULL, inferred as max(edges). Set it to include isolated nodes or to skip the max scan.
compress TRUE: tidy ids 1..k. FALSE: raw Union–Find root labels.

Returns a list: components (component id per node, length n_nodes), component_sizes (size of each component), n_components (count).

Notes — errors if node ids exceed the 32-bit integer limit or if the implied allocation would exceed 32 GB; warns above ~8 GB. For sparse/huge ids use find_connected_components_safe().

cc <- find_connected_components(matrix(c(1,2, 2,3, 5,6), ncol = 2, byrow = TRUE))
cc$n_components   # 2

6.2 find_connected_components_safe

find_connected_components_safe(edges, compress = TRUE, verbose = TRUE)

Same result, but remaps node ids to a dense 1..(unique nodes) space with fastmatch first — safe and memory-efficient for sparse or large ids.

Argument Description
edges Two-column edge list (kept numeric to tolerate large ids).
compress As above.
verbose Print a memory analysis. Default TRUE.

Returns components (named by original node ids), component_sizes, n_components, node_mapping (original ↔︎ mapped), and memory_info (naive_memory_gb, efficient_memory_gb, memory_saved_gb).

6.3 find_connected_components_large(edges, compress = TRUE, verbose = FALSE)

For node ids beyond the 32-bit integer range. Ids are held as doubles and remapped to consecutive integers internally.

Returns components (named by original ids), component_sizes, n_components, and (when remapping occurs) node_mapping.

7 Per-edge components

7.1 get_edge_components

get_edge_components(edges, n_nodes = NULL, compress = TRUE, return_type = "list")

Component assignment for each edge rather than each node.

Argument Description
return_type "list": from_components, to_components, n_components. "combined": just the from_components vector.

For a genuine edge, from and to are always in the same component, so the combined vector is the natural “component id per row”.

7.2 group_edges(edges, n_nodes = NULL, compress = TRUE)

Convenience alias returning one component id per edge row (get_edge_components(..., return_type = "combined")).

group_edges(matrix(c(1,2, 2,3, 5,6), ncol = 2, byrow = TRUE))   # 1 1 2

7.3 edge_components

edge_components(dt, from_col, to_col, compress = TRUE)

Same as group_edges() but takes a data.table/data.frame and column names — designed for inline data.table use.

dt[, component := edge_components(.SD, "from", "to")]

7.4 add_component_column

add_component_column(dt, from_col = "from", to_col = "to", component_col = "component", n_nodes = NULL, compress = TRUE, in_place = TRUE, verbose = FALSE)

Add a component column to a data.table. Node ids are mapped with fastmatch.

Argument Description
from_col, to_col Edge endpoint columns.
component_col Name of the new column.
in_place TRUE: modify dt by reference. FALSE: return a modified copy.
verbose Print per-step timing.

Returns the data.table (invisibly when in_place = TRUE).

8 Connectivity, distance, statistics

8.1 are_connected

are_connected(edges, query_pairs, n_nodes = NULL)

Are the two nodes in each pair in the same component? Builds Union–Find once.

Returns a logical vector, one element per query pair.

are_connected(edges, matrix(c(1,3, 1,5), ncol = 2, byrow = TRUE))   # TRUE FALSE

8.2 shortest_paths

shortest_paths(edges, query_pairs, n_nodes = NULL, max_distance = -1)

Unweighted shortest hop distance per query pair, via BFS.

Argument Description
max_distance Stop searching beyond this depth; farther pairs return -1. -1 (default) = no limit.

Returns an integer vector; 0 for identical source/target, -1 if no path (or beyond max_distance).

8.3 graph_statistics

graph_statistics(edges, n_nodes = NULL)

Single-pass degree and density summary; no adjacency matrix.

Returns n_edges, n_nodes, density, and degree_stats (min, max, mean).

9 Entity resolution / grouping

9.1 group_id

group_id(data, cols = NULL, use_regex = TRUE, incomparables = c("", "NA", "Unknown"), case_sensitive = TRUE, min_group_size = 1, return_details = FALSE, verbose = FALSE)

Group rows that share any value across the chosen columns (Union–Find over rows).

Argument Description
data A data.frame/data.table, or a list of equal-length columns.
cols Column names, or regex patterns when use_regex = TRUE. NULL uses all columns.
use_regex Treat cols as regex patterns matched against column names.
incomparables Values that never link rows (empty, "NA", etc.).
case_sensitive Case-sensitive string comparison.
min_group_size Groups smaller than this get id 0.
return_details Return a rich group_id_result object instead of a bare vector.
verbose Print timing/progress.

Returns an integer vector of group ids (one per row); or, with return_details = TRUE, a group_id_result list with group_ids, n_groups, group_sizes, and value_map (which shared values formed each group).

Note — an all-numeric, no-incomparables, case-sensitive call dispatches to a specialised fast numeric path automatically.

9.2 print(x, ...) for group_id_result

S3 print method summarising counts, settings, the first group ids, and the shared values that created groups.

9.3 add_group_ids

add_group_ids(dt, cols, group_col = "group_id", use_regex = TRUE, ...)

data.table wrapper for group_id() — adds the group column by reference. Extra ... are passed through to group_id().

Returns dt (invisibly).

9.4 set_group_id

set_group_id(dt, cols = "phone", var_output_name = "gid", incomparables = c(NA, ""), isolate = NULL, return_edges = FALSE)

Alternative grouping engine using the bipartite edge reduction (melt → edges → edge_components).

Argument Description
dt A data.table that must contain an id column.
cols Regex matched against column names to choose the value columns. Ignored when isolate is given.
var_output_name Name of the group-id column to add.
incomparables Values excluded from linking.
isolate Optional list of column-name vectors. Each set gets its own value namespace, so identical text only links rows within the same set (e.g. a phone number in an email column won’t link to the phone columns). The value columns are the union of all sets.
return_edges TRUE returns the record-to-record edge list of all pair connections (from, to, shared value) instead of dt. The group column is still added to dt by reference — handy for plotting the linkage with visNetwork.

Returns dt (modified by reference with the new group column); or, when return_edges = TRUE, a data.table edge list with columns from, to (from < to) and value.

9.5 See also

  • Theory — how these algorithms work and why they are fast.
  • Examples — runnable demonstrations of every function.
  • Benchmarks — scaling against igraph, network, sna.