Package 'hypergraphs'

Description

Repairs and strips the non-content a bibliographic or web export leaves in a text: HTML tags and entities, mojibake and typographic characters, bracketed citation numbers and list or section numbering, URLs and DOIs, trailing copyright notices, bare numbers, and optionally stop words. Each step is a switch. The result has the same length (or the same rows) as the input; a text that falls below min_content becomes the empty string, which text_hypergraph() then drops with a hypergraphs_dropped_documents warning, so nothing leaves the corpus silently.

Usage

clean_text(
  x,
  column = NULL,
  html = TRUE,
  encoding = TRUE,
  citations = TRUE,
  urls = TRUE,
  copyright = TRUE,
  copyright_max = 300L,
  boilerplate = FALSE,
  numbers = TRUE,
  remove = NULL,
  stop_words = NULL,
  min_chars = 0L,
  min_content = 0
)

Arguments

Value

x with the text cleaned: a character vector of the same length (names kept), or the same data.frame with column replaced. NA and low-content texts become "". Raises hypergraphs_bad_input for a malformed x, column or switch.

References

Manning, C. D., Raghavan, P., & Schütze, H. (2008). Introduction to Information Retrieval. Cambridge University Press. doi:10.1017/CBO9780511809071

Examples

messy <- c(
  "1. The programme raised attainment in 2020, see section 3.2.1.",
  "Peer&nbsp;support <b>improved</b> outcomes [12] across schools.",
  "Full report at https://example.org/study.pdf and doi:10.1/x.",
  "Students' views shifted. (c) 2021 Informa UK Limited.",
  "(3) OJ No L 297, 24.11.1979, p. 1."
)
clean_text(messy)
clean_text(messy, min_content = 0.5)
clean_text(c("[No abstract available]", "A real abstract."),
           remove = "no abstract available")

Description

A deterministic stratified sample of 165 abstracts (up to 40 per year, 2020–2024) from a Scopus export of COVID-19 education research, the same source corpus used by the sbert package's topic-modeling articles. Rebuilt by data-raw/covid_abstracts.R.

Usage

covid_abstracts

Format

A data frame with 165 rows and 4 columns:

doc

Scopus EID, the unique document identifier.

title

Article title.

abstract

Abstract text (each at least 400 characters).

year

Publication year (integer, 2020–2024).

Source

Scopus export of COVID-19 education research, 2020–2024.

Examples

hg <- text_hypergraph(covid_abstracts, column = "abstract", id = "doc")
hg

Description

Sentence embeddings of covid_abstracts' abstract texts, computed with the sbert package's pinned all-MiniLM-L6-v2 model (L2-normalized rows). Bundled so that text_hypergraph(construction = "knn") runs offline; rebuilt by data-raw/covid_embeddings.R.

Usage

covid_embeddings

Format

A numeric matrix with 165 rows (rownames = covid_abstracts$doc) and 384 columns.

Source

Computed from covid_abstracts with sbert::encode().

Examples

hg <- text_hypergraph(covid_abstracts, column = "abstract", id = "doc",
                      construction = "knn", k = 10,
                      embeddings = covid_embeddings)
hg

Description

A simple random sample of 1,000 abstracts from the Scopus export of COVID-19 education research that the sbert package also uses (4,187 records, 2020–2024). Records without an abstract of at least 400 characters are excluded before sampling, and an abstract that appears twice is kept once. The years are represented in the proportions of the source. Rebuilt by data-raw/covid_sample.R.

Usage

covid_sample

Format

A data frame with 1,000 rows and 4 columns:

doc

Scopus EID, the unique document identifier.

title

Article title.

abstract

Abstract text (each at least 400 characters).

year

Publication year (integer, 2020–2024).

Source

Scopus export of COVID-19 education research, 2020–2024.

Examples

hg <- text_hypergraph(covid_sample, column = "abstract", id = "doc",
                      stop_words = stop_words_en(), min_count = 5)
hg

Description

Returns the dual hypergraph: every hyperedge becomes a vertex and every vertex becomes a hyperedge, with the transposed weighted incidence. For a bag-construction text_hypergraph(), the dual is identical to rebuilding with the opposite nodes orientation (tested), so document-level and word-level analyses can share one constructed object. Duals of windowed and kNN hypergraphs are returned as plain net_hg objects (their corpus bookkeeping does not transpose meaningfully).

Usage

dual_hypergraph(hg)

Arguments

Value

A hypergraph whose incidence is exactly the transpose of hg's, sparse when hg is sparse, with every row and column kept: an isolated vertex of hg becomes an empty hyperedge of the dual and an empty hyperedge an isolated vertex, so the dual of the dual is hg's incidence again. A text_hypergraph with flipped nodes for bag constructions (dense or sparse), otherwise a net_hg. Hyperedge metadata (edge_data, window counts) describes hyperedges that become vertices, so it is not carried over. Accepted by all ⁠hg_*⁠ verbs.

References

Berge, C. (1989). Hypergraphs: Combinatorics of Finite Sets. North-Holland Mathematical Library 45. North-Holland.

Examples

hg <- text_hypergraph(c(a = "salt and soup", b = "soup and stars"))
dual <- dual_hypergraph(hg)
dual
hg_measures(dual, what = "edges")

Description

A corpus whose sequence of topics can only be described with memory. Thirty students each write twelve posts. Each post is about one of three topics, cooking, astronomy or gardening, and holds seven words drawn with replacement from the vocabulary of its topic and one everyday word (night, today, week, friends) shared by all topics. The first two topics of a student are drawn at random. After two different topics, the next topic is the third one with probability 0.8 and otherwise drawn at random; after a repeated topic, it is drawn at random. A first-order model of the topic sequence cannot represent this rule.

Usage

forum_posts

Format

A data frame with 360 rows (one per post) and 5 columns:

post

Character. The post identifier, st01_t01 to st30_t12.

student

Character. The author, st01 to st30.

turn

Integer. The position of the post among the author's posts, 1 to 12.

topic

Character. The topic drawn by the simulation.

text

Character. The text of the post, eight words.

Source

Simulated with seed 11 by data-raw/forum_posts.R.

See Also

hg_sequences(), which turns a clustering of these posts into one sequence of topics per student.

Examples

head(forum_posts)
forum_hg <- text_hypergraph(forum_posts, column = "text", id = "post")
forum_hg

Description

Every citation between the decisions in gfcc_decisions, grouped into citation blocks: an uninterrupted run of cited decisions inside one decision, the hyperedge of Coupette, Hartung and Katz (2024). One row per citation, dated by both decisions, so backward citations are the rows with date_citing > date_cited.

Usage

gfcc_citations

Format

A data frame with 77,284 rows and 5 columns:

citing

Key of the citing decision, the source of the block.

cited

Key of the cited decision, the node.

block

Citation block identifier, citing:index, the hyperedge.

date_citing

Date of the citing decision, the time of the block.

date_cited

Date of the cited decision.

Source

Coupette, C., Hartung, D., & Katz, D. M. (2024). Legal hypergraphs (GFCC dataset). Zenodo. doi:10.5281/zenodo.8081511, via the replication archive doi:10.5281/zenodo.8081507. Licence CC BY-NC 4.0. Built by data-raw/legal_hypergraphs.R.

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

Examples

head(gfcc_citations)
blocks <- temporal_hypergraph(gfcc_citations, node = "cited",
                              hyperedge = "block", time = "date_citing",
                              nodes = gfcc_decisions, sparse = TRUE)
summary(blocks)

Description

The 3,618 decisions in volumes 1 to 160 of the official collection of the German Federal Constitutional Court (BVerfGE), 1951 to 2022, as released by Coupette, Hartung and Katz (2024). The node table of the citation-block hypergraph in gfcc_citations: every decision is a node from its own date, whether or not it is ever cited.

Usage

gfcc_decisions

Format

A data frame with 3,618 rows and 5 columns:

decision

Decision key, volume-page.

date

Date of the decision.

citation

Official citation, e.g. "BVerfGE 1, 1-3".

type

Decision type ("Urteil" or "Beschluss").

title

Title of the decision, in German.

Source

Coupette, C., Hartung, D., & Katz, D. M. (2024). Legal hypergraphs (GFCC dataset). Zenodo. doi:10.5281/zenodo.8081511, via the replication archive doi:10.5281/zenodo.8081507. Licence CC BY-NC 4.0. Built by data-raw/legal_hypergraphs.R.

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

Examples

head(gfcc_decisions)

Description

Constructs a net_hg the way a network is defined from data. Membership data name a node and a hyperedge: every node sharing one value of hyperedge (a session, a team, a citation block) belongs to one hyperedge. An edge list names from and to, and every row is a hyperedge of size two. An optional weight column produces a weighted incidence matrix.

Usage

group_hypergraph(
  data,
  node = NULL,
  hyperedge = NULL,
  weight = NULL,
  nodes = NULL,
  sparse = FALSE,
  separator = NULL,
  from = NULL,
  to = NULL,
  member = NULL,
  cooccur_by = NULL,
  top = NULL,
  states = NULL,
  threshold = NULL,
  min_size = 1L,
  group = NULL,
  min_share = NULL
)

Arguments

Details

The bipartite representation preserves the full group structure without projecting to a pairwise network. A group of three members A, B, C produces a single 3-hyperedge containing all three, not three pairwise edges AB, AC, BC. This avoids information loss when group interactions are the primary unit of analysis (Perc et al. 2013).

