Rai Graph Analysis

Graph Analysis

• Summary
• Quick Reference
• Graph Analysis Workflow
• Graph Construction from Ontology
• Parameter Guidance
• Domain Constraints
• Result Extraction and Binding
• Downstream Use
• Common Pitfalls
• Examples
• Reference Files

Summary

What: Graph algorithm selection and execution — building Graph instances from PyRel ontology patterns and running the right algorithm to answer structural questions about the data.

When to use:

• Building a Graph instance from an existing PyRel model (choosing node concept, edge construction, directed/weighted)
• Selecting which graph algorithm answers a given question (centrality, community, reachability, etc.)
• Configuring algorithm parameters (direction, weights, aggregator)
• Extracting and binding graph results to model properties
• Feeding graph outputs into downstream reasoning (optimization, rules, predictions)

When NOT to use:

• Discovering whether graph analysis is appropriate for a dataset — see rai-discovery
• PyRel syntax reference (imports, types, model patterns) — see rai-pyrel
• Ontology design decisions (concept modeling, data mapping) — see rai-ontology
• Optimization formulation (variables, constraints, objectives) — see rai-prescriptive-problem
• Business rule authoring (validation, classification, alerting) — see rai-pyrel
• GNN graph construction for predictive pipelines — see rai-predictive-modeling

Overview (process steps):

1. Study the existing model — understand base definitions, coding conventions, and what's already wired
2. Start from the question — identify which concepts and relationships are relevant, and what kinds of analysis best speak to the question
3. Determine which relevant concepts should constitute nodes in the graph
4. Determine what edges would best capture the information relevant to the question and the planned analysis
5. Figure out how to derive those edges from the relevant relationships (sometimes a pass-through, often involving filters or more substantial logic)
6. Choose which Graph constructor pattern fits given the node/edge decisions
7. Select the specific algorithm(s) best suited to the question
8. Execute, extract results, and blend back into the model for downstream use

Quick Reference

# Imports
from relationalai.semantics import Model, Float, Integer, String, where, define, data
from relationalai.semantics.reasoners.graph import Graph
from relationalai.semantics.std import aggregates, floats

model = Model("my_model")

Note: where, define, and data are available as standalone imports and as model.where(), model.define(), model.data() methods. Both are equivalent for single-model scripts. Use the model.* form when multiple Models exist — standalone functions fail with "Multiple Models have been defined.". See rai-pyrel for data loading patterns with model.data().

Graph constructor — three patterns

Pattern 1: No existing node or edge concepts — the most common pattern. Use when nodes are drawn from multiple concepts, or when not all instances of a concept should be nodes. Edges are defined manually with Edge.new().

graph = Graph(
    model,
    directed=True|False,          # Edge directionality
    weighted=True|False,          # Whether edges carry weights
)
Node, Edge = graph.Node, graph.Edge
# Define nodes and edges manually with Edge.new(src=..., dst=...)

Pattern 2: Existing node concept, manual edges — use when a single concept covers all desired nodes and you want all instances as nodes (including isolated nodes with no edges). Isolated nodes can also be added explicitly via model.define(Node(my_instance)).

graph = Graph(
    model,
    directed=True|False,
    weighted=True|False,
    node_concept=MyConcept,       # All instances of MyConcept become nodes; graph.Node is bound to MyConcept
)
Node, Edge = graph.Node, graph.Edge
# graph.Node IS MyConcept — properties assigned to graph.Node are directly available on MyConcept
# Define edges manually with Edge.new(src=..., dst=...)

Pattern 3: Existing node concept + edge concept — use when each interaction is already modeled as its own concept with source/destination relationships. Rather than deriving new nodes and edges, graph.Node, graph.Edge, graph.EdgeSrc, graph.EdgeDst, and graph.EdgeWeight bind directly to the provided concepts and relationships — avoiding extra computation, which matters for large graphs.

graph = Graph(
    model,
    directed=True,
    weighted=True,
    node_concept=Account,
    edge_concept=Transaction,                      # Each Transaction instance becomes an edge
    edge_src_relationship=Transaction.payer,        # Source endpoint
    edge_dst_relationship=Transaction.payee,        # Destination endpoint
    edge_weight_relationship=Transaction.amount,    # Edge weight (required when weighted=True)
)

Important:

