ubergraph

Ubergraph is a versatile, general-purpose graph data structure for Clojure. It is designed to be compatible with Loom protocols but provides advanced capabilities that exceed standard Loom implementations.

Key features include:

• Support for directed, undirected, and weighted edges.
• Support for node and edge attributes.
• Ability to mix directed and undirected edges within a single graph.
• Support for multiple "parallel" edges between a pair of nodes.
• Support for multiple weights per edge and changeable weights.
• Full implementation of all Loom protocols.

In a multigraph, multiple edges can exist between the same src and dest. To uniquely identify an edge, Ubergraph uses "edge descriptions".

Edge Description Formats:

• [src dest]
• [src dest weight]
• [src dest attribute-map]

When using a description, Ubergraph will pick an edge that matches the description. If the description is unique (e.g., includes a specific color attribute), it will target that specific edge.

Example:

;; If multiple edges exist between 1 and 4, this targets the red one:
(weight g [1 4 {:color :red}])

;; Targets the edge from :a to :b with weight 5 to get its :color attribute:
(attr g [:a :b 5] :color)

Ubergraph provides four distinct graph types based on how they handle edge directionality and parallel edges. While they share the same underlying representation, their default behaviors differ:

Note: You can override these defaults. For example, you can add directed edges to an undirected graph using add-directed-edges, or undirected edges to a directed digraph using add-undirected-edges.

If you provide only a :start-node to alg/shortest-path, it returns an AllPathsFromSource object. This acts as an efficient lookup table for all shortest paths emanating from that source.

Key Operations

• Find path to specific node: Use alg/path-to with the lookup table.
• List all reachable nodes: Use alg/all-destinations.
• Sequence of discovery: Set :traverse true to get a sequence of path objects in the order they were discovered by the search algorithm.
• Constrained Traversal: When using :traverse true, you can use :min-cost and :max-cost to filter the sequence of discovered paths.

(def out-of-coulton (alg/shortest-path airports {:start-node :Coulton, :cost-attr :distance}))

;; Get path to a specific node
(alg/path-to out-of-coulton :Artemis)

;; Get all reachable destinations
(alg/all-destinations out-of-coulton)

When serializing or representing graph data, you can choose between two conceptual approaches depending on whether you need to preserve identity or minimize footprint:

• Option 1 (Reconstructible): Stores only the sufficient information required to rebuild an equivalent ubergraph. This approach is more compact and highly compatible with various serialization libraries. Note that in this mode, UUIDs for nodes and edges will change upon reconstruction, though the underlying nodes, edges, and attributes will remain identical in content.
• Option 2 (Identity-Preserving): Captures the exact UUIDs from the existing graph and preserves any cached hash values. Use this option when maintaining specific node/edge identities across serialization cycles is required.

Require ubergraph.core in your namespace. For convenience, ubergraph.core provides access to all of Loom's protocol functions through its own namespace, allowing you to call functions like out-edges or add-attr directly from the uber alias instead of importing multiple Loom namespaces.

(ns example.core
  (:require [ubergraph.core :as uber]))

To use Ubergraph in your Clojure project, add it to your project.clj dependencies. Note that Ubergraph depends on Loom, so Loom will be automatically downloaded and available in your project.

[ubergraph "0.9.0"]

Use uber/viz-graph from the ubergraph.core namespace to create a visualization of your graph. This requires GraphViz to be installed on your system.

Basic Usage

(uber/viz-graph airports)

Saving to a file

Pass an options map with a :save key containing :filename and :format (e.g., :png, :pdf).

(uber/viz-graph airports {:save {:filename "C:/temp/airports.png" :format :png}})

Customization Options

• Layout Algorithm: Specify a Graphviz layout using :layout (e.g., :neato).
• Auto-labeling: Use :auto-label true to annotate all nodes and edges with their attribute maps.
• Attribute Integration: If node or edge attribute maps contain Graphviz-compatible keys (like :color or :style), Graphviz will automatically use them for drawing.