Skip to content

Causal Graphs

Causality extraction (see Tasks) identifies causal relationships claimed in natural language text. Causal graphs aggregate such relations (one edge per cause → effect pair) into a knowledge graph that can be queried, traversed, and used as background knowledge (for example to look up whether a candidate cause/effect pair is already attested, or to expand a seed concept along its causal neighborhood).

causalatee.graph provides:

  • A small, typed Graph / Node / Edge interface that every backend below implements, so code written against it works regardless of how a graph is stored.
  • load_causenet, an eager loader for the CauseNet causality graph and other compatible JSONL resources.
  • load_cause_effect_graph, a loader for the Lexical Cause-Effect Graph (CEG) format, mined at CausalBank scale.
  • CGF (Causal Graph Format), a compact, memory-mappable binary format for storing a Graph on disk and traversing it without materializing it in Python objects — see the CGF 1.0 specification for the full format.
  • SQLGraph, a generic, mutable, SQLite-backed Graph you build yourself via add_node/add_edge — unlike the loaders above, it has no external source to load from (causalatee.mining.GraphSink uses one as its storage engine).

Quick start

from causalatee.graph import load_causenet, save_cgf, load_cgf

# Eagerly load a (bounded) slice of CauseNet into memory.
graph = load_causenet("causenet-precision.jsonl.bz2", limit=10_000)

# Convert it to CGF. The writer streams through a disk-backed sort, so memory
# use does not grow with the number of edges.
save_cgf(graph, "causenet.cgf")

# Memory-map the CGF file: nodes and edges are resolved lazily from disk.
with load_cgf("causenet.cgf", validate=True) as mapped:
    rain = mapped.get_node("rain")
    for edge in rain.outgoing_edges():
        print(edge.target.id, edge.metadata["support"])

Graph implementations are interchangeable: save_cgf accepts any Graph, not just a CauseNet instance, and a CGFGraph loaded back with load_cgf is itself a Graph that can be passed to save_cgf again (e.g. to add or drop the incoming-edge index).

Choosing a backend

CauseNet CGFGraph
Loaded from Local or remote JSONL (optionally gzip/bzip2) A local .cgf file
Memory use Whole selection materialized as Python objects Memory-mapped; independent of graph size
Node/edge lookup Python dict Binary search / CSR offsets
Best for Building a graph, small samples, one-off exploration (limit=...) Repeatedly querying or traversing a large graph

In short: use load_causenet to build a graph from the source data, then save_cgf to persist it once for fast, low-memory access afterwards via load_cgf.

Example

See the CauseNet and CGF notebook for a runnable walkthrough of loading a CauseNet sample, saving it as CGF, and loading it back.

Supported Causal Graphs

  • CauseNet

    CauseNet is a large-scale causality graph extracted from web and Wikipedia text, mapping cause concepts to effect concepts with supporting evidence for each relation.

    View details →

  • CGF

    CGF (Causal Graph Format) is causalatee's own compact, memory-mappable binary format for storing a causal graph on disk and traversing it without materializing it in Python objects.

    View details →

  • CauseEffectGraph

    The Lexical Cause-Effect Graph (CEG) is a word-level cause/effect graph mined at CausalBank scale, with an occurrence count and two causal-strength scores ("necessity" and "sufficiency") per pair.

    View details →

  • SQLGraph

    SQLGraph is causalatee's generic, mutable, SQLite-backed causal graph, for building a graph incrementally rather than loading one from an existing external resource.

    View details →

API Reference

See causalatee.graph for the full API.