Water Valve Charts for displaying logical relationships

A type of flow chart that can display very complex logical relationships in an easily interpretable form

Repository: https://github.com/scheid/water-valve-charts

Additional Demo: https://github.com/scheid/water-valve-charts/blob/master/demo.html

Water Valve Chart (WVC) visualizes logical relationships, and is capable of representing very complex sets of logical statements pictorially. The flow starts at one side and progresses across. The flow could also start at the top and progress downward.

This example illustrates the statement A AND B. Using the analogy of water and gates/locks, both A and B must be open (true) in order for the water to flow through. If you keep this water analogy in mind, even the complex graphs are much easier to understand than the same logic represented in more traditional text based methods.

This example illustrates the statement A OR B. Coming into the block, the "water" splits to flow to both the A and B gates. If either A or B is open (true), then the "water" will flow to the other side of the graph.

Getting progressively more complex, this graph represents (A OR (B AND C)) . The flow can either go through A to reach the other side of the graph, or both B and C need to be open in order for the flow to take that route.

Continuing, this represents (A OR B OR (C AND D AND E)) .

This shows the same graph as above, with the execution path highlighted.

Multiple blocks/groups can be joined together as well, to better represent distinct objects you may be working with:

A AND (B AND (M OR N) AND Z) AND (E OR (P AND Q) OR S) AND F AND (G OR H OR I)

It is also possible to display evaluation results for each of the nodes, whether each was true or false. You can easily create a display as shown below, using whatever shapes and styles are appropriate for your display. To enable this, you must include a boolean field that describes the evaluation result of each individual item/object in the chart, whether it is true or false (e.g., whether the valve would be open or closed, respectively, to maintain the analogy). In the water valve configuration, set highlightExecutionPath to true, and set evaluationResultField to the name of the field containing the evaluation result for each of the individual items.

A AND (B AND (M OR N) AND Z) AND (E OR (P AND Q) OR S) AND F AND (G OR H OR I)

Input Data Structure

So, what is the data structure required as input to create these graphs? The structure is a series of arrays, with an array representing a 'group' of items. The first element of every array must be the operator 'and' or 'or' and all of the items in the array will be connected using that operator. One of the array elements can itself be an array, with the same requirement of having the group operator as the first element. Of course some combinations of comparisons are non-sensical and it is left up to the developer to use meaningful structures. The component does not perform any 'sanity' checking of the input data.

The outermost array will define the visual groupings. Each element will be treated as an independent group logically and visually.

The data shown in these examples use simple alpha-numeric characters as the elements. But you can use any custom object structure that you wish, and that entire object will be carried through and exposed in the calculated data. This would be a necessity in the real world, especially to allow users to interact meaningfully with the graph objects.

There are a few quirks currently. For the outermost array, you should always use "and" as the operator.

For the statement (A AND B) , the input data structure would be

[
   "and",
   [
      "and",
      "A",
      "B"
   ]
]

For the statement (A OR B) , the input data structure would be

[
   "and",
   [
      "or",
      "A",
      "B"
   ]
]

For the statement (A OR B OR (C AND D AND E)) , the input data structure would be

[
   "and",
   [
      "or",
      "A",
      "B",
      [
         "and",
         "C",
         "D",
         "E"
      ]
   ]
]

In addition to the simple characters used in these examples, you could use any type of object with any combination of fields, etc. that you wish for each element. The structure below shows an expanded structure of the above data.

Vertical Orientation

The graph can also be oriented vertically, with a simple configuration setting, such that the first node is at the top and the flow goes downward.

Alternate Node Rendering

This illustrates that the nodes can be anything you wish. The WVC calculates the coordinates of the various entities and you can tailor your d3js code to render those coordinates in many different ways.

forked from scheid's block: Water Valve Charts for displaying logical relationships