stCEG: Customized Chain Event Graph in R

• stCEG is an R package designed to construct and customize Chain Event Graph models for sequential, asymmetric, and spatially-indexed events.
• It implements flexible staging methods including manual and algorithmic (AHC) clustering, with integrated Bayesian prior specification using Dirichlet distributions.
• The package features a web-based GUI offering interactive plotting and mapping, enabling effective visualization of event trees and area-specific probabilities.

Searching arXiv for the exact topic and related CEG/staged-tree literature. stCEG is an R package for constructing, customizing, estimating, and visualizing Chain Event Graph (CEG) models, with particular emphasis on event processes indexed by spatial areas. It allows a user to fully specify a CEG model from data, includes functions for visualizing spatial variables, and provides a web-based graphical user interface for users without knowledge of R. The package is presented as the first software package for CEGs that allows for full model customization, meaning direct control over both the staging or colouring structure and the prior distributions attached to stages (Calley et al., 9 Jul 2025).

1. Conceptual setting and modelling scope

Chain Event Graphs were developed for processes that are naturally sequential, event-based, and asymmetric. The asymmetry emphasized in the stCEG framework has two distinct forms. The first is asymmetric conditional independence, where conditional independence holds only for some values of a conditioning variable. The second is asymmetric structure, where some combinations of events are logically impossible, so certain branches should not exist at all. In this setting, Bayesian Networks are less natural because they do not handle asymmetry well, whereas CEGs begin from an event tree that directly represents all logically possible root-to-leaf sequences of events (Calley et al., 9 Jul 2025).

The package therefore addresses three practical tasks at once. It supports building CEGs from observed data in a flexible way, encoding expert judgement in both stage structure and priors, and incorporating spatially indexed categorical variables together with geographic display. This design also reflects the broader interpretive role of CEGs as decision-support tools, since the package emphasizes interactive plotting and communication with non-statistical stakeholders.

A common misconception is to treat stCEG as a spatial-statistical model in the sense of introducing adjacency- or covariance-based dependence across areas. Its spatial treatment is more operational: area is included as a categorical variable in the event process, and fitted probabilities are then linked to shapefiles for map-based display. This suggests a pragmatic spatial workflow rather than a spatial dependence model.

2. Mathematical structure of event trees, staged trees, and CEGs

The package is grounded in the standard event-tree formulation. An event tree is defined as

$\mathcal{T} = (V(\mathcal{T}), E(\mathcal{T})),$

where $V(\mathcal{T})$ is the set of vertices and $E(\mathcal{T})$ the directed edges. The root node is $s_0$. Vertices with outgoing edges are called situations and denoted $S(\mathcal{T})$; terminal vertices are leaf nodes $L(\mathcal{T})$. The set of all root-to-leaf paths is the event space

$$\mathbb{X} = \{\lambda(s_0, s) : s \in L(\mathcal{T})\}.$$

For each situation $s \in S(\mathcal{T})$, there is an associated conditional random variable $X(s)$, with state space $\mathbb{X}(s)$. A staged tree is obtained by colouring vertices to indicate that their outgoing-edge distributions are judged equivalent. These equivalence classes are called stages. Two vertices $V(\mathcal{T})$0 and $V(\mathcal{T})$1 belong to the same stage $V(\mathcal{T})$2 if and only if there exists a bijection

$V(\mathcal{T})$3

under which the random variables $V(\mathcal{T})$4 and $V(\mathcal{T})$5 have the same distribution (Calley et al., 9 Jul 2025).

For a stage $V(\mathcal{T})$6 with $V(\mathcal{T})$7 outgoing edges, the conditional probability vector is

$V(\mathcal{T})$8

where $V(\mathcal{T})$9 is the probability that an individual at a situation in stage $E(\mathcal{T})$0 takes the $E(\mathcal{T})$1-th outgoing edge. stCEG uses Dirichlet priors on these stage-level probability vectors: $E(\mathcal{T})$2 with prior density

$E(\mathcal{T})$3

or, up to proportionality,

$E(\mathcal{T})$4

Given data counts $E(\mathcal{T})$5 at stage $E(\mathcal{T})$6, the likelihood is multinomial: $E(\mathcal{T})$7 By Dirichlet–Multinomial conjugacy, the posterior is again Dirichlet: $E(\mathcal{T})$8 Equivalently, if $E(\mathcal{T})$9, then

$s_0$0

Algorithmic staging in stCEG uses Agglomerative Hierarchical Clustering (AHC), whose merge criterion is based on the log Bayes factor

$s_0$1

where $s_0$2 is the log marginal likelihood of staged tree $s_0$3. The package uses

$s_0$4

with $s_0$5, $s_0$6, and $s_0$7. The expanded merge score is also given in the software description, reflecting the stagewise Dirichlet–Multinomial scoring used for greedy bottom-up merging.

