wb2dot - A Tool For Translating Textual WB-Graphs into DOT Format

What is wb2dot?

Wb2dot is a Perl script that translates textual WB-Graphs into dot format. Using dot from the graphviz tools you can then create PostScript files (wb2dot can execute dot with correct parameter settings for you automatically, of course).

Operation of wb2dot is easy. It is command driven but has a telling online help. If that isn't enough this documentation provides all details you have to know about. Wb2dot does a great job at making your work easier: You only have to write down once the resulting graph of your "Why...Because"-Analysis in any ASCII editor of your choice. Then run wb2dot and you get a nicely drawn graph you can display and print. No more worries about leaving out parts of the graph or inserting errors as you are drawing the large graph with a program manually, making double work.

Wb2dot can even help you detecting errors in your WB-Graphs: It rejects syntax errors displaying appropriate error messages and searches for undefined links. When the PostScript graph is printed, it's easy to find logical errors, because you can grasp the whole graph at once. It's even possible to detect cycles: WB-Graphs are DAGs with all edges pointing from causes to their results. Because there is a time ordering imposed on the graph, no edge should point backward in time. Wb2dot produces edges oriented from right to left. So if you see any edge pointing in the opposite direction you will know something went wrong with your analysis.

Wb2dot will mark all source nodes that led to the accident automatically. Default is filling the source nodes with lightblue color. As with almost everything in this tool, you can change it according to your liking (although you have to edit the Perl source code this time - there is no parameter, sorry).

How to install wb2dot

Just download wb2dot by clicking on the name while holding the SHIFT key pressed. You are probably using UNIX, so you want to run the command

 chmod 555 wb2dot

afterwards (this allows you to run wb2dot like any other command). Of course, you need to have installed Perl and dot. On my system a bug occurs whenever a graph is distributed over more than one page: A string will be displayed on every page that looks like

 (\\() show i str cvs show (,) show j str cvs show (\\)) show

I don't know whether dot or ghostscript is responsible for it. A remedy against this is a small Perl hack named fixps. It will search for any occurence of this string and comment it out by placing "%%" in front of it. Just run it after the PostScript version of the WB-Graph has been generated:

 fixps ps_file > fixed_ps_file

How to use wb2dot

To get a list of all available options along with a short description of how they work just type

 wb2dot

In its simplest form wb2dot expects one parameter: the name of the textual WB-Graph

 wb2dot wb_file

This will parse wb_file and report any errors to you. If there are none, a statistics will be displayed and all relevant data for dot will be written to a file using an automatically generated name. Then it will run dot which reads the newly created file and finally the PostScript file containing your graph will be written (both filenames will be displayed).

Textual WB-Graphs

To give you an informal insight what textual WB-Graphs look like you can download three examples: Cali, Nagoya and Warsaw. They were produced by our research group and result from applying the "Why...Because"-Analysis to various aircraft incidents.

If you are interested in the EBNF syntax representation of textual WB-Graphs, look at figure 2.7 on page 18 of Karsten Loer's Diplom Thesis. Wb2dot implements it in large parts (at least that is what the author of wb2dot hopes) except for:

textgraph is now defined as

 textgraph = firstnode { node }.

where

 firstnode = tag node_info ( tag | "/\" tag { "/\" tag } | node_ext | "/\" node_ext { "/\" node_ext" } ).

node_ext does not include possible worlds any longer:

 node_ext = "<-." number ">" | "[-." number "]" | "{-." number "}" | "(-." number ")".

This is a feature.

More about wb2dot

You think there must be more to know about? You're right. Wb2dot has six command line options. Except for switches -n and -p which are mutually exclusive, all can be combined in any arbitrary order. The only thing you must make sure is the name of the textual WB-Graph must appear as the last argument. If there is an error in parsing the command line options, wb2dot will display its help screen.

Switch -c allows you customize the length of the labels. Depending on switch -l each node displais certain information. The problem is how to format this information of varying length. You probably don't want to put everything in a single line. But the exact point of where to insert a newline character is not easily defined. It depends on your esthetical sense. You can deliver a number greater than null to wb2dot. Otherwise the default of "20" is taken. Wb2dot works it way through every label like follows: If the label has less or equal many arbitrary characters as the number specifies, it is done with that label. Otherwise wb2dot looks whether a whitespace follows after that number of characters. If it does, the whitespace is replaced by a newline character and the whole procedure starts with the rest of the label. If it doesn't, the number gets incremented by one and the test for a whitespace is repeated.

Switch -d tells wb2dot what filename to use for the intermediate graph in dot format. If it isn't specified, wb2dot takes the name of the textual WB-Graph, deletes the suffix ".txt" or ".wb" (if there is one), and adds the suffix ".dot" resulting in the automatically generated name.

Switch -l allows you to extract the kind of information from the textual WB-Graph you're interested in.
1. If you only want an overview, use "path" as argument. This will label the nodes with just the path numbers, so the graph is kept to its minimum size.
2. Default is "text" which means after the path number a description of this node follows. Or technically speaking 'tag' and 'descr' are combined (look at the EBNF mentioned above for details).
3. Maybe you just want to see the failure types, timestamps, altitudes and other remarks: Then you should choose "fail". Here 'tag' gets combined with 'add_info'.
4. To get all available information, just type "all".

Switch -n can't be combined with switch -p. It causes wb2dot to finish after the WB-Graph has been converted to dot format. This enables you to modify dot_file (say, for changing the page size into A3 format or removing the legend and statistics box). You can run dot manually by typing
```
 dot -Tps dot_file -o ps_file
```

Switch -p can't be combined with switch -n. It tells wb2dot what filename to use for the resulting PostScript graph. If it isn't specified, wb2dot takes the name of the textual WB-Graph, deletes the suffix ".txt" or ".wb" (if there is one), and adds the suffix ".ps" resulting in the automatically generated name.

Switch -s lets you choose from four different sizes for the PostScript graph. If that isn't enough, modify dot_file to achieve the desired page and graph size. You may want to run this switch with various arguments to see what effects they have. All resulting graphs are landscape style. If you want them to be portrait style, you also have to change the "rankdir" setting in dot_file. Consult the dot user's guide for further information.
1. The default is "a4" which produces a graph just small enough to fit on a single sheet of paper of that size.
2. If the previous parameter produces unreadable graphs, try "a3". This will double the size of the graph and split it up between two pages.
3. Some graphs are long and narrow. To maximize page coverage and improve readability for those cases, you can use "long" to combine two landscape a4 pages giving a landscape style graph of double length while keeping the height constant.
4. Other graphs leave some regions white no matter which of the previous arguments you choose. Try "large" for a better page exploitation.