Struct NarrativeGraph 

pub struct NarrativeGraph { /* private fields */ }

A directed graph representing events and their relationships.

The graph uses petgraph internally and provides methods for:

• Adding events as nodes
• Connecting events with typed edges
• Querying paths and neighbors
• Subgraph extraction

Implementations

impl NarrativeGraph

pub fn new() -> Self

Create an empty narrative graph.

pub fn from_events(events: impl IntoIterator<Item = Event>) -> Self

Create a graph from a vector of events.

Events are added as nodes but no edges are created.

pub fn add_event(&mut self, event: Event) -> NodeId

Add an event as a node in the graph.

Returns the NodeId for the newly added node.

pub fn get_node(&self, event_id: &EventId) -> Option<NodeId>

Get the NodeId for an event by its EventId.

pub fn event(&self, node: NodeId) -> Option<&Event>

Get the event at a node.

pub fn event_mut(&mut self, node: NodeId) -> Option<&mut Event>

Get a mutable reference to the event at a node.

pub fn connect(&mut self, from: NodeId, to: NodeId, edge_type: EdgeType)

Connect two events with an edge.

pub fn connect_weighted(&mut self, from: NodeId, to: NodeId, weight: EdgeWeight)

Connect two events with a weighted edge.

pub fn are_connected(&self, from: NodeId, to: NodeId) -> bool

Check if two nodes are connected (directly).

pub fn has_path(&self, from: NodeId, to: NodeId) -> bool

Check if there’s a path between two nodes.

pub fn successors(&self, node: NodeId) -> Vec<NodeId>

Get all outgoing neighbors of a node.

pub fn predecessors(&self, node: NodeId) -> Vec<NodeId>

Get all incoming neighbors of a node.

pub fn node_count(&self) -> usize

Get the number of nodes.

pub fn edge_count(&self) -> usize

Get the number of edges.

pub fn is_empty(&self) -> bool

Check if the graph is empty.

pub fn nodes(&self) -> impl Iterator<Item = (NodeId, &Event)>

Iterate over all nodes.

pub fn edges(&self) -> impl Iterator<Item = (NodeId, NodeId, &EdgeWeight)>

Iterate over all edges.

pub fn shortest_path(&self, from: NodeId, to: NodeId) -> Option<PathInfo>

Find the shortest path between two nodes.

Returns path information including the sequence of nodes and total weight.

pub fn edges_of_type(&self, edge_type: EdgeType) -> Vec<(NodeId, NodeId)>

Get edges of a specific type.

pub fn connect_temporal(&mut self)

Automatically connect events based on temporal sequence.

Creates edges from earlier events to later events.

pub fn connect_spatial(&mut self, max_distance_km: f64)

Automatically connect events that are spatially close.

Creates edges between events within the given distance threshold (in meters).

pub fn connect_thematic(&mut self)

Automatically connect events that share tags.

pub fn subgraph_temporal(&self, range: &TimeRange) -> SubgraphResult

Extract a subgraph containing only events within a time range.

pub fn subgraph_spatial(&self, bounds: &GeoBounds) -> SubgraphResult

Extract a subgraph containing only events within geographic bounds.

pub fn in_degree(&self, node: NodeId) -> usize

Get the in-degree of a node (number of incoming edges).

pub fn out_degree(&self, node: NodeId) -> usize

Get the out-degree of a node (number of outgoing edges).

pub fn roots(&self) -> Vec<NodeId>

Find nodes with no predecessors (roots/sources).

pub fn leaves(&self) -> Vec<NodeId>

Find nodes with no successors (leaves/sinks).

pub fn to_dot(&self) -> String

Export the graph to DOT format (Graphviz).

The DOT output can be rendered with Graphviz tools like dot, neato, etc.

Example

use spatial_narrative::graph::{NarrativeGraph, EdgeType};
use spatial_narrative::core::{Event, Location, Timestamp};

let mut graph = NarrativeGraph::new();
let e1 = Event::new(Location::new(40.7, -74.0), Timestamp::now(), "Event 1");
let e2 = Event::new(Location::new(40.8, -74.1), Timestamp::now(), "Event 2");
let n1 = graph.add_event(e1);
let n2 = graph.add_event(e2);
graph.connect(n1, n2, EdgeType::Temporal);

let dot = graph.to_dot();
assert!(dot.contains("digraph"));

pub fn to_dot_with_options(&self, options: DotOptions) -> String

Export the graph to DOT format with custom options.

pub fn to_json(&self) -> String

Export the graph to JSON format.

Returns a JSON object with nodes and edges arrays.

pub fn to_json_pretty(&self) -> String

Export to JSON with pretty printing.

Trait Implementations

impl Debug for NarrativeGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NarrativeGraph

fn default() -> Self

Returns the “default value” for a type.