Sub-hypergraph by hyperedges, nodes or hyperedge attributes

Keeps part of a hypergraph and returns it as a net_hg with the same incidence weights, edge metadata and multiplicities. Three selectors combine by intersection. edges names the hyperedges to keep. nodes keeps the hyperedges whose members all lie in the set, the induced sub-hypergraph of HypergraphX. where keeps the hyperedges whose attributes take given values, so where = c(citing = "153-001") on a citation-block hypergraph is the hypergraph of one citing decision (Coupette et al. 2024, Figure 3).

Usage

hg_subset(
  hg,
  edges = NULL,
  nodes = NULL,
  where = NULL,
  size = NULL,
  component = c("all", "largest"),
  drop_isolated = TRUE
)

Arguments

hg: A net_hg (from group_hypergraph(), hg_snapshot(), text_hypergraph(), ...).
edges: Hyperedge names to keep: a character vector, or a data.frame with an edge column such as the table hg_edge_centrality() or hg_edges() returns, so a ranking can be passed straight through.
nodes: Character vector of node names. Only hyperedges contained in this set are kept, and the node set of the result is exactly nodes.
where: Hyperedge attribute values to keep: a named vector or list, one element per attribute column of the edge metadata (the columns temporal_hypergraph() keeps because they are constant within a hyperedge), each holding the value or values to keep.
size: Hyperedge sizes to keep, as a vector of member counts (distinct members): size = 3 keeps the hyperedges with exactly three members, the 3-uniform hypergraph that hg_motifs() needs.
component: "all" (default) keeps every connected component; "largest" keeps only the largest connected component, in which two nodes are connected when a chain of shared hyperedges joins them. Spectral clustering and label spreading need a connected hypergraph (Hayashi et al. 2020), and a corpus of short texts often holds a few texts that share no word with the rest. Applied after the other filters.
drop_isolated: Drop nodes that belong to no retained hyperedge? Default TRUE. Ignored when nodes is given.

Value

A net_hg whose incidence matrix is the selected sub-matrix of the input, sparse if the input is sparse. Edge metadata (edge_data), duplicate multiplicities (edge_multiplicity) and the window counts of a window_hypergraph() are subset alongside. The nodes the subset removes are recorded in params$subset$removed, and the labels of removed nodes are set aside with a hypergraphs_dropped_documents warning by hg_classify(), hg_keywords() and the other verbs that take labels, so the table that built the hypergraph can be passed back whole.

References

Coupette, C., Hartung, D., & Katz, D. M. (2024). Legal hypergraphs. Philosophical Transactions of the Royal Society A, 382(2270), 20230141. doi:10.1098/rsta.2023.0141

Hayashi, K., Aksoy, S. G., Park, C. H., & Park, H. (2020). Hypergraph random walks, Laplacians, and clustering. Proceedings of CIKM 2020, 495-504. doi:10.1145/3340531.3412034

Examples

dat <- data.frame(
  member = c("a", "b", "c", "b", "c", "d", "d", "e"),
  event = c("e1", "e1", "e1", "e2", "e2", "e2", "e3", "e3"),
  kind = c("x", "x", "x", "x", "x", "x", "y", "y")
)
hg <- group_hypergraph(dat, node = "member", hyperedge = "event")
hg_subset(hg, edges = c("e1", "e2"))
#> Hypergraph: 4 nodes, 2 hyperedges (sizes 3: 2)
#> Source: group membership (node = member, hyperedge = event)
#>  hyperedge size members
#>         e1    3 a, b, c
#>         e2    3 b, c, d
hg_subset(hg, nodes = c("b", "c", "d", "e"))
#> Hypergraph: 4 nodes, 2 hyperedges (sizes 2: 1, 3: 1)
#> Source: group membership (node = member, hyperedge = event)
#>  hyperedge size members
#>         e2    3 b, c, d
#>         e3    2    d, e
hg_subset(hg, where = c(kind = "y"))
#> Hypergraph: 2 nodes, 1 hyperedges (sizes 2: 1)
#> Source: group membership (node = member, hyperedge = event)
#>  hyperedge size members
#>         e3    2    d, e
hg_subset(hg, edges = c("e1", "e3"), component = "largest")
#> Hypergraph: 3 nodes, 1 hyperedges (sizes 3: 1)
#> Source: group membership (node = member, hyperedge = event)
#>  hyperedge size members
#>         e1    3 a, b, c