caugi

Causal Graph Interface (for R) — a fast and flexible toolbox for building, coercing and analyzing causal graphs.

What is caugi?

caugi (pronounced “corgi”) stands for Causal Graph Interface. It is a causality-first graph package that focuses on performance and flexibility. If you are developing scripts or algorithms in the field of causality or if you are learning about causal graphs for the first time, caugi is made for you.

Installation

You can install the development version of caugi from GitHub with:

pak::pak("frederikfabriciusbjerre/caugi")

or directly from CRAN with:

install.packages("caugi")

Installing Rust

Rust is required for caugi to work. If you don’t have Rust installed, visit rustup.rs for installation instructions appropriate for your platform.

Alternatively, you may install Rust from your OS package manager.

The basic object: caugi

A caugi graph object is the bread and butter of the caugi package. It is easy to create, query, and modify.

library(caugi)

You can create simple graphs as well as a number of predefined graph classes. Currently, we support "UNKNOWN", "DAG", "PDAG", "ADMG", and "UG". We plan on supporting several other causal graph types in future releases, such as "PAG", "MAG", and "SWIG".

# a tiny DAG
cg <- caugi(
  A %-->% B + C,
  B %-->% D,
  C %-->% D,
  class = "DAG"
)

plot(cg)

Edge operators

The available edges in caugi are listed below:

• %-->% (directed)
• %---% (undirected)
• %<->% (bidirected)
• %o->% (partially directed)
• %o--% (partially undirected)
• %o-o% (partial)

You can register more types with register_caugi_edge(), if you find that you need a more expressive set of edges. For example, if you want to represent a directed edge in the reverse direction, you can do so like this:

register_caugi_edge(
  glyph = "<--",
  tail_mark = "arrow",
  head_mark = "tail",
  class = "directed",
  symmetric = FALSE
)

caugi(A %-->% B, B %<--% C, class = "DAG")
#> <caugi object; 3 nodes, 2 edges; simple: TRUE; session=0x000001a2318f5e90>
#>   graph_class: DAG
#>   nodes: A, B, C
#>   edges: A-->B, B<--C

# reset the registry to default with original edges
reset_caugi_registry()

We expect this feature to be needing further polishing in future releases, and we would love your input if you use this feature!

Querying and metrics

caugi provides a number of functions to query and analyze caugi objects. Some of the available functions are:

• Relational queries, such as parents(), ancestors(), neighbors(), and more.
• Structural queries, such as is_acyclic(), is_cpdag(), and more.
• Graph manipulations, such as add_edges(), remove_nodes(), and more.
• Graph metrics, such as shd() and aid().

How it works

caugi graphs are represented in a compact Compressed Sparse Row (CSR) format in Rust. caugi works with a front-loading philosophy. Since the caugi graph is stored in a CSR format, mutations of the graph is computationally expensive compared to other graph storage systems, but it allows for very fast querying. Additionally to the storage format of the graph itself, caugi also stores additional information about node relations in such a way that it allows for faster queries without blowing up the object too much.

To accommodate for the cost of mutations, caugi graphs are built lazily, but you can force a build by using the function build().

Why?

It’s fast, dawg 🐶 See the article on performance on our website for benchmarks.

Contribution

Would you like to contribute? Great! Please see Contributing to caugi for detailed guidelines on code style, testing, and the development workflow. Quick tips: follow the tidyverse style guide for R code, run styler::style_pkg() for R and cargo fmt for Rust before PRs, and write tests for new features.

Did you find run into problems? That’s paw-ful! Please report an issue!