## 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"
```
Last updated on `Tue Nov 8 15:58:09 2022` with bnlearn `4.9-20221107` and `R version 4.2.2 (2022-10-31)`.