• When using edge_concept, you must also pass node_concept, edge_src_relationship, and edge_dst_relationship. Add edge_weight_relationship when the graph is weighted.
• Weights must be floats. Use floats.float() to cast from other numeric types: weight=floats.float(Transaction.amount).
• Note: edge_src_relationship, edge_dst_relationship, and edge_weight_relationship accept only a Relationship or Chain — not a Property, not an Expression. If your ontology models the link as a Property (e.g., f"{Edge} from {Node:source}"), or if you need to cast (floats.float(...)), use Pattern 1 or 2 with manual Edge.new(src=..., dst=..., weight=...) instead. Pattern 3 will fail silently with a model warning and produce 0 edges.

Graph constructor aggregator parameter guidance

aggregator defaults to None; multi-edges (parallel edges between the same node pair) emit warnings when present. aggregator="sum" (the only supported alternative) collapses multi-edges by summing weights — works on unweighted too.

Use it only when multi-edges are expected (co-occurrence with multiple shared attributes, or intermediary concepts where multiple operations connect the same pair). Omit otherwise — silencing unexpected multi-edges masks bugs in edge-derivation logic.

Algorithm cheat sheet

Compatibility constraints in this section are non-exhaustive. For any algorithm you plan to call, load algorithm-selection.md and confirm its compatibility row before writing the Graph(...) constructor. The Pre-flight table in Step 7 summarizes the most common gotchas, but is also non-exhaustive.

Bridge edges (edge-side single points of failure) have no named primitive — don't loop a WCC per candidate edge; collapse to one layered WCC. See Collapsing per-scenario connectivity checks.

For compatibility constraints (directed/weighted limits per algorithm), see Step 7.

Graph Analysis Workflow

Step 1: Study the Existing Model

Before writing any graph or enrichment code, read the existing model file to understand:

1. How to include base definitions — graph scripts that extend an existing model must import it (e.g., from my_model import model, Site, Operation) so that all base define() rules are in scope. Creating a standalone Model("same name") reference without the base definitions will produce an empty graph because concept instances won't exist.
2. Coding conventions — check how the existing model references table columns (casing, naming patterns) and follow the same style. The model file is the source of truth for conventions, not external metadata tools.
3. What's already wired — identify which relationships and properties exist vs. what needs enrichment. Only enrich what's missing.

Steps 2–5: From Question to Nodes and Edges

Start from the question, not the ontology. The question determines which concepts become nodes, what edges you need, and how to derive them.

Step 2 — Scope the question:

• State the question clearly — what property of the data's network structure are you trying to understand?
• Identify which concepts and relationships in the ontology are relevant to the question
• In broad strokes, what kinds of graph analysis over those concepts and relationships best speak to the question?

Step 3 — Identify the nodes:

• Which of the relevant concepts should constitute nodes — the actors or objects you want to rank, group, or trace?

Step 4 — Determine the edges:

• What edges would best capture the information relevant to the question and the planned analysis?
• Does direction matter? Direction often matters for flow, dependency, or causality. Undirected is often appropriate for co-membership or symmetric relationships. Consider whether directionality is semantically meaningful for your question.
• Note: The edges you need are informed both by the question and by the algorithm you plan to apply.

Step 5 — Derive edges from relationships:

• Sometimes an existing relationship maps directly to edges (the rules are essentially pass-through).
• Often, edges must be derived from one or more relationships less directly — involving filters, joins, or more substantial logic.
• Scan the ontology for the structural signals below to find how to build the edges you need.

Key principle: A single ontology can support multiple graph constructions. Different questions about the same data lead to different node/edge choices. The question always comes first — the ontology is the source of available structure, not the driver.

Recognizing edge sources in the ontology:

Once you know what nodes and edges you need, scan the ontology for these structural signals to find them:

Tip: When the ontology has an interaction concept with source/destination relationships and edge-relevant properties (volume, weight, intensity), prefer edge_concept over manual Edge.new() — it's more concise and ensures every instance is included.

Step 6: Choose Construction Pattern

Map the ontology signal you identified in Steps 2–5 to a construction pattern and decide how to implement it:

Then decide the remaining axes:

1. Directed or undirected? — Directed for flow/dependency, undirected for structural analysis
2. Weighted or unweighted? — Weighted when edge properties (cost, volume, distance) matter for the question
3. Edge.new() or edge_concept? — Prefer edge_concept when the interaction is already modeled as a concept with src/dst relationships

See graph-construction.md for detailed patterns including filtered edges, multi-graph, and weight construction.