3. Software architecture and end-to-end workflow

The package accepts a dataset in data.frame format, and in the GUI the input is a CSV file. The variables used to define the event tree are categorical columns, and the order in which those columns are chosen defines the event sequence. In the GUI, a user may additionally specify an area division column, a time division column, and a prediction variable; the prediction variable is forced to be the final branch in the tree (Calley et al., 9 Jul 2025).

The workflow implemented by stCEG is: input a dataset; construct an event tree from selected columns; optionally delete nodes to encode structural asymmetry; colour situations into stages manually, by algorithm, or both; specify prior distributions for each stage; combine the staged tree and priors; create the CEG; inspect posterior updates, log marginal likelihoods, and Bayes factors; and, when a spatial variable is present, link the fitted CEG to a shapefile and map area-specific probabilities or reduced CEGs. This corresponds closely to the general staged-tree-to-CEG pipeline formalized in the broader CEG literature, where a CEG is obtained by contracting equivalent staged substructures (Shenvi et al., 2020).

The package organizes this workflow around three main S3-style classes: event_tree, staged_tree, and chain_event_graph. All three use visNetwork for interactive network plotting.

Function	Role
create_event_tree()	Creates a symmetric event tree from selected factors
delete_nodes()	Removes selected nodes to encode structural asymmetry
update_node_colours()	Manually groups nodes into stages
ahc_colouring()	Applies Agglomerative Hierarchical Clustering for staging
specify_priors()	Assigns Custom, Uniform, or Phantom Dirichlet priors
staged_tree_prior()	Combines staged tree and priors
create_ceg()	Contracts equivalent substructures into a CEG
create_reduced_CEG()	Displays only paths involving selected categories
compare_ceg_models()	Compares fitted models by log marginal likelihood and log Bayes factor
generate_CEG_map()	Links a fitted CEG to a shapefile for area-level probability maps
run_stceg()	Launches the web-based GUI

A distinctive design choice is that create_event_tree() builds the full symmetric logical tree from selected variables and then allows deletion of nodes if needed. The package contrasts this with cegpy, which only maps observed paths and requires the user to add unobserved but logically possible paths manually. This suggests that stCEG is particularly oriented toward applications where structural asymmetry must be imposed after an initially symmetric logical specification.

Prior elicitation is integrated into the modelling pipeline through specify_priors(). Three prior types are supported. Custom priors allow manual stage-specific Dirichlet parameters. Uniform priors use $s_0$8. Phantom priors use the “phantom individuals” idea, in which an imaginary sample size $s_0$9 is set equal to the maximum number of outgoing edges from any situation in the staged tree and then distributed evenly through the tree. If Uniform or Phantom is selected, the user can still edit specific rows interactively.

The CEG produced by create_ceg() contracts situations that have the same colour and downstream structure, and all leaf nodes are contracted into a single sink node $S(\mathcal{T})$0. The function can display prior parameters, prior means, posterior parameters, posterior means, or no numerical labels, and can also produce a prior-to-posterior update table through view_table = TRUE.

4. Spatial variables, map linkage, and reduced graph views

Spatial information in stCEG is incorporated by treating area as one of the variables in the event tree or CEG. A borough or other area division can therefore appear as one branch in the event process, after which the fitted model can be linked to a polygon shapefile. The function generate_CEG_map() uses leaflet and a shapefile to display model-derived probabilities by area, optionally conditioned on selected event categories (Calley et al., 9 Jul 2025).

This spatial workflow has four stages: include a spatial area variable as one branch in the event tree; fit the larger CEG as usual; join the fitted graph to a polygon shapefile; and display area-level probabilities or area-specific reduced CEGs. The package also supports create_reduced_CEG(), which shows only paths involving selected categories. In spatial settings, this is used to inspect area-specific branches without reading the full graph.

The map interface can colour polygons by a specified response category and can condition on selected event values such as weapon type or victim sex. Hovering over polygons displays averaged probabilities for that area. The GUI extends this with polygon-triggered reduced CEG views and map-assisted colouring for area florets.

A recurrent misunderstanding is to treat these capabilities as evidence that stCEG models dependence between nearby areas. The software description is explicit that the current spatial approach treats space as another categorical variable and does not model dependence between nearby areas. Two adjacent boroughs are therefore modelled as distinct categories rather than as units with correlated behavior. The package’s spatial innovation lies in model construction and interpretability, not in a new theory of spatial dependence.

5. Demonstration on London homicide data

The package includes a homicide dataset sourced from the Metropolitan Police Homicide Dashboard, covering homicide victims in London from 2003–2023. The main example uses the categorical variables Method of Killing, Sex, Domestic Abuse, and Solved Status, and the modelling goal is to explore factors affecting whether a homicide case is solved (Calley et al., 9 Jul 2025).

In the initial event-tree construction, the example code applies create_event_tree() to the first four relevant columns with labels showing both names and counts. The paper also shows how asymmetry can be imposed through delete_nodes(). For an asymmetric version of the homicide tree, the reported summary gives 45 nodes, 44 edges, 5 node levels, and 10 unique edge labels. In the partially coloured tree example, the summary indicates total nodes: 61, total edges: 60, and nodes left to be coloured: 16.

The homicide example then combines manual and algorithmic staging. Some node groups are coloured manually with update_node_colours(), and the remaining uncoloured nodes are staged using ahc_colouring(). This hybrid sequence is central to the package’s notion of full model customization, because it allows expert judgement and data-driven clustering to operate in either order.

Custom priors are then assigned with specify_priors(..., "Custom"). The reproduced example includes 17 stages with user-entered prior vectors such as root stage $S(\mathcal{T})$1: $S(\mathcal{T})$2, $S(\mathcal{T})$3: $S(\mathcal{T})$4, $S(\mathcal{T})$5: $S(\mathcal{T})$6, $S(\mathcal{T})$7: $S(\mathcal{T})$8, and $S(\mathcal{T})$9: $L(\mathcal{T})$0. These priors are then attached through staged_tree_prior(), and the resulting staged tree is converted to a CEG with posterior means displayed on edges.

For the fitted homicide CEG, the reported summary() gives a total log marginal likelihood of $L(\mathcal{T})$1, together with stage-level log scores and effective sample size values; several low-information stages are flagged. The paper also compares this expert-informed model with a competing model built using full AHC colouring and uniform priors. The comparison yields log marginal model 1: $L(\mathcal{T})$2, log marginal model 2: $L(\mathcal{T})$3, and log Bayes factor: $L(\mathcal{T})$4, favoring model 2. The authors caution that such scores can reflect alignment of priors with observed data and may be misleading under sparse or unrepresentative observations.

The spatial extension adds a Borough variable. This increases the event tree from 60 vertices to 1952 vertices, which motivates the package’s mapping and reduced-graph tools. A solved-probability map by borough is then generated with generate_CEG_map(), and conditional mapping is demonstrated for conditionals = c("Knife or Sharp Implement", "Female"). The paper notes that Hillingdon and Hounslow, despite being adjacent, have markedly different solved probabilities; create_reduced_CEG() is then used to compare the borough-specific branches thought to drive that difference.

6. GUI, software ecosystem, limitations, and future directions

A major component of stCEG is its Shiny web interface, which is intended to lower the barrier to entry for users without R programming experience. It can be launched with run_stceg() and is organized into three tabs: Upload Data, Select Data, and Plots. The first tab handles CSV upload and metadata such as area column, time column, and prediction variable. The second tab supports filtering by areas and time range, and selection of variables and their order. The third tab supports event-tree display, node deletion, colouring, AHC, prior specification, staged-tree display, CEG creation, and optional joint display of graph and map (Calley et al., 9 Jul 2025).

One of the most distinctive GUI features is map-assisted colouring for area variables. When an area column exists and a shapefile is uploaded, polygons are shown on a leaflet map; uncoloured area florets appear orange; selecting polygons and clicking “Show Floret” opens a popup with the corresponding floret; colours assigned there propagate back to the full event tree; and polygons turn green when fully coloured and amber when partially coloured. This is a usability-oriented response to the fact that large spatial event trees can become difficult to manipulate directly.

The package is positioned relative to cegpy, stagedtrees, and ceg as the first one enabling full model customization together with spatial support and an interactive user interface. Its explicit strengths are full colouring control, full prior control, spatial variable support, interactive plotting, and a GUI. The implementation reported in the paper uses R 4.4.1, shiny 1.10.0, and leaflet 2.2.2, and the source code is available at https://github.com/holliecalley/stCEG.

Its limitations are equally explicit. The main methodological limitation is spatial: space is currently handled by treating area as a categorical variable, so the model cannot express dependence between nearby areas. There is also a computational limitation, since adding many area categories can greatly enlarge the event tree, as in the borough example. The future developments proposed include richer spatial theory for CEGs allowing inter-area dependence, user-defined event tree structures without starting from a data frame, temporal and spatio-temporal CEG extensions, and more model selection criteria and scoring methods.

In this sense, stCEG is best understood not as a new probabilistic theory of spatial dependence, but as an end-to-end software environment for staged trees and Chain Event Graphs in applications where events unfold sequentially, asymmetrically, and across spatial categories. Its central contribution is the integration of model construction, expert customization, Bayesian prior specification, graph contraction, interactive visualization, and geographic display into a single CEG workflow.