Unlike network_hypergraph() (which derives hyperedges from a network's clique structure), group_hypergraph() takes group memberships directly. The two functions are complementary:

• group_hypergraph() - when group membership is observed (sessions, transactions, co-authorships).

• network_hypergraph() - when only pairwise interactions are observed and triadic structure must be inferred from triangles.

Rows with NA in the node, hyperedge or weight column are dropped silently.

Value

A net_hg object with the same structure produced by network_hypergraph() (hyperedges, incidence, nodes, n_nodes, n_hyperedges, size_distribution, params), plus edge_data when data carries hyperedge attributes (see Details). The params list records source = "group_hypergraph" and the original column names. For clustered sequences the object also has group_sizes and state_counts (read them with hg_get()) and params records source = "clustered_sequences", top, states and unit = "sequences".

Frequent sets within groups

With group, top or min_share, a data frame is read as transactions. Each value of hyperedge (a trial, a session, a basket) is one set, the distinct node values it holds, and the sets are counted within each value of group, which must be constant within a hyperedge. The top most frequent sets of each value of group become hyperedges, counted exactly as for clustered sequences below, and hg_get(hg, what = "sets") reads them with their count and share of the value's sets. Without group, the sets are counted over all hyperedges together, under one value named after hyperedge ("All sessions"). plot(hg, group = ) draws the sets of one value, every node sized by the sets that contain it. states keeps only the listed node values, and min_size the sets of at least that many.

Topic combinations

Given a mixed-membership topic model fitted by hg_topics(), every document is reduced to the set of topics whose share in it is at least threshold, the thresholded topic presence used to build topic co-occurrence networks (Abuhay et al. 2017; Cassi et al. 2017). A document on love, hate and romance gives the set of those three topics. The top most frequent sets become hyperedges, counted exactly as for clustered sequences below, with each document as one transaction, and the topics are the nodes. top = Inf keeps every set, and min_size = 2 keeps only the sets that combine two or more topics. group names a column of the documents table of the fitted hypergraph, such as a publication year or an author, and the sets are then counted within each of its values; NULL (default) counts them over all documents. A document with no topic at the threshold is not counted. Read the sets with hg_get(hg, what = "sets"); count is the number of documents with exactly that set and share its proportion of the group's documents.

Clustered sequences

Given a clustering of sequences, every sequence of every group is reduced to the set of its distinct states (order and repetition dropped; NA and empty cells ignored), and the top most frequent sets of each group become hyperedges – frequent-itemset support counting with each sequence as one transaction (Agrawal & Srikant 1994), restricted to the sets that occur exactly. Sets of equal count are ranked by their name (states sorted and joined by " + "). Groups are named "Cluster 1", "Cluster 2", ... for a net_mmm or net_clustering, and by the list names of a netobject_group, so renamed groups carry through. Integer-coded states are decoded to their labels. The objects are read by their structure; the package that fitted them is not needed.

The hyperedges are named "<group>: <set>" and carry group, set and count (sequences with exactly that set) as hyperedge attributes, so plot() colours and titles them by count in "sequences", and plot(hg, group = "Cluster 1") draws one group's sets with each node sized by the sequences of that group containing the state. Read the tables with hg_get(hg, what = "sets") (one row per hyperedge: its group, set, size, count and share of the group's sequences) and hg_get(hg, what = "state_counts") (one row per group and state). A malformed clustering (no ⁠$data⁠, assignments that do not match it, unnamed networks) raises hypergraphs_bad_input.

Every other column of data that is constant within a hyperedge (a session's date, a team's department) is kept as a hyperedge attribute in the result's edge_data table, one row per hyperedge, where hg_subset()'s where argument and pairwise_network()'s edge_source can use it. Columns that vary within a hyperedge describe memberships, not hyperedges, and are left out.

Note

Dense and sparse paths are tested for exact equality. The sparse path is additionally exercised by the full GFCC reproduction from the Legal Hypergraphs Zenodo archive (3,618 nodes, 46,165 hyperedges and 77,187 nonzero incidences).

A dense incidence with more than .Machine$integer.max cells cannot be addressed by the flat cell index, and would exhaust memory well before that. It raises the classed error hypergraphs_dense_too_large rather than attempting the allocation; pass sparse = TRUE for data at that scale.

References

Agrawal, R., & Srikant, R. (1994). Fast algorithms for mining association rules in large databases. In Proceedings of the 20th International Conference on Very Large Data Bases (VLDB) (pp. 487-499). Morgan Kaufmann.

Abuhay, T. M., Kovalchuk, S. V., Bochenina, K., Kampis, G., Krzhizhanovskaya, V. V., & Lees, M. H. (2017). Analysis of computational science papers from ICCS 2001-2016 using topic modeling and graph theory. Procedia Computer Science, 108, 7-17. doi:10.1016/j.procs.2017.05.183

Cassi, L., Lahatte, A., Rafols, I., Sautier, P., & de Turckheim, E. (2017). Improving fitness: Mapping research priorities against societal needs on obesity. Journal of Informetrics, 11(4), 1095-1113. doi:10.1016/j.joi.2017.09.010

Perc, M., Gomez-Gardenes, J., Szolnoki, A., Floria, L. M., & Moreno, Y. (2013). Evolutionary dynamics of group interactions on structured populations: a review. Journal of the Royal Society Interface 10(80), 20120997. doi:10.1098/rsif.2012.0997

See Also

network_hypergraph() for the clique-based constructor, temporal_hypergraph() for the same inputs with a clock.

Examples

df <- data.frame(
  person = c("Alice", "Bob", "Carol", "Alice", "Bob",
             "Dave", "Carol", "Dave", "Eve"),
  session = c("S1", "S1", "S1", "S2", "S2",
              "S3", "S3", "S3", "S3")
)
hg <- group_hypergraph(df, node = "person", hyperedge = "session")
print(hg)
summary(hg)

contacts <- data.frame(from = c("a", "b"), to = c("b", "c"))
group_hypergraph(contacts, from = "from", to = "to")

# a clustering of sequences, shaped as a mixture Markov fit (net_mmm)
fit <- structure(list(
  data = data.frame(V1 = c("a", "a", "b", "a", "c"),
                    V2 = c("b", "b", "c", "c", "a"),
                    V3 = c("a", NA, "a", "b", "b")),
  assignments = c(1L, 1L, 2L, 1L, 2L), k = 2L
), class = "net_mmm")
sets <- group_hypergraph(fit, top = 3)
hg_get(sets, what = "sets")
plot(sets, group = "Cluster 1")

Description

Implements Linmei et al.'s (2019) heterogeneous graph convolution and dual-level attention. Node types retain separate input feature spaces and transformation matrices. For every target node, type-level attention first weighs the available neighboring information types; node-level attention then weighs individual neighbors before their type-specific transformed representations are combined. This is HGAT for heterogeneous information networks, distinct from Ding et al.'s document-hypergraph text_hypergat().

Usage

heterogeneous_hgat(
  adjacency,
  node_types,
  features,
  labels,
  hidden = 128L,
  layers = 2L,
  epochs = 200L,
  lr = 0.005,
  weight_decay = 5e-04,
  dropout = 0.5,
  validation = 0.1,
  seed = 1L,
  verbose = FALSE
)

Arguments

Value

A prediction data.frame for every heterogeneous-network node, with training history and node types attached as attributes.

References

Linmei, H., Yang, T., Shi, C., Ji, H., & Li, X. (2019). Heterogeneous graph attention networks for semi-supervised short text classification. EMNLP-IJCNLP 2019, 4821–4830.

Description

Compares any two tidy labelings – partitions from hg_cluster(), predictions from hg_classify(), hg_neural() or hg_hypergat() – joined on their shared node column. agreement is the share of nodes with literally equal labels (meaningful when both labelings use the same label set, e.g. a classifier scored against the clustering that produced its seeds); ari is the adjusted Rand index (Hubert & Arabie 1985), which is label-permutation invariant and the right statistic when the two label sets are arbitrary (e.g. two independent clusterings). Adjusted mutual information (ami) and normalized mutual information (nmi) are also available; the legal-hypergraphs workflow uses AMI to select the medoid of repeated Infomap partitions.

Usage

hg_agreement(
  x,
  y,
  what = c("summary", "table", "mapping"),
  method = "ari",
  node = NULL,
  label = NULL
)

Arguments

Value

A base data.frame. For what = "summary": one row with columns n (nodes compared), agreement (share of equal labels), aligned (nodes that stay with the majority of their x label in y – the sum of overlap over what = "mapping", so a label-name-free count of how many nodes a re-fit keeps together) and the requested measure columns. For what = "table": one row per label pair with columns label_x, label_y and n. For what = "mapping": one row per label of x with columns label_x, n (its nodes), label_y (the label of y holding most of them), overlap (how many) and share (overlap / n), in the natural order of label_x.

References

Hubert, L., & Arabie, P. (1985). Comparing partitions. Journal of Classification, 2, 193–218.

Vinh, N. X., Epps, J., & Bailey, J. (2010). Information theoretic measures for clusterings comparison. Journal of Machine Learning Research, 11, 2837–2854.

Examples

hg <- text_hypergraph(c(
  cooking_1 = "simmer the soup with onions and carrots",
  cooking_2 = "this soup recipe needs salt on a cold night",
  space_1 = "the telescope revealed a distant galaxy and stars",
  space_2 = "astronomers aimed the telescope at the stars all night"
), stop_words = c("the", "with", "and", "a", "this", "at", "on", "all"))
topics <- hg_cluster(hg, k = 2, seed = 1)
fit <- hg_classify(hg, labels = c(cooking_1 = "Cluster 1",
                                  space_1 = "Cluster 2"))