Step 7: Select Algorithm

Start from the question, not the algorithm name. First check whether the question reduces to an aggregation — per-entity counts and one-hop group-bys ("how many sources per target?", "which targets have only one predecessor?") run as aggs.count(distinct(...)).per(target) with no Graph constructor needed. Reserve graph reasoners for multi-hop traversal, partitioning, and centrality.

Within the Centrality family, pick the variant by the structural test:

• Eigenvector — undirected mutual importance: a node ranks high when its undirected neighbors do. Requires directed=False. Use for structural-importance / centrality questions (symmetric, co-occurrence, similarity graphs). See eigenvector vs. PageRank.
• Betweenness — bottleneck identification: nodes that sit on many shortest paths. Best for: "which nodes are critical connectors / single points of failure?" Requires weighted=False.
• PageRank — directed inbound flow: importance accumulates along incoming edges. Default for any directed graph where the question explicitly turns on which nodes receive the most flow or attention.
• Degree — local connectivity: count of direct connections. Best for: "which nodes have the most direct relationships?"

One algorithm per question. Pick the single algorithm that matches the structural test above. Don't combine multiple centrality measures into a "composite criticality score" — the resulting ranking has no clean interpretation, depends on arbitrary normalization choices, and typically reorders results vs. any one of its inputs. If the question genuinely requires multiple lenses, run them as separate columns in the output, but rank by one and explain why.

Pre-flight compatibility check. Before Step 8, confirm the chosen algorithm fits the graph's directed/weighted settings:

• pagerank() / reachable() work on undirected but are most meaningful on directed.
• louvain(), infomap(), label_propagation() are non-deterministic — report ranges or structural assertions, not exact values.

For per-algorithm deep dives (parameters, output shapes, interpretation, compatibility matrix), see algorithm-selection.md and confirm the row for any algorithm you call.

Step 8: Configure, Execute, and Bind Results

Canonical assign → bind → query skeleton:

graph = Graph(model, directed=False, weighted=True, node_concept=MyConcept, aggregator="sum")  # match flags to the algorithm (Step 7 pre-flight): eigenvector needs directed=False
model.define(graph.Edge.new(src=..., dst=..., weight=...))                  # define edges
graph.Node.score = graph.eigenvector_centrality()                           # execute — substitute any algorithm
model.where(graph.Node == MyConcept).define(MyConcept.score(graph.Node.score))  # bind back
model.select(MyConcept.id, MyConcept.score).to_df()                         # query

For the directed / weighted / aggregator decisions, see Parameter Guidance. Expensive algorithms (reachable, jaccard_similarity, distance, triangle, …) require explicit domain constraints (of=/from_=/to=/between=/full=True) to run — see Domain Constraints. For the full assign → bind → query walkthrough and per-algorithm extraction, see Result Extraction and Binding and result-extraction.md.

Graph Construction from Ontology

The question determines which construction to use — the same ontology can yield multiple valid graphs.

Two main edge definition approaches (Patterns 1–2 vs Pattern 3)

Manual edges with Edge.new() — most common:

# Entity-level: direct relationship between concepts
graph = Graph(model, directed=True, weighted=False, node_concept=Business)
b1, b2 = Business.ref(), Business.ref()
model.where(b1.ships_to(b2)).define(graph.Edge.new(src=b1, dst=b2))

# Infrastructure-level: edges from intermediary concept
graph = Graph(model, directed=False, weighted=True, node_concept=Site, aggregator="sum")
op = Operation.ref()
model.where(
    op.source_site(site1 := Site.ref()),
    op.output_site(site2 := Site.ref()),
).define(graph.Edge.new(src=site1, dst=site2, weight=op.shipment_count))

# Co-occurrence: shared attribute (id < guard prevents duplicates)
graph = Graph(model, directed=False, weighted=True, node_concept=Customer, aggregator="sum")
left_order, right_order = Order.ref(), Order.ref()
model.where(
    left_order.product == right_order.product,
    left_order.customer.id < right_order.customer.id,
).define(graph.Edge.new(src=left_order.customer, dst=right_order.customer, weight=1.0))

Concept-based edges with edge_concept — when each interaction is already a concept, pass it via edge_concept= + the three required relationships (edge_src_relationship, edge_dst_relationship, and edge_weight_relationship when weighted). See Quick Reference Pattern 3 for the full constructor signature.

