rhype: A Flexible Package For Working With Hypergraphs In R

Introduction

rhype is a package for working with hypergraphs in R. It works under the general idea that data can be transformed into a hypergraph object and then there are many functions to manipulate and analyse this hypergraph object.

Installation

rhype is available from CRAN using

install.packages("rhype")

or the development version is available from GitHub using

remotes::install_github("hwarden162/rhype")

Getting Started

To get started with rhype, see these blog posts:

• Working With Hypergraphs In R
• Estimating Heterogeneity of scRNA-seq Data With rhype

Within rhype, there comes a new environment that saves all the information about a hypergraph. There are multiple functions for creating hypergraphs from your own data, but as well as this there is a function for generating example hypergraphs to test pipelines and run proof of concepts.

library(rhype)

hype <- example_hype()
hype
#> Hypergraph Object: 
#>     Number of vertices:  4 
#>     Number of hyperedges:  2 
#>     Oriented:  FALSE    Directed:  FALSE 
#>     Real Coefficients:  FALSE    Weighted:  FALSE

This is the basic output that a hypergraph object will print to the screen. To get more information, you can use the hype_info function, although this may be quite large for large hypergraphs.

hype_info(hype)
#> ====================HYPERGRAPH INFORMATION====================
#> 
#> --------------------VERTEX INFORMATION--------------------
#> 
#> This hypergraph has  4  vertices
#> 
#> These vertices are called:
#>  v1, v2, v3, v4 
#> 
#> --------------------HYPEREDGE INFORMATION--------------------
#> 
#> The hyperedges are called:
#>  h1, h2 
#> 
#> The hyperedges have the structure:
#> $h1
#> [1] 1 2 3
#> 
#> $h2
#> [1] 2 3 4
#> 
#> ---------------WEIGHTING INFORMATION--------------------
#> 
#> This hypergraph is not weighted
#> 
#> --------------------Orientation Information--------------------
#> 
#> This hypergraph is not oriented
#> 
#> This hypergraph is not directed
#> 
#> --------------------REAL COEFFICIENTS INFORMATION--------------------
#> 
#> This hypergraph does not have real coefficients associating vertices to hyperedges
#> 
#> There is no incidence matrix associating vertices to hyperedges with non-binary coefficients

Hypergraphs can be abstracted in many ways and can quickly become complicated, rhype is designed to make these abstractions as simple to work with as possible and design a simple interface to working with with many common hypergraph applications. An example of a very complex hypergraph:

hype1 <- example_hype(
  oriented = TRUE,
  directed = TRUE,
  vertex_weighted = TRUE,
  edge_weighted = TRUE,
  real_coef = TRUE
)

hype_info(hype1)
#> ====================HYPERGRAPH INFORMATION====================
#> 
#> --------------------VERTEX INFORMATION--------------------
#> 
#> This hypergraph has  4  vertices
#> 
#> These vertices are called:
#>  v1, v2, v3, v4 
#> 
#> --------------------HYPEREDGE INFORMATION--------------------
#> 
#> The hyperedges are called:
#>  h1, h2 
#> 
#> The hyperedges have the structure:
#> $h1
#> $h1$from
#> [1] 1 2
#> 
#> $h1$to
#> [1] 3 4
#> 
#> 
#> $h2
#> $h2$from
#> [1] 2 3 4
#> 
#> $h2$to
#> [1] 1 2
#> 
#> 
#> ---------------WEIGHTING INFORMATION--------------------
#> 
#> This hypergraph is weighted
#> 
#> The hyperedges have weights:
#> h1 h2 
#>  1  2 
#> 
#> The vertices have weights:
#> v1 v2 v3 v4 
#>  1  2  3  4 
#> 
#> --------------------Orientation Information--------------------
#> 
#> This hypergraph is oriented
#> 
#> This hypergraph is directed
#> 
#> --------------------REAL COEFFICIENTS INFORMATION--------------------
#> 
#> This hypergraph has real coefficients associating vertices to hyperedges
#> 
#> The incidence matrix associating vertices to hyperedges is given by:
#> $from
#>    h1 h2
#> v1  1  0
#> v2  2  2
#> v3  0  3
#> v4  0  4
#> 
#> $to
#>    h1 h2
#> v1  0  1
#> v2  0  2
#> v3  3  0
#> v4  4  0

rhype lowers the in level of technical knowledge needed for working with hypergraphs, providing a simple interface for exploring higher order interactions.

Advanced Functionality

Hypergraph objects are R6 objects that have inherent properties describing their structure. These properties are private and need to be changed via public getter and setter functions, although at the moment these have no validation on them as this is taken care of within other functions.

The inherent properties of a hypergraph are:

numv: The number of vertices in the hypergraph

elist: The hyperedge list, a list of the vertices contained in each hyperedge this structure is slightly more complicated for oriented hypergraphs)

vnames: A vector of names of the vertices

vweights: A vector of weights of the vertices

enames: A vector of names of the hyperedges

eweights: A vector of weights of the hyperedges

weighted: Whether the hypergraph is weighted (a hypergraph is weighted if it has either or both vertex or hyperedge weights)

oriented: Whether the hypergraph is oriented

directed: Whether the hypergraph is directed (all directed hypergraphs are oriented)

real_coef: Whether the hypergraph has real coefficients associating vertices to hyperedges

inc_mat: A matrix of the real coefficients associating vertices to hyperedges, only present for hypergraphs with real coefficients (has a slightly different structure for oriented hypergraphs)

It is encouraged to use these functions if rhype does not currently cater to your analytical needs, however, the way in which hypergraphs are represented may be changed and therefore so might these functions. This means that there is no guarantee these functions will be present or work in the same way in the future. If you are doing something that is not currently supported in rhype please wrap it in a function and make a pull request to the GitHub repo, then the code will always be maintained and tested to work in future versions.

These properties of the hypergraph interact with one another and so therefore making changes can break the integrity of the hypergraph object, causing further functions to fail. If you are changing the object directly and something is not working the validate_hypergraph() function is supplied as a first point of call for troubleshooting.

hype <- example_hype(
  oriented = FALSE,
  directed = FALSE,
  edge_weighted = TRUE,
  vertex_weighted = TRUE
)

hype$set_directed(TRUE)
hype$set_numv(50)

validate_hypergraph(hype)
#>   There are 3 serious problems with this hypergraph:
#>   ✖ The number of vertices is not equal to the length of the vector containing the vertex names. 
#>  ✖ The number of vertices is not equal to the length of the vector containing the vertex weights and the hypergraph is weighted. 
#>  ✖ The hypergraph is directed but not oriented.
#>  There are 1 items that need your attention with this hypergraph:
#>   ℹ The number of vertices recorded and the number of vertices contained in the hyperedge list is different. This is expected if and only if you have an isolated vertex in your hypergraph. 
#>  These tests are not exhaustive, just an indication of where things might be going wrong.

As well as outputting to the screen this can also be used as a part of a validation function by setting it to return a boolean

validate_hypergraph(hype, return = TRUE, verbose = FALSE)
#> [1] FALSE