hg_agreement(fit, topics)
hg_agreement(fit, topics, what = "table")
hg_agreement(fit, topics, what = "mapping")
# a labeling read from any table: name its label column
known <- data.frame(doc = c("cooking_1", "space_2"), theme = c("cooking", "space"))
hg_agreement(topics, known, label = c("cluster", "theme"), what = "table")

Description

Implements the AllSet framework of Chien et al. (2022) as one complete node-to-edge-to-node propagation layer. model = "deepsets" uses Eq. 7, an MLP before and after each multiset sum. model = "transformer" uses Eq. 8: pooling by multihead attention from a learned query, followed by residual MLPs and layer normalization. Both directions have independent learned multiset functions and are permutation invariant.

Usage

hg_allset(
  hg,
  labels,
  features = "incidence",
  model = c("deepsets", "transformer"),
  hidden = 128L,
  heads = 4L,
  epochs = 200L,
  lr = 0.001,
  weight_decay = 5e-04,
  dropout = 0.5,
  validation = 0.1,
  seed = 1L,
  verbose = FALSE
)

Arguments

Value

A prediction data.frame in the same format as hg_neural(), with training history and the AllSet model name attached.

References

Chien, E., Pan, C., Peng, J., & Milenkovic, O. (2022). You are AllSet: A multiset function framework for hypergraph neural networks. ICLR 2022.

Description

Measures whether nodes of similar hyperdegree share hyperedges, with the three choice functions of Chodrow (2020, Sec. 4.2). From every hyperedge with at least two members a pair of nodes is chosen, and the coefficient is the correlation of their scores over hyperedges, each hyperedge counting once:

Usage

hg_assortativity(hg, type = "uniform", scale = c("rank", "degree"))

Arguments

Details

• "uniform" – a uniformly random pair of distinct members (computed exactly, as the expectation over the random choice; the pair is unordered, so both orders enter with equal weight);

• "top_2" – the two members of largest degree (unordered);

• "top_bottom" – the ordered pair (largest-degree member, smallest-degree member), measuring whether the least-connected member of a group is better connected when its best-connected member is.

The score of a node is its hyperdegree (the number of hyperedges containing it). With scale = "rank" (default) the score is the node's rank by hyperdegree among all nodes (ties averaged), which gives Chodrow's "generalized Spearman" coefficient; scale = "degree" uses the raw hyperdegree (a Pearson coefficient, as XGI does).

On a graph (every hyperedge of size two) the three choice functions give the same pairs, and ⁠type = "uniform", scale = "degree"⁠ is Newman's degree assortativity (tested against igraph::assortativity_degree()).

Convention differences with XGI 0.10.2 (degree_assortativity(exact = TRUE)), documented and tested: XGI's exact "uniform" weights every hyperedge by its number of member pairs $m(m-1)$ instead of counting each hyperedge once, so the two agree only on uniform hypergraphs (XGI's Monte Carlo sampler, exact = FALSE, samples Chodrow's edge-weighted quantity and agrees within sampling error); XGI symmetrizes "top-bottom" (both orders), whereas Chodrow's definition keeps the order (largest, smallest); XGI returns 0 where the coefficient is undefined. "top_2" agrees with XGI exactly.

The coefficient is undefined (NA) when either chosen score has zero variance across hyperedges, e.g. on a regular hypergraph.

Zero is not the null value for "top_2" and "top_bottom". Both pair order statistics of a hyperedge (its two largest scores, or its largest and smallest), which are correlated even when members are drawn at random, so random hypergraphs give positive values (Chodrow 2020 compares against a null model for this reason). Judge them against coefficients on degree-matched random hypergraphs, not against 0; "uniform" is centred near 0 under random mixing.

Value

A base data.frame, one row per type, with columns type, scale, assortativity (in ⁠[-1, 1]⁠, NA when undefined) and n_edges (the hyperedges of size at least two that entered).

Conditions

Raises hypergraphs_bad_input when hg is not a net_hg or has no hyperedge with at least two members.

References

Chodrow, P. S. (2020). Configuration models of random hypergraphs. Journal of Complex Networks, 8(3), cnaa018. doi:10.1093/comnet/cnaa018

Battiston, F., Cencetti, G., Iacopini, I., Latora, V., Lucas, M., Patania, A., Young, J.-G., & Petri, G. (2020). Networks beyond pairwise interactions: Structure and dynamics. Physics Reports, 874, 1-92. doi:10.1016/j.physrep.2020.05.004

See Also

hg_degree_correlation(), hg_transitivity().

Examples

groups <- data.frame(
  member = c("a", "b", "c", "a", "d", "b", "d", "e", "c", "d", "e", "f"),
  group  = c("g1", "g1", "g1", "g2", "g2", "g3", "g3", "g3",
             "g4", "g4", "g4", "g4")
)
hg <- group_hypergraph(groups, node = "member", hyperedge = "group")
hg_assortativity(hg, type = c("uniform", "top_2", "top_bottom"))

Description

The ranks of the homology groups with rational coefficients: $\beta_0$ counts connected components, $\beta_1$ independent loops, $\beta_2$ voids, and so on.

Usage

hg_betti(sc)

Arguments

Details

The coefficients are rational, not Z/2. The two agree on most complexes but not on one with torsion: on the six-vertex real projective plane (RP2) hg_betti() gives ⁠(1, 0, 0)⁠, while hg_homology(), which reduces over Z/2 as the persistence literature does, ends its Betti curve at ⁠(1, 1, 1)⁠. Use hg_homology() when Z/2 Betti numbers are meant.

Value

A named integer vector c(b0 = , b1 = , ...).

References

Hatcher, A. (2002). Algebraic Topology. Cambridge University Press.

See Also

hg_euler(), hg_homology()

Examples

adj <- matrix(c(0, 1, 1, 0,
                1, 0, 1, 1,
                1, 1, 0, 1,
                0, 1, 1, 0), 4, 4, dimnames = list(letters[1:4], letters[1:4]))
hg_betti(simplicial(adj))

Description

Nonparametric bootstrap over sequences for the rules of a higher-order network (see hon()): sequences are resampled with replacement, and for every rule edge of the observed network the replicate distribution yields a percentile confidence interval for its conditional probability and a support - the fraction of replicates in which the rule's context is extracted as a rule at all. Support close to 1 for a higher-order context means the order elevation is stable under resampling, not an artifact of the particular sample; first-order contexts have support 1 by construction.

Usage

hg_bootstrap(
  data,
  n_boot = 500L,
  level = 0.95,
  max_order = 5L,
  min_freq = 1L,
  collapse_repeats = FALSE,
  action = NULL,
  actor = NULL,
  time = NULL,
  parallel = FALSE,
  n_cores = 2L,
  seed = NULL,
  session = NULL,
  time_threshold = 900,
  timezone = "UTC"
)

Arguments

Details

Per-sequence observation counts are computed once; every replicate is a weighted aggregation of those counts followed by counts-based rule extraction (never a re-scan of the data). All randomness is drawn before any parallel work, so parallel = TRUE reproduces the serial result under the same seed.

Value

An object of class hypergraphs_bootstrap: a list with edges (the tidy inference table, one row per rule edge of the observed network: from, to, order, count, probability, ci_lower, ci_upper, support, n_boot_used), n_boot, level, max_order, min_freq, n_trajectories, and seed. Has print, summary and plot methods; hg_get() returns the inference table (optionally filtered with ⁠min_support =⁠ or restricted with ⁠order_min =⁠).

References

Xu, J., Wickramarathne, T. L., & Chawla, N. V. (2016). Representing higher-order dependencies in networks. Science Advances 2(5), e1600028. doi:10.1126/sciadv.1600028

Efron, B., & Tibshirani, R. J. (1993). An Introduction to the Bootstrap. Chapman & Hall.

See Also

hon(), hg_compare(), markov_order()

Examples

hg_seqs <- list(
  c("a", "b", "c", "a", "b", "c"),
  c("x", "b", "d", "x", "b", "d"),
  c("a", "b", "c", "a", "b", "c"),
  c("x", "b", "d", "x", "b", "d")
)
bs <- hg_bootstrap(hg_seqs, n_boot = 50, max_order = 2, seed = 1)
bs
hg_get(bs, sort_by = "support", top = 6)

Description

The largest displacement of the best matching between two persistence diagrams, where a point may also match the diagonal. Essential classes are matched only to essential classes; a dimension whose essential counts differ is Inf apart.

Usage

hg_bottleneck(d1, d2, dimension = NULL, tol = .Machine$double.eps^0.5)

Arguments

Value

A named numeric vector, one distance per dimension, named "dim_<k>".

References

Cohen-Steiner, D., Edelsbrunner, H., & Harer, J. (2007). Stability of persistence diagrams. Discrete & Computational Geometry, 37, 103–120. doi:10.1007/s00454-006-1276-5

Edelsbrunner, H., & Harer, J. (2010). Computational Topology: An Introduction. American Mathematical Society.

See Also

hg_wasserstein()

Examples

d1 <- data.frame(dimension = 0L, birth = 0, death = 2)
d2 <- data.frame(dimension = 0L, birth = 0, death = 3)
hg_bottleneck(d1, d2)

Description

One verb, two estimators, chosen by the class of x:

a hypergraph (net_hg, e.g. from text_hypergraph(), window_hypergraph())

eigenvector-style hypergraph centralities – clique-motif, Z- and H-eigenvector, EDVW PageRank, subhypergraph and Katz; see hg_centrality.net_hg().

a memory network (net_hon, from hon())

PageRank, betweenness and closeness of the higher-order topology, projected onto the first-order states; see hg_centrality.net_hon().

Each method keeps its own arguments; passing an argument that only the other method takes raises hypergraphs_bad_input.

Usage

hg_centrality(x, ...)

## Default S3 method:
hg_centrality(x, ...)

Arguments

Value

A base data.frame, one row per node (or per state), with one column per requested centrality. Any other input raises hypergraphs_bad_input.

Examples

hg <- text_hypergraph(c(a = "salt and soup", b = "soup and stars"))
hg_centrality(hg, type = "clique")

seqs <- list(c("a", "b", "c", "a", "b", "c"), c("x", "b", "d", "x", "b", "d"))
hg_centrality(hon(seqs, max_order = 2), type = "pagerank")

Description

The hypergraph method of hg_centrality(). Computes one or more eigenvector-style centralities on a net_hg: clique-motif (CEC), Z-eigenvector (ZEC), and H-eigenvector (HEC). Each variant captures influence differently - CEC flattens group structure via clique expansion, while ZEC and HEC propagate through the higher-order groups directly.

Usage

## S3 method for class 'net_hg'
hg_centrality(
  x,
  type = c("clique", "Z", "H"),
  sort_by = NULL,
  n = Inf,
  max_iter = 1000L,
  tol = 1e-08,
  normalize = TRUE,
  damping = 0.85,
  edge_weights = NULL,
  alpha = NULL,
  ...
)

Arguments

Details

type also accepts "pagerank" (EDVW hypergraph PageRank), "subhypergraph" and "katz" (Katz centrality, which needs alpha); the result is one row per node.

Clique-motif eigenvector centrality (CEC): forms the clique-expanded pairwise graph $W$ where $W_{ij} = |\{e : i, j \in e\}|$ and returns the leading eigenvector of $W$. Equivalent to running igraph::eigen_centrality() on pairwise_network() output.

Z-eigenvector centrality (ZEC): solves the linear eigen-equation on the hyperedge tensor,

$\lambda\, x_i \;=\; \sum_{e \ni i}\; \prod_{j \in e,\; j \neq i} x_j,$

via power iteration. Works for hypergraphs with mixed edge sizes.

H-eigenvector centrality (HEC): solves the power-k-1 eigen-equation,

$\lambda\, x_i^{k-1} \;=\; \sum_{e \ni i}\; \prod_{j \in e,\; j \neq i} x_j.$

For uniform hypergraphs (all hyperedges of size $k$), this is equivalent to normalizing the ZEC update by the geometric-mean exponent $1/(k-1)$. For mixed sizes, the effective exponent is taken from the largest hyperedge; expect slightly different rankings from ZEC in the mixed case.

Hypergraph PageRank ("pagerank"): the stationary distribution of the damped EDVW random walk of Chitra & Raphael (2019): from node $v$, pick a hyperedge $e \ni v$ with probability proportional to its weight $w(e)$, then a node $u \in e$ with probability proportional to its edge-dependent vertex weight $\gamma_e(u)$ (the incidence cell, i.e. occurrence totals for window_hypergraph()); with probability $1 - damping$ teleport uniformly. Their collapse theorem: with edge-independent vertex weights (a binary incidence) the walk is equivalent to PageRank on the weighted clique expansion with edge weights $\sum_{e \ni u,v} w(e)/\delta(e)$ – the hypergraph adds information exactly when $\gamma$ is edge-dependent. Nodes left in no hyperedge (possible after min_weight/min_size filtering) teleport from every step and receive only teleportation mass. The undamped stationary distribution of the same walk is the pi column reported by hg_cluster().

Subhypergraph centrality ("subhypergraph"): the logarithm of the diagonal of the matrix exponential of the clique adjacency derived from binary incidence (so entries count shared hyperedges), $\log[\exp(W)]_{ii}$. It counts closed walks based at each node with a factorial penalty for length and matches the implementation used by HypergraphX 1.5 in the legal-hypergraphs analysis.

Katz centrality ("katz"): Katz's (1953) status index on the hypergraph adjacency of Estrada & Rodriguez-Velazquez (2006), $A_{ij}$ = the number of hyperedges containing both $i$ and $j$ (the weighted clique expansion),

$x = \sum_{k \ge 1} \alpha^k A^k \mathbf{1} = (I - \alpha A)^{-1} \alpha A \mathbf{1},\qquad 0 < \alpha < 1/\lambda_{max}(A),$

the $\alpha$-discounted number of walks leaving each node (Battiston et al. 2020, Sec. III.B.3). Returned on this natural scale, not normalized; the alpha centrality of Bonacich & Lloyd (2001) with unit exogenous status, which also counts the length-0 walk, is katz + 1 (tested against igraph::alpha_centrality() on the clique expansion). XGI's katz_centrality() is the same vector for its fixed $\alpha = 2^{-n}$, rescaled to sum to one (tested). It is the only type that also runs on a sparse incidence.

Value

A base data.frame, one row per node (or the n requested rows), with one column per requested centrality.

References

Benson, A. R. (2019). Three hypergraph eigenvector centralities. SIAM Journal on Mathematics of Data Science 1(2), 293-312. arXiv:1807.09644.

Chitra, U., & Raphael, B. J. (2019). Random walks on hypergraphs with edge-dependent vertex weights. Proceedings of the 36th International Conference on Machine Learning, PMLR 97, 1172-1181.

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

Estrada, E., & Rodriguez-Velazquez, J. A. (2005). Complex networks as hypergraphs. arXiv preprint physics/0505137.

Estrada, E., & Rodriguez-Velazquez, J. A. (2006). Subgraph centrality and clustering in complex hyper-networks. Physica A, 364, 581-594. doi:10.1016/j.physa.2005.12.002

Katz, L. (1953). A new status index derived from sociometric analysis. Psychometrika, 18(1), 39-43. doi:10.1007/BF02289026

Bonacich, P., & Lloyd, P. (2001). Eigenvector-like measures of centrality for asymmetric relations. Social Networks, 23(3), 191-201. doi:10.1016/S0378-8733(01)00038-7

Battiston, F., Cencetti, G., Iacopini, I., Latora, V., Lucas, M., Patania, A., Young, J.-G., & Petri, G. (2020). Networks beyond pairwise interactions: Structure and dynamics. Physics Reports, 874, 1-92. doi:10.1016/j.physrep.2020.05.004

See Also

network_hypergraph(), pairwise_network(), hg_measures().

Examples

hg <- text_hypergraph(c(
  a = "salt and soup and onions",
  b = "soup and salt",
  c = "stars and salt"
))
hg_centrality(hg, type = "clique")
hg_centrality(hg, type = c("clique", "katz"), alpha = 0.1)

Description

The memory-network method of hg_centrality(). Computes centralities on the higher-order topology of a hon() network and, by default, projects them back onto the first-order states, following Scholtes, Wider & Garas (2016). Because a higher-order node carries the memory of how a state was reached, these centralities can rank states differently from the same measures on the first-order transition network - and that difference is the evidence that memory matters for flow, not just for prediction.

Usage

## S3 method for class 'net_hon'
hg_centrality(
  x,
  type = c("pagerank", "betweenness", "closeness"),
  project = TRUE,
  projection = c("scaled", "last", "first", "all"),
  damping = 0.85,
  weighted = FALSE,
  max_iter = 1000L,
  tol = 1e-12,
  max_paths = 1e+06,
  sort_by = NULL,
  top = NULL,
  ...
)

Arguments

Details

Semantics match pathpy 2.2.0 (the reference implementation by the method's author), generalized from fixed-order to the variable-order networks hon() produces: a higher-order node's order is the number of states in the path it represents, and the first-order distance implied by a higher-order hop count adds that node's order minus one. With a uniform order the generalization reduces exactly to pathpy's formulas.

Value

A data.frame, one row per first-order state (or per higher-order node when project = FALSE), with the requested centralities as columns:

state

First-order state (when project = TRUE).

node, order

Higher-order node and its order (when project = FALSE).

pagerank

Projected PageRank of the higher-order topology.

betweenness

Share of first-order shortest paths (implied by the higher-order topology) passing through the state.

closeness

Harmonic closeness on the implied first-order distances: the sum of inverse distances into the state.

Rows are ordered by state (or by node) so the result is deterministic.

References

Scholtes, I., Wider, N., & Garas, A. (2016). Higher-order aggregate networks in the analysis of temporal networks: path structures and centralities. The European Physical Journal B 89, 61. doi:10.1140/epjb/e2016-60663-0

Xu, J., Wickramarathne, T. L., & Chawla, N. V. (2016). Representing higher-order dependencies in networks. Science Advances 2(5), e1600028. doi:10.1126/sciadv.1600028

See Also

hon(), hg_bootstrap(), memory()

Examples

seqs <- c(
  replicate(6, rep(c("a", "b", "c"), 4), simplify = FALSE),
  replicate(6, rep(c("x", "b", "d"), 4), simplify = FALSE)
)
hon <- hon(seqs, max_order = 2)
hg_centrality(hon)

# Which contexts, rather than which states, carry the flow?
hg_centrality(hon, type = "pagerank", project = FALSE)

Description

Semi-supervised classification of hypergraph nodes by the regularization framework of Zhou et al. (2006): given labels for a subset of nodes, the scores ⁠F = (1 - xi) * (I - xi * S)^{-1} Y⁠ spread the labels over the hypergraph, where S = I - L is the normalized similarity operator of the chosen Laplacian and Y is the label indicator matrix. Each node is assigned the class with the highest score. This is the non-neural ancestor of hypergraph-attention text classifiers: with documents as hyperedges over words (or vice versa) it classifies unlabeled nodes from a handful of labeled ones.

Usage

hg_classify(
  hg,
  labels,
  xi = 0.99,
  type = c("zhou", "random_walk"),
  normalization = c("none", "class_mass"),
  edge_weights = NULL,
  holdout = NULL,
  seed = 1L
)

Arguments

Details

The result is one row per node with its given and predicted label.

Value

A base data.frame, one row per node, with columns node, label (the given label or NA), predicted, score, and margin. With holdout, an hg_classification: the same table with label holding the true label, split ("train" or "test") and correct for the held-out documents; read its evaluation with hg_get() (what = "accuracy", "classes", "confusion").

References

Zhou, D., Huang, J., & Scholkopf, B. (2006). Learning with hypergraphs: Clustering, classification, and embedding. NeurIPS 19. doi:10.7551/mitpress/7503.003.0205

Zhu, X., Ghahramani, Z., & Lafferty, J. (2003). Semi-supervised learning using Gaussian fields and harmonic functions. ICML 20.

Examples

hg <- text_hypergraph(c(
  cooking_1 = "simmer the soup with onions and carrots",
  cooking_2 = "this soup recipe needs salt on a cold night",
  space_1 = "the telescope revealed a distant galaxy and stars",
  space_2 = "astronomers aimed the telescope at the stars all night"
), stop_words = c("the", "with", "and", "a", "this", "at", "on", "all"))
hg_classify(hg, labels = c(cooking_1 = "cooking", space_1 = "space"))

Description

Partitions the nodes of a hypergraph into k clusters with either of Hayashi et al.'s (2020) representative-digraph algorithms. algorithm = "spectral" (RDC-Spec) row-normalizes the k smallest Laplacian eigenvectors and applies k-means. algorithm = "symnmf" (RDC-Sym) computes a rank-k non-negative factorization ⁠T ~= U U'⁠ of the normalized similarity T = I - L, then assigns each vertex to the largest entry in its row of U, exactly as Algorithm 2 specifies. T is dense whatever the incidence, so on a sparse hypergraph it is built from the sparse Laplacian and factorised dense (8 n^2 bytes: 350 MB for 6,630 documents); beyond 15,000 nodes this raises hypergraphs_sparse_too_large. With type = "random_walk" and a weighted incidence (e.g. from group_hypergraph() with ⁠weight =⁠), the edge-dependent vertex weights genuinely change the partition - with edge-independent weights the walk collapses to a graph random walk (Chitra & Raphael 2019).

Usage

hg_cluster(
  hg,
  k,
  type = c("zhou", "random_walk"),
  edge_weights = NULL,
  seed = NULL,
  nstart = 25L,
  what = c("clusters", "embedding", "eigenvalues", "membership"),
  n = Inf,
  algorithm = c("spectral", "symnmf"),
  max_iter = 500L,
  tol = 1e-06,
  parallel = FALSE,
  n_cores = 2L
)

Arguments

Details

Both solvers are stochastic: nstart initializations are used and a seed fixes the result. Report stability across seeds for consequential results.

type = "random_walk" (Hayashi et al. 2020) is the natural choice for tf-idf-weighted text hypergraphs. ⁠what =⁠ returns the cluster table, the embedding or the leading eigenvalues as a tidy data.frame.

Value

A base data.frame. For what = "clusters": one row per node, columns node and cluster. For what = "embedding": node, cluster, pi, dim1..dimk. For what = "eigenvalues": one row per eigenvalue, columns index, value (ascending) and gap (the distance to the next eigenvalue – large gaps indicate supported cluster counts; NA on the last row). For what = "membership": one row per node and cluster, columns node, cluster and membership (summing to one over a node's clusters); a node's largest membership is its cluster in what = "clusters".

References

Kuang, D., Ding, C., & Park, H. (2012). Symmetric nonnegative matrix factorization for graph clustering. Proceedings of the 2012 SIAM International Conference on Data Mining, 106-117. doi:10.1137/1.9781611972825.10

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

Chitra, U., & Raphael, B. J. (2019). Random walks on hypergraphs with edge-dependent vertex weights. ICML 2019.

Examples

hg <- text_hypergraph(c(
  cooking_1 = "simmer the soup with onions and carrots",
  cooking_2 = "this soup recipe needs salt on a cold night",
  space_1 = "the telescope revealed a distant galaxy and stars",
  space_2 = "astronomers aimed the telescope at the stars all night"
), stop_words = c("the", "with", "and", "a", "this", "at", "on", "all"))
hg_cluster(hg, k = 2, type = "random_walk", seed = 1)
hg_cluster(hg, k = 2, seed = 1, what = "embedding")
hg_cluster(hg, k = 2, seed = 1, what = "eigenvalues", n = 5)

Description

Clusters the nodes and the hyperedges of a hypergraph together, so that each cluster is a pair: a set of documents and the set of words that characterises them, from one spectral cut of the document-word bipartite graph (Dhillon 2001). With $A$ the incidence matrix (nodes by hyperedges, the stored weights: counts or tf-idf on a text_hypergraph()), $D_1$ and $D_2$ its row and column sums, the scaled matrix $A_n = D_1^{-1/2} A D_2^{-1/2}$ is decomposed by SVD; its leading singular pair is trivial, the next $\ell = \lceil \log_2 k \rceil$ left and right singular vectors $U, V$ give the embedding $Z = [D_1^{-1/2} U;\ D_2^{-1/2} V]$, one row per node and per hyperedge, and k-means on the rows of $Z$ gives the k co-clusters (Dhillon 2001, Algorithm Multipartition).

Usage

hg_cocluster(
  hg,
  k,
  seed = NULL,
  nstart = 25L,
  what = c("clusters", "embedding"),
  role = c("all", "node", "hyperedge")
)

Arguments

Details

For a binary incidence with unit hyperedge weights, the node half of the embedding spans the same space as the Zhou et al. (2006) hypergraph Laplacian eigenvectors that hg_cluster() cuts (the squared singular values are one minus the Laplacian eigenvalues), so co-clustering reads the same cut on both sides of the bipartite graph; with other weights the two differ, because the Zhou Laplacian reads only the binary pattern. A cluster may hold nodes and no hyperedges, or the reverse.

Value

A base data.frame, one row per node and then per hyperedge (filtered by role), with columns node (the node or hyperedge name), role ("node" or "hyperedge") and cluster ("Cluster 1", ..., numbered by first appearance in that row order); with what = "embedding" also dim1..dimL. Raises hypergraphs_bad_input for a k that is not a whole number from 2 to the number of rows, a k whose $\ell + 1$ singular pairs the incidence does not have ($\ell + 1 > \min(m, n)$ for an $m \times n$ incidence, so $k \le 2^{\min(m, n) - 1}$), an embedding with fewer distinct rows than k, or an empty node or hyperedge (zero degree, where the scaling is undefined).

References

Dhillon, I. S. (2001). Co-clustering documents and words using bipartite spectral graph partitioning. Proceedings of the Seventh ACM SIGKDD International Conference on Knowledge Discovery and Data Mining, 269–274. doi:10.1145/502512.502550

Zhou, D., Huang, J., & Schölkopf, B. (2006). Learning with hypergraphs: Clustering, classification, and embedding. Advances in Neural Information Processing Systems 19, 1601–1608. doi:10.7551/mitpress/7503.003.0205

Examples

hg <- text_hypergraph(c(
  cooking_1 = "simmer the soup with onions and carrots",
  cooking_2 = "this soup recipe needs salt on a cold night",
  space_1 = "the telescope revealed a distant galaxy and stars",
  space_2 = "astronomers aimed the telescope at the stars all night"
), stop_words = c("the", "with", "and", "a", "this", "at", "on", "all"))
hg_cocluster(hg, k = 2, seed = 1)
hg_cocluster(hg, k = 2, seed = 1, role = "hyperedge")

Description

One verb, two estimators, chosen by the class of x:

a hypergraph (net_hg)

an ensemble of Infomap runs on a projection (or IRMM with type = "irmm"), with the adjusted-mutual- information medoid; see hg_communities.net_hg().

a memory network (net_hon, from hon())

the map equation for memory networks: overlapping modules of the physical states, compared with the first-order map; see hg_communities.net_hon().

Each method keeps its own arguments; passing an argument that only the other method takes raises hypergraphs_bad_input.

Usage

hg_communities(x, ...)

## Default S3 method:
hg_communities(x, ...)

Arguments

Value

An hg_communities object (hypergraph) or a hypergraphs_memory_communities object (memory network); read either with hg_get(). Any other input raises hypergraphs_bad_input.

Examples

seqs <- list(c("a", "h", "b", "a", "h", "b", "a"),
             c("c", "h", "d", "c", "h", "d", "c"))
comm <- hg_communities(hon(seqs, max_order = 2L), trials = 2L)
hg_get(comm)

Description

The hypergraph method of hg_communities(). Builds the normalized association graph of Coupette et al. (2024), runs Infomap repeatedly, compares every pair of partitions with AMI, ARI and NMI, and returns the run with the largest summed AMI as the medoid. The paper uses 50 seeds and 100 Infomap trials per seed, which are the defaults.

Usage

## S3 method for class 'net_hg'
hg_communities(
  x,
  n_runs = 50L,
  trials = 100L,
  seeds = NULL,
  method = c("association", "citation"),
  duplicate_edges = c("count", "collapse"),
  self_association = FALSE,
  edge_source = NULL,
  directed = FALSE,
  type = c("infomap", "irmm"),
  delta = 0.01,
  max_iter = 50L,
  edge_weights = NULL,
  parallel = FALSE,
  n_cores = 2L,
  ...
)

Arguments

Value

An hg_communities object containing medoid (a tidy node/community table), all partitions, AMI/ARI/NMI similarity matrices, run metadata, community sizes, and the graph projection Infomap ran on. For type = "irmm" the "runs" table has run, seed, n_communities, iterations, converged, max_weight_change and modularity (the linear hypergraph modularity of hg_modularity()), projection is the reweighted clique reduction of the medoid run, and hg_get(fit, what = "weights") gives one row per hyperedge with edge, size, initial_weight and the medoid run's final weight.

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

Kumar, T., Vaidyanathan, S., Ananthapadmanabhan, H., Parthasarathy, S., & Ravindran, B. (2020). Hypergraph clustering by iteratively reweighted modularity maximization. Applied Network Science, 5, 52. doi:10.1007/s41109-020-00300-3

Blondel, V. D., Guillaume, J.-L., Lambiotte, R., & Lefebvre, E. (2008). Fast unfolding of communities in large networks. Journal of Statistical Mechanics, 2008(10), P10008. doi:10.1088/1742-5468/2008/10/P10008

See Also

hg_modularity() to score any partition.

Examples

dat <- data.frame(
  member = c("a", "b", "c", "a", "b", "c", "x", "y", "z", "x", "y", "z"),
  edge = rep(paste0("e", 1:4), each = 3)
)
h <- group_hypergraph(dat, "member", "edge")
if (requireNamespace("igraph", quietly = TRUE)) {
  fit <- hg_communities(h, n_runs = 2, trials = 2, seeds = 1:2)
  hg_get(fit)
  irmm <- hg_communities(h, type = "irmm", n_runs = 3, seeds = 1:3)
  hg_get(irmm)
  hg_get(irmm, what = "runs")
}

Description

Finds modules in a higher-order network by minimising the map equation for memory networks (Rosvall et al. 2014; Edler, Bohlin & Rosvall 2017). The state nodes of the HON ("a -> b" is physical node b reached from a) are clustered, but each module's codebook is written over physical nodes: state nodes of one physical node that land in the same module share a codeword. This is not first-order Infomap run on the state graph, and a physical node whose state nodes fall in different modules belongs to all of them, so modules of physical nodes can overlap.

The same search is run on the first-order network obtained by projecting the memory network's link flow onto physical nodes, so the result says whether memory compresses the flow better than a first-order description.

Usage

## S3 method for class 'net_hon'
hg_communities(
  x,
  partition = NULL,
  trials = 10L,
  teleportation = 0.15,
  seed = 1L,
  ...
)

Arguments

Details

Flow. State node visit rates are the stationary distribution of the walk on the HON transition matrix $P_{\alpha\beta} = w_{\alpha\beta}/w_\alpha$ (Edler et al. 2017, Eq. 8-9). With probability teleportation ($\tau$), and always from a state with no out-links, the walker restarts at the tail of a link drawn in proportion to its weight (teleportation to links; Lambiotte & Rosvall 2012). Teleportation is unrecorded: link flow is $f_{\alpha\beta} = \pi_\alpha P_{\alpha\beta}$ renormalised to sum to one, and a state's flow is its link in-flow. This is Infomap's directed flow model; node flows and codelengths match the Python infomap package (2.15.1). teleportation = 0 uses the plain stationary distribution and needs an irreducible chain.

Codelength (Edler et al. 2017, Eq. 24-26). With module enter flow $q^{in}_m$, exit flow $q^{out}_m$, and physical flow inside a module $\pi_{i \cap m} = \sum_{\beta_i \in m} \pi_{\beta_i}$,

$L(M) = q^{in} H(Q) + \sum_m p_m H(P_m),$

where $q^{in} = \sum_m q^{in}_m$, $H(Q)$ is the entropy of the enter rates $q^{in}_m / q^{in}$, $p_m = q^{out}_m + \sum_i \pi_{i \cap m}$, and $H(P_m)$ is the entropy of $\{q^{out}_m, \pi_{i \cap m}\}$ normalised by $p_m$. The one-module codelength is the entropy of the physical-node flow.

Search (Edler et al. 2017, Algorithms 2-5): every state node starts in its own module; in random sequential order each node moves to the neighbouring or new module that most decreases $L$; modules are then aggregated into nodes and the moves repeat, until $L$ stops decreasing (repeated node aggregation, the Louvain machinery). The result is fine-tuned by restarting the aggregation from single state nodes placed in their current modules. Coarse-tuning (Algorithm 6) is not implemented. trials independent runs are made from one seeded random stream and the shortest codelength is kept; hg_get(x, what = "trials") reports every run and its agreement (adjusted Rand index) with the kept one.

First-order comparison. The link flow of the memory network is summed over state nodes into a physical-node network, $w_{ij} = \sum_{\alpha_i, \beta_j} f_{\alpha\beta}$, and searched with the same flow model and the same number of trials. Rosvall et al. (2014) compare memory and first-order maps of the same pathway data this way.

Value

A hypergraphs_memory_communities object. Read it with hg_get(): what = "states" (one row per state node), "physical" (one row per physical node x module), "modules", "trials", "first_order" and "codelength"; see hg_get.hypergraphs_memory_communities().

Conditions

hypergraphs_bad_input for a non-net_hon input, invalid arguments, or a partition that does not cover every state; hypergraphs_not_ergodic when teleportation = 0 and the walk has no unique stationary flow.

References

Rosvall, M., Esquivel, A. V., Lancichinetti, A., West, J. D., & Lambiotte, R. (2014). Memory in network flows and its effects on spreading dynamics and community detection. Nature Communications, 5, 4630. doi:10.1038/ncomms5630

Edler, D., Bohlin, L., & Rosvall, M. (2017). Mapping higher-order network flows in memory and multilayer networks with Infomap. Algorithms, 10(4), 112. doi:10.3390/a10040112

Rosvall, M., & Bergstrom, C. T. (2008). Maps of random walks on complex networks reveal community structure. Proceedings of the National Academy of Sciences, 105(4), 1118-1123. doi:10.1073/pnas.0706851105

Lambiotte, R., & Rosvall, M. (2012). Ranking and clustering of nodes in networks with smart teleportation. Physical Review E, 85(5), 056107. doi:10.1103/PhysRevE.85.056107

Hubert, L., & Arabie, P. (1985). Comparing partitions. Journal of Classification, 2(1), 193-218. doi:10.1007/BF01908075

Examples

seqs <- list(c("a", "h", "b", "a", "h", "b", "a"),
             c("c", "h", "d", "c", "h", "d", "c"),
             c("a", "h", "b", "a", "h", "b"),
             c("c", "h", "d", "c", "h", "d"))
hon <- hon(seqs, max_order = 2L)
comm <- hg_communities(hon, trials = 3L)
comm
summary(comm)
hg_get(comm)
hg_get(comm, what = "physical")

Description

Reports graph-partition diagnostics on the association projection: unweighted coverage, weighted coverage, performance, weighted modularity, and conductance. Conductance is the maximum (worst) community conductance $cut(S, \bar S) / min(vol(S), vol(\bar S))$; lower is better.

Usage

hg_community_quality(
  hg,
  partition,
  method = c("association", "citation"),
  duplicate_edges = c("count", "collapse"),
  self_association = FALSE,
  edge_source = NULL
)

Arguments

Value

A one-row data frame.

References

Fortunato, S. (2010). Community detection in graphs. Physics Reports, 486(3-5), 75-174. doi:10.1016/j.physrep.2009.11.002

Newman, M. E. J., & Girvan, M. (2004). Finding and evaluating community structure in networks. Physical Review E, 69, 026113. doi:10.1103/PhysRevE.69.026113

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

Description

Tests whether two groups of sequences differ in their higher-order rule probabilities. The rule set is extracted from the pooled data of the two groups; for every pooled rule the statistic is the absolute difference of the two groups' conditional probabilities, and its null distribution comes from permuting the group labels over sequences. Per-rule p-values are Benjamini-Hochberg adjusted; a global test aggregates the rule differences weighted by pooled counts.

Usage

hg_compare(
  x,
  groups = NULL,
  n_perm = 1000L,
  alpha = 0.05,
  parallel = FALSE,
  n_cores = 2L,
  seed = NULL
)

Arguments

Details

A rule whose context one group never observes has no difference (diff is NA) and is not counted as zero. The global statistic is the pooled-count-weighted mean absolute difference over the comparable rules, those whose context both groups observe; in a permutation, a comparable rule whose context one permuted group lacks is left out of that permutation's mean. When no rule is comparable (the groups share no context), the statistic and its p-value are NA and the warning hypergraphs_undefined_statistic is raised.

Per-sequence counts are precomputed once and every permutation is a weighted aggregation; permutations are drawn before any parallel work, so parallel = TRUE reproduces the serial result under the same seed. Rules whose context is unobserved in a group under some permutation contribute only their valid permutations (n_perm_used).

Value

An object of class hypergraphs_comparison: a list with edges (one row per pooled rule: from, to, order, count, the two groups' counts and probabilities (columns named after the groups), diff (probability difference, first minus second), p_value, p_adj (BH), significant, n_perm_used), global (statistic, the pooled-count-weighted mean absolute difference over the comparable rules, p_value, n_comparable and n_rules, the comparable and pooled rules, and n_perm_used, the permutations with a defined statistic), names, n_perm, alpha, max_order, min_freq, n_trajectories (per group) and seed. Has print, summary and plot methods; hg_get() returns the rule table (significant = TRUE restricts it).

References

Xu, J., Wickramarathne, T. L., & Chawla, N. V. (2016). Representing higher-order dependencies in networks. Science Advances 2(5), e1600028. doi:10.1126/sciadv.1600028

Good, P. (2005). Permutation, Parametric and Bootstrap Tests of Hypotheses (3rd ed.). Springer.

Benjamini, Y., & Hochberg, Y. (1995). Controlling the false discovery rate. Journal of the Royal Statistical Society B, 57(1), 289-300. doi:10.1111/j.2517-6161.1995.tb02031.x

See Also

hon(), hg_bootstrap(), markov_order()

Examples

set.seed(1)
first_order <- replicate(6, sample(c("a", "b", "c"), 12, replace = TRUE),
                         simplify = FALSE)
second_order <- replicate(6, rep(c("a", "b", "c", "b"), 3),
                          simplify = FALSE)
by_group <- hon(c(first_order, second_order),
                group = rep(c("first", "second"), each = 6), max_order = 2)
comparison <- hg_compare(by_group, n_perm = 99, seed = 1)
comparison
hg_get(comparison, sort_by = "p_adj", top = 6)

Description

Sets several hg_communities() fits of the same data side by side, as the paper does for its eight GFCC representations (Coupette et al. 2024, Figure 8): the cluster-size distribution of each AMI medoid, the pairwise AMI, ARI and NMI between medoids, and per-fit summaries (number of communities, singletons, the balance between the two largest clusters).

Usage

hg_compare_communities(..., hg = NULL, edge_source = NULL)

## S3 method for class 'hypergraphs_community_comparison'
print(x, n = 10L, ...)

## S3 method for class 'hypergraphs_community_comparison'
hg_get(x, what = c("summary", "similarity", "sizes", "quality"), ...)

## S3 method for class 'hypergraphs_community_comparison'
plot(x, what = c("sizes", "similarity"), ...)

Arguments

Value

A hypergraphs_community_comparison object. hg_get() returns its "summary" (default; one row per fit with model, medoid_seed, n_communities, n_singletons, n_nontrivial, largest_size, second_size and balance = second / largest), "similarity" (one row per pair of fits with model_a, model_b, n_nodes, ami, ari, nmi, on the n_nodes nodes the two medoids share; with fewer than two shared nodes the three scores are NA and a hypergraphs_undefined_statistic warning is raised), "sizes" (one row per community of every medoid with model, rank, n_nodes) or, when hg was given, "quality" (one row per fit with the columns of hg_community_quality()). plot() draws the cluster-size distributions (what = "sizes", the number of communities at least as large as each size, on logarithmic axes) or the similarity matrix (what = "similarity", AMI below and ARI above the diagonal, values printed in the cells, on a diverging scale from -1 through 0 (white) to 1, since chance-corrected agreement can be negative; undefined cells are grey).

For plot, a ggplot object.

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

Examples

dat <- data.frame(
  member = c("a", "b", "c", "a", "b", "c", "x", "y", "z", "x", "y", "z"),
  edge = rep(paste0("e", 1:4), each = 3)
)
h <- group_hypergraph(dat, "member", "edge")
if (requireNamespace("igraph", quietly = TRUE)) {
  multi <- hg_communities(h, n_runs = 2, trials = 2, seeds = 1:2)
  binary <- hg_communities(h, n_runs = 2, trials = 2, seeds = 1:2,
                           duplicate_edges = "collapse")
  comparison <- hg_compare_communities(mh = multi, bh = binary)
  hg_get(comparison)
  hg_get(comparison, what = "similarity")
}

Description

How many simplices of each dimension contain each node.

Usage

hg_degree(sc, normalized = FALSE)

Arguments

Value

A base data.frame, one row per node, most connected first: node, one column per dimension (d0, d1, ...), and total (the simplices of dimension one and above). The same table is hg_get(sc, what = "degree").

References

Serrano, D. H., & Gomez, D. S. (2020). Centrality measures in simplicial complexes: Applications of topological data analysis to network science. Applied Mathematics and Computation, 382, 125331. doi:10.1016/j.amc.2020.125331

See Also

simplicial()

Examples

adj <- matrix(c(0, 1, 1, 0,
                1, 0, 1, 1,
                1, 1, 0, 1,
                0, 1, 1, 0), 4, 4, dimnames = list(letters[1:4], letters[1:4]))
hg_degree(simplicial(adj))

Description

For every pair of hyperedge sizes $s < t$ present in the hypergraph, the Pearson correlation across nodes between the size-$s$ hyperdegree (the number of size-$s$ hyperedges containing the node) and the size-$t$ hyperdegree, as reported by Lotito et al. (2023) for the high-school contact hypergraph ($\rho_{2,3}$, $\rho_{2,4}$, $\rho_{3,4}$). A high value means that nodes active in pairs are also active in larger groups.

Usage

hg_degree_correlation(hg)

Arguments

Details

Every node of hg enters every correlation (with degree 0 at the sizes it does not take part in). Sizes below two are ignored, as in hypergraphx. A pair is NA when one of the two sequences is constant. hypergraphx 1.8.0 degree_correlation() returns the full (max_size - 1)-square matrix, including sizes with no hyperedge (all NaN); hypergraphs returns one row per pair of sizes that occur. Tested against hypergraphx at 1e-12.

Value

A base data.frame, one row per pair of present hyperedge sizes size_1 < size_2, with columns size_1, size_2, correlation (Pearson, NA when undefined) and n_nodes.

Conditions

Raises hypergraphs_bad_input when hg is not a net_hg or has fewer than two distinct hyperedge sizes of at least two.

References

Lotito, Q. F., Contisciani, M., De Bacco, C., Di Gaetano, L., Gallo, L., Montresor, A., Musciotto, F., Ruggeri, N., & Battiston, F. (2023). Hypergraphx: a library for higher-order network analysis. Journal of Complex Networks, 11(3), cnad019. doi:10.1093/comnet/cnad019

See Also

hg_assortativity().

Examples

groups <- data.frame(
  member = c("a", "b", "a", "c", "b", "c", "a", "d",
             "a", "b", "c", "a", "b", "d", "c", "d", "e"),
  group  = c("p1", "p1", "p2", "p2", "p3", "p3", "p4", "p4",
             "t1", "t1", "t1", "t2", "t2", "t2", "t3", "t3", "t3")
)
hg <- group_hypergraph(groups, node = "member", hyperedge = "group")
hg_degree_correlation(hg)

Description

Codes each node by the hyperedges it belongs to. In a text hypergraph with documents as nodes, the hyperedges of a document are its words, or with text_hypergraph(separator = ";") its keywords, so a dictionary that lists the terms of each category labels every document that carries one of them. This is dictionary-based content analysis (Grimmer & Stewart 2013): the categories and their terms are the analyst's, and the labelling is a count. A node takes the category with the most matched terms. A node that matches no term, or matches two categories equally, takes no label, and a message reports how many. The result is the labels input of hg_classify() and hg_hypergat(), which spread or learn the labels to the nodes the dictionary cannot code.

Usage

hg_dictionary(hg, dictionary)

Arguments

Value

A base data.frame, one row per labelled node: node, label (the category), n_terms (how many of the category's terms the node carries) and terms (those terms, joined by "; "), ordered by label and node. Raises hypergraphs_bad_input for a malformed dictionary and warns with hypergraphs_unmatched_terms when a term of the dictionary is not a hyperedge of hg.

References

Grimmer, J., & Stewart, B. M. (2013). Text as data: The promise and pitfalls of automatic content analysis methods for political texts. Political Analysis, 21(3), 267-297. doi:10.1093/pan/mps028

Examples

papers <- data.frame(
  keywords = c("medical education; online learning",
               "teacher education; online learning",
               "medical students; assessment",
               "online learning; assessment")
)
kw <- text_hypergraph(papers, column = "keywords", separator = ";")
hg_dictionary(kw, dictionary = list(
  health = c("medical education", "medical students"),
  teachers = "teacher education"
))

Description

Hyperedges become vertices in the unweighted s-line graph: two are adjacent when they share at least s nodes. Betweenness and closeness are then ordinary shortest-path vertex centralities on that graph. At s = 1 these are the paper's hyperedge 1-betweenness and 1-closeness.

Usage

hg_edge_centrality(
  hg,
  s = 1L,
  measure = c("betweenness", "closeness"),
  normalized = TRUE,
  top = NULL,
  start = NULL,
  end = NULL,
  step = NULL,
  window = NULL,
  at = NULL,
  snapshot_mode = c("active", "cumulative"),
  multiedges = TRUE
)

Arguments

Value

A tidy data frame with edge, s, measure, and value; temporal input adds a leading time column, the snapshot time: a date for a calendar hypergraph, the number on its clock otherwise.

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

Examples

h <- group_hypergraph(
  data.frame(member = c("a", "b", "c", "b", "c", "d"),
             event = rep(c("e1", "e2"), each = 3)),
  "member", "event"
)
hg_edge_centrality(h, s = 1)

Description

One row per hyperedge. hg_measures(what = "edges") reports cardinality alone; this adds the incident weight, how many other hyperedges a hyperedge meets, and how large its vertex neighbourhood is — the hyperedge-side counterparts of degree and neighbourhood size, and the descriptive layer used to characterise higher-order structure (Coupette et al. 2024). A temporal hypergraph is evaluated snapshot by snapshot, with a leading time column, so the distribution of hyperedge sizes at several dates (the paper's Figure 4b) or the neighbourhood size of a tribunal over time (Figure 5c) come from one call.

Usage

hg_edges(
  hg,
  what = c("edges", "distribution", "summary"),
  measure = c("size", "weight", "n_incident_edges", "n_neighbors"),
  s = 1L,
  start = NULL,
  end = NULL,
  step = NULL,
  window = NULL,
  at = NULL,
  snapshot_mode = c("active", "cumulative"),
  multiedges = TRUE
)

Arguments

Value

With what = "edges", a base data.frame with one row per hyperedge and columns edge (name), size (integer, vertices it contains), weight (numeric, its incidence weights summed), n_incident_edges (integer, other hyperedges sharing at least s vertices) and n_neighbors (integer, vertices adjacent to a member without being one). With what = "distribution", a hypergraphs_distribution table with one row per distinct observed value of measure, ascending, with columns value, n, proportion and ccdf — the complementary cumulative distribution $P(X \ge value)$, so the first row's ccdf is always 1; its plot() draws the CCDF. With what = "summary", one row with n_edges, mean, sd, min, q25, median, q75 and max. Several s values add an s column; temporal input adds a leading time column, and the summary is then a hypergraphs_series whose plot() draws each statistic against time.

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

See Also

hg_measures() for vertex-level measures, hg_line_graph() for the graph whose degrees n_incident_edges reports.

Examples

hg <- text_hypergraph(c(a = "salt and soup", b = "soup and stars",
                        c = "stars and salt"))
hg_edges(hg)
hg_edges(hg, what = "distribution")
hg_edges(hg, what = "summary", measure = "n_neighbors")

Description

Returns the node coordinates computed by hypergraphs' existing hypergraph spectral or symmetric-NMF engine without exposing the incidental k-means assignments produced by hg_cluster().

Usage

hg_embed(
  hg,
  dimensions = 2L,
  type = c("zhou", "random_walk"),
  method = c("spectral", "symnmf"),
  seed = NULL,
  nstart = 25L,
  max_iter = 500L,
  tol = 1e-06
)

Arguments

Value

A data frame with node, stationary mass pi, and dim1 through ⁠dim<dimensions>⁠.

References

Zhou, D., Huang, J., & Schölkopf, B. (2006). Learning with hypergraphs: clustering, classification, and embedding. Advances in Neural Information Processing Systems 19. doi:10.7551/mitpress/7503.003.0205

Hayashi, K., Aksoy, S. G., Park, C. H., & Park, H. (2020). Hypergraph random walks, Laplacians, and clustering. Proceedings of the 29th ACM International Conference on Information and Knowledge Management, 495-504. doi:10.1145/3340531.3412034

Examples

h <- group_hypergraph(
  data.frame(node = c("a", "b", "c", "b", "c", "d"),
             edge = rep(c("e1", "e2"), each = 3)),
  "node", "edge"
)
hg_embed(h, dimensions = 2)

Description

$\chi = \sum_k (-1)^k f_k$, the alternating sum of the number of k-simplices; by the Euler-Poincare theorem it equals the alternating sum of the Betti numbers.

Usage

hg_euler(sc)

Arguments

Value

A single integer.

References

Hatcher, A. (2002). Algebraic Topology. Cambridge University Press.

See Also

hg_betti()

Examples

adj <- matrix(c(0, 1, 1, 0,
                1, 0, 1, 1,
                1, 1, 0, 1,
                0, 1, 1, 0), 4, 4, dimnames = list(letters[1:4], letters[1:4]))
hg_euler(simplicial(adj))

Description

hg_get() is the single reader of the package. Every object a constructor or a verb returns – a hypergraph, a memory network, a simplicial complex, an inference or a community result – hands over its tables through hg_get(), never through $. ⁠what =⁠ selects the table; what = NULL (the default) returns the object's primary table. Filters, orderings and ⁠top =⁠ are named arguments of the method for that class.

Usage

hg_get(x, what = NULL, ...)

## Default S3 method:
hg_get(x, what = NULL, ...)

## S3 method for class 'net_hg_pairwise'
hg_get(x, what = c("edges", "nodes"), ..., sort_by = NULL, top = NULL)

Arguments

Value

A base data.frame, one row per observation of the selected table. An object of a class without a method raises hypergraphs_bad_input, naming the class.

Tables by class

net_hg (hypergraphs)

"edges" (default), "nodes", "memberships", "sets", "state_counts", "edge_data"; see hg_get.net_hg().

text_hypergraph

"weights" (default), "documents", "vocabulary", "sentences"; see hg_get.text_hypergraph().

hg_hypergat

Predictions (default), evaluation, document text, history and optional attention; see hg_get.hg_hypergat().

net_temporal_hypergraph

"memberships" (default), "edges", "nodes".

net_hon (hon())

"rules" (default), "nodes", "pathways".

net_honem (honem())

"embeddings" (default), "variance".

net_hypa (hypa() on sequences)

"anomalies" (default), "scores", "over", "under", "pathways".

net_mogen (mogen())

"orders" (default), "transitions", "paths", "pathways".

net_markov_order (markov_order())

"orders" (default), "null".

net_path_dependence (memory())

"contexts".

net_markov_stability (hg_markov_stability())

"states" (default), "passage_time", "stationary".

hypergraphs_bootstrap (hg_bootstrap())

"edges".

hypergraphs_comparison (hg_compare())

"edges".

hypergraphs_memory_communities (hg_communities() on a memory network)

"states" (default), "physical", "modules", "codelength", "trials".

simplicial_complex (simplicial())

"simplices" (default), "f_vector", "degree".

q_analysis (hg_qanalysis())

"q_levels" (default), "nodes".

persistent_homology (hg_homology())

"persistence" (default), "betti".

persistence_landscape (hg_landscape())

"landscape".

hg_communities (hg_communities() on a hypergraph)

see hg_get.hg_communities().

hypergraphs_community_comparison, hypergraphs_motifs, net_hg_mmsbm

see their methods.

Examples

hg <- window_hypergraph(list(s1 = c("a", "b", "a", "c")), window = 2L)
hg_get(hg)
hg_get(hg, what = "nodes")

seqs <- list(c("a", "b", "c", "a", "b", "c"), c("x", "b", "d", "x", "b", "d"))
hg_get(hon(seqs, max_order = 2), what = "nodes")

Description

hg_classify() and hg_hypergat() with holdout return an hg_classification: one row per document with its true label, its predicted label, its split and whether a held-out prediction is correct. hg_get() reads the evaluation tables, and for hg_hypergat() the diagnostic attention of the trained network, computed on request.

Usage

## S3 method for class 'hg_classification'
hg_get(
  x,
  what = c("predictions", "accuracy", "classes", "confusion", "hyperedges",
    "hyperedge_words", "documents"),
  split = NULL,
  correct = NULL,
  node = NULL,
  sort_by = NULL,
  top = NULL,
  ...
)

## S3 method for class 'hg_classification'
print(x, ...)

## S3 method for class 'hg_classification'
summary(object, ...)

## S3 method for class 'hg_classification'
plot(x, y, type = c("confusion", "hyperedges"), node = NULL, top = 8L, ...)

Arguments

Value

A base data.frame as described under what. print() shows the held-out accuracy and the per-class table and returns x invisibly; summary() returns the per-class table; plot() returns a ggplot of the confusion table (type = "confusion") or of the heaviest hyperedges of some documents (type = "hyperedges").

References

Brodersen, K. H., Ong, C. S., Stephan, K. E., & Buhmann, J. M. (2010). The balanced accuracy and its posterior distribution. Proceedings of the 20th International Conference on Pattern Recognition, 3121-3124. doi:10.1109/ICPR.2010.764

Ding, K., Wang, J., Li, J., Li, D., & Liu, H. (2020). Be more with less: Hypergraph attention networks for inductive text classification. EMNLP 2020, 4927-4936.

Examples

hg <- text_hypergraph(head(forum_posts, 60), column = "text")
fit <- hg_classify(hg, labels = "topic", holdout = 0.25)
fit
hg_get(fit, what = "classes")
hg_get(fit, what = "confusion")
hg_get(fit, split = "test", correct = FALSE)

Description

The classifier retains its trained network, vocabulary and topic keywords. Reading a table or predicting new documents never trains the network. Attention tables describe internal aggregation weights. They are not class-specific contributions or explanations of a prediction.

Usage

## S3 method for class 'hg_hypergat'
hg_get(
  x,
  what = NULL,
  split = NULL,
  correct = NULL,
  node = NULL,
  sort_by = NULL,
  top = NULL,
  ...
)

## S3 method for class 'hg_hypergat'
print(x, ...)

## S3 method for class 'hg_hypergat'
summary(object, ...)

## S3 method for class 'hg_hypergat'
plot(
  x,
  y,
  type = c("confusion", "history", "hyperedges", "attention"),
  node = NULL,
  top = 8L,
  ...
)

Arguments

Value

A plain data frame. The attention tables include uniform normalization baselines: word_uniform = 1 / n_words within an edge, and edge_uniform = 1 / n_edges for a word. Hyperedge summaries include uniform_weight (mean edge_uniform) and exclusive_fraction (the fraction of words belonging only to that hyperedge). Such words have edge_weight = 1 regardless of the learned parameters.

References

Ding, K., Wang, J., Li, J., Li, D., & Liu, H. (2020). Be more with less: Hypergraph attention networks for inductive text classification. EMNLP 2020, 4927-4936.

Description

Inference table of a memory-network bootstrap

Usage

## S3 method for class 'hypergraphs_bootstrap'
hg_get(
  x,
  what = "edges",
  ...,
  min_support = NULL,
  order_min = NULL,
  sort_by = NULL,
  top = NULL
)

Arguments

Value

A data.frame, one row per rule edge: from, to, order, count, probability, ci_lower, ci_upper, support, n_boot_used.

Description