Filtered edges: restrict via .where(t.amount >= 100.0).define(graph.Edge.new(src=t.payer, dst=t.payee)).

For detailed patterns (multi-intermediary, hierarchy, self-referencing, multi-graph, weight construction, validation), see graph-construction.md. Graph algorithms and prescriptive optimization coexist on the same Model — use domain concepts directly as node_concept (no mirror concepts or separate models needed).

Parameter Guidance

Defaults: directed=False, weighted=False. Only deviate when the question's structure justifies it. Flipping either flag changes algorithm outputs significantly — Louvain communities partition differently, PageRank scores invert, eigenvector is undefined on directed graphs. Add direction or weight only when the question explicitly demands it (see "When to use" below).

Domain Constraints

Domain constraints control which subset of an output relationship gets materialized. Some algorithms (e.g., preferential_attachment, common_neighbor, jaccard_similarity, reachable, triangle, distance) are expensive to materialize in full and require explicit domain constraints via of=, from_=, to=, between=, or full=True to proceed.

For detailed guidance — which relationships support which keywords, the full=True guard rationale, and a worked constrained-similarity example — see domain-constraints.md.

Result Extraction and Binding

Core pattern: assign → bind → query

# 1. Run algorithm — result lives on graph.Node
graph.Node.centrality_score = graph.eigenvector_centrality()

# 2. Bind to original concept (makes it available for rules, optimization, queries)
Site.centrality_score = model.Property(f"{Site} has {Float:centrality_score}")
model.where(graph.Node == Site).define(Site.centrality_score(graph.Node.centrality_score))

# 3. Query as DataFrame
df = model.select(Site.id, Site.centrality_score).to_df().sort_values("centrality_score", ascending=False)

Shorthand: assign to graph.Node with node_concept

When node_concept is set (e.g., node_concept=User), graph.Node IS the concept — assigning to graph.Node directly creates the property on the concept without a separate binding step:

# graph.Node IS User when node_concept=User — property is automatically available on User
graph.Node.community = graph.weakly_connected_component()

# Query directly via User — no explicit binding needed
df = model.select(User.name, User.community).to_df()

Community labels → concept entities

graph.Node.community_label = graph.louvain()
Segment = model.Concept("Segment", identify_by={"id": Integer})
model.define(Segment.new(id=graph.Node.community_label))
Customer.segment = model.Property(f"{Customer} belongs to {Segment:segment}")
model.where(graph.Node == Customer).define(
    Customer.segment(Segment.lookup(id=graph.Node.community_label))
)

Type handling

Critical: Any integer-valued graph result column (community IDs, unweighted distance() lengths, degree counts) arrives in pandas as Int128Array — reductions raise, and equality filters against Python ints silently match nothing (df[df.hops == 6] returns empty even when df.hops.max() is 6). Cast with .astype(int) before pandas comparisons, groupby, or model.data(). WCC is different: its output is a Node, so the shorthand produces string hashes (.astype(str)) while the direct-query pattern using graph.Node.ref() exposes the node identifier type directly. See result-extraction.md for full casting guidance including both WCC access modes.

Validation

graph.num_nodes().inspect()  # 0 = edge definitions don't match data
graph.num_edges().inspect()  # 0 = relationship/join path is wrong

# .inspect() prints and returns None — for an assertion or any Python-side
# check, fetch the scalar through a query:
n_edges = int(model.select(graph.num_edges().alias("n")).to_df()["n"].iloc[0])
assert n_edges > 0

For per-algorithm query patterns (binary, ternary, reachability, similarity filtering, aggregation), see result-extraction.md.

Downstream Use

Graph outputs become model properties that other reasoning consumes:

• Optimization: Centrality scores as objective weights, community labels for per-group constraints
• Rules: Threshold-based alerting on graph metrics (e.g., centrality < 0.1 → at-risk flag)
• Predictions: Community membership and centrality as predictive features
• Multi-graph: Run multiple Graph() instances on the same model for complementary perspectives (e.g., directed flow graph + undirected connectivity graph)

# Graph metric feeds optimization
problem.maximize(aggregates.sum(x * Site.centrality_score))

# Graph metric feeds rule
Site.is_at_risk = model.Relationship(f"{Site} is at risk")
model.where(Site.centrality_score < 0.1).define(Site.is_at_risk())

Common Pitfalls

Examples

Each example targets a distinct combination of edge construction, topology, algorithm, and result pattern.

…(truncated)