03 — Building and analysing the DAG

Pierpaolo Massoli

Operational examples assume that the SSPICE project root is the working directory. Operational chunks are not executed when building the vignette because they require the project data. Standalone chunks explicitly marked eval=TRUE are exceptions.

From routing metadata to a graph

build_DAG() reads routing metadata and produces the canonical DAG. stop_on_cycle = TRUE prevents processing from continuing with cyclic dependencies; analyze = TRUE computes structural diagnostics. The project script also saves the adjacency matrix, transposed incidence matrix, numeric routing table and graph partitions.

source(file.path("scripts", "00_config.R"))
dag <- SSPICE::build_DAG(
  routing = config$routing_file,
  separator = config$metadata_separator,
  na_strings = config$missing_codes,
  analyze = TRUE,
  stop_on_cycle = TRUE,
  max_paths_per_partition = config$max_paths_per_partition
)
names(dag)
dag$graph_diagnostics

What to inspect

Nodes represent variables and logical groups; edges represent path prerequisites. Inspect sources, isolated nodes, partitions and path lengths before attributing routing anomalies to the data. OR and XOR groups are represented by canonical VOR and VXOR variables. An acyclic graph allows dependencies to be evaluated in a consistent order.

source(file.path("scripts", "01_build_DAG.R"))
dag <- readRDS(file.path(config$dag_output_dir, "questionnaire_DAG.rds"))
str(dag$graph_diagnostics, max.level = 1)
utils::head(dag$routes_numeric)

If construction fails, correct the metadata and rebuild the DAG before reusing derived results. The DAG extended with logical edits is built separately in Step 09.

Checking the meaning of the graph

Read Building the routing file before constructing the graph. Canonical nodes can replace several original variables: VOR and VXOR are not simple renamings. In particular, check that jump targets still exist after grouping.

An acyclic DAG can still contain incorrectly specified domains, jumps or groups. Inspect routes_original, routes_grouped, routes_numeric and Bt, and check expected paths on small examples. An isolated node may indicate a question excluded by an unconditional jump or a metadata error; do not remove it automatically without interpreting its role.