## Utilities to construct blacklists

Often we have substantial prior knowledge about which arcs would make no sense in the domain we are studying, and we
can define broad patterns for those arcs. Hence **bnlearn** provides some utility functions to construct
blacklists programmatically and make structure learning easier.

### Constructing a blacklist from a topological ordering

One such function is `ordering2blacklist()`

, which takes a vector of node labels as argument. The order of
the node labels in the vector defines a total topological ordering, and the function returns the complete set of the
arcs that would violate that ordering. (That is, all the arcs that go from a node to a node that precedes it in the
topological ordering.)

> library(bnlearn) > ordering2blacklist(LETTERS[1:6])

from to [1,] "B" "A" [2,] "C" "A" [3,] "D" "A" [4,] "E" "A" [5,] "F" "A" [6,] "C" "B" [7,] "D" "B" [8,] "E" "B" [9,] "F" "B" [10,] "D" "C" [11,] "E" "C" [12,] "F" "C" [13,] "E" "D" [14,] "F" "D" [15,] "F" "E"

In this example the total ordering is `c("A", "B", "C", "D", "E", "F")`

, hence the resulting blacklist
contains `A`

← `B`

, `A`

← `C`

, `A`

←
`C`

etc. leaving `A`

→ `B`

, `A`

→ `C`

as admissible
arcs.

This blacklist can be used to enforce a total topological ordering in structure learning.

### Constructing a blacklist from a partial ordering

The analogous function for a partial ordering is `tiers2blacklist()`

. It takes a list of character vectors
as argument; each element of the list should contain the labels of a group of nodes (called *tier*). The returned
blacklist contains all the arcs pointing from any node in one tier to any node in a preceding tier.

> tiers2blacklist(list(LETTERS[1:3], LETTERS[4:6]))

from to [1,] "D" "A" [2,] "E" "A" [3,] "F" "A" [4,] "D" "B" [5,] "E" "B" [6,] "F" "B" [7,] "D" "C" [8,] "E" "C" [9,] "F" "C"

In this example, the first tier contains `c("A", "B", "C")`

and the second tier contains ```
c("D", "E",
"F")
```

. Hence the blacklist is formed by all arcs that point from one of `D`

, `E`

,
`F`

to one of `A`

, `B`

, `C`

. Note that the blacklist does not contain any
arc between nodes in the same tier.

This blacklist can be used to enforce a partial topological ordering in structure learning. A common use case is to blacklist arcs going backward in time when learning dynamic Bayesian networks.

### Constructing a blacklist to ensure a subset of nodes are disconnected from each other

`set2blacklist()`

takes a character vector of node labels as argument and constructs a blacklist
containing all the arcs between any of these nodes. Common usage is to force some nodes to be root nodes disconnected
from each other.

> set2blacklist(LETTERS[1:4])

from to [1,] "B" "A" [2,] "C" "A" [3,] "D" "A" [4,] "A" "B" [5,] "C" "B" [6,] "D" "B" [7,] "A" "C" [8,] "B" "C" [9,] "D" "C" [10,] "A" "D" [11,] "B" "D" [12,] "C" "D"

`Tue Nov 8 15:58:09 2022`

with **bnlearn**

`4.9-20221107`

and `R version 4.2.2 (2022-10-31)`

.