SimInf (version 11.1.0)

edge_properties_to_matrix: Convert an edge list with properties to a matrix

Description

A utility function to convert a data frame of edge properties (e.g., movement rates, counts) into the specific matrix format required for ldata in spatial models. This format allows the C code to efficiently iterate over all incoming edges for a specific node.

Usage

edge_properties_to_matrix(edges, n_nodes)

Value

A numeric matrix with dimensions determined by the maximum number of incoming edges for any node. Columns correspond to

to nodes. Entries are NaN where no data exists.

Arguments

edges

A data.frame with properties assigned for each edge (from --> to). Must contain columns from and to (integer indices, 1-based) and any number of numeric property columns.

n_nodes

The total number of nodes in the model. The resulting matrix will have n_nodes columns.

Details

The function converts the edges data frame into a numeric matrix where:

• Each column corresponds to a to node.

• Each column contains a single sequence of data blocks, one for each incoming edge to that node.

• Each block starts with the zero-based index of the from node.

• The subsequent rows in the block contain the property values (e.g., rate, count).

• The sequence for a node ends with a stop marker (-1) in the first row of the block (the position where the from index is stored). This marker appears exactly once per column, immediately after the last incoming edge.

• Unused cells in the matrix (below the stop marker) are filled with NaN.

The edges data frame must contain columns from and to with valid node indices (1-based). All edges pointing to the same to node must be unique (no duplicate from -> to pairs).

Examples

## Define edge properties: from, to, rate, and count.
edges <- data.frame(
  from  = c(2, 3, 4, 1, 4, 5, 1, 3, 1, 3),
  to    = c(1, 1, 1, 2, 3, 3, 4, 4, 5, 5),
  rate  = c(0.2, 0.01, 0.79, 1, 0.2, 0.05, 0.2, 0.8, 0.2, 0.8),
  count = c(5, 5, 5, 50, 10, 10, 5, 5, 5, 5)
)

## Convert to matrix for 6 nodes.
mat <- edge_properties_to_matrix(edges, 6)
print(mat)

## Interpretation of Column 1 (to node 1): The column contains a
## single sequence of 3 blocks (edges from # 2, 3, and 4).
## Row 1: Index of 'from' node 2 (2-1 = 1).
## Row 2: rate=0.2
## Row 3: count=5
## Row 4: Index of 'from' node 3 (3-1 = 2).
## Row 5: rate=0.01
## Row 6: count=5
## Row 7: Index of 'from' node 4 (4-1 = 3).
## Row 8: rate=0.79
## Row 9: count=5
## Row 10: Stop marker (-1) indicating the end of the list for node 1.