Graph Exchange File Format

GEFF is a specification for a file format for exchanging spatial graph data. It is not intended to be mutable, editable, chunked, or optimized for use in an application setting.

This repository contains two packages:

• geff-spec is the specification of GEFF metadata written with pydantic BaseModels which are exported to a json schema for use in other languages.
• geff is the python library that reads and writes GEFF files to and from several python in-memory graph data structures (networkx, rustworkx and spatial-graph).

Learn more in the documentation or check out the source code.

Installation

pip install geff

or

conda install conda-forge::geff

Quick Start

For this example, we will use a simple networkx graph, but geff can write graphs created with networkx, rustworkx and spatial-graph.

import networkx as nx

# Create a simple networkx graph with 10 nodes connected sequentially
node_ids = range(10)
nodes = []
for t, node in enumerate(node_ids):
    # Each node has an attribute "t"
    nodes.append((node, {"t": t}))

edges = []
for i in range(len(node_ids) - 1):
    # Each edge has an attribute "color"
    edges.append((node_ids[i], node_ids[i + 1], {"color": "red"}))

graph = nx.DiGraph()
graph.add_nodes_from(nodes)
graph.add_edges_from(edges)

The simplest geff requires only a graph.

from geff import write, read

write(
    graph,
    "simple.geff",
    zarr_format=2  # 2 or 3
)

read_graph = read(
    "simple.geff",
    backend="networkx"  # or "spatial-graph" or "rustworkx"
)

Basic metadata about spatial-temporal axes can be included in the write function call. Additional metadata defined in the geff-spec can be included by creating a GeffMetadata object.

write(
    graph,
    "simple-metadata.geff",
    axis_names=["t"],
    axis_units=["second"],
    axis_types=["time"]
)