Computer Laboratory: Tree Information File

File Formats

Tree Information File

The tree infomration file defines the tree on the left of the line plot display, the organisation of the Sankey diagram and the logical tree used in the tree map display. It is invariably large and at the moment tools for editing tree information other than by hand editting the json file are under development. Hand editting is extremely error prone. A good json checker can be found at jsonlint.com. Even valid json is not enough to produce valid tree files, and Joule is currently not helpful in communicating error messages. This is an understatment.

Until those tools are developed, you really need to understand json. There are multiple sources of information on the web. JSON.org is probably a good place to start.

There are two json objects in the tree data file. These are the functionTree and the plotLines array. When the tree data is included in the configuration tree, these two objects are subobjects of the treeData object.

An example of a (large) tree data file can be found here (opens new tab).

The plotLines object is a description of things that we want to plot that don't fall naturally out of the functiontree description. So we start with the functionTree object.

(The name "functionTree" comes from an original view that we should present both the physical distribution and functional organisations of electricity, but then realised that we just need different tree files. So it is a tree of whatever you want it to be.)

Let's start with a very simple tree file:

You can see the resulting plot here (other tab). There are no additional plotLines defined - the plotLine array is empty - and the tree is a simple node (lighting for the ground floor) which has five children for different parts of the ground floor. All five children correspond directly to meters (S is for "sensor") S-m34, S-m17, S-m33, S-m22 and S-m7. Any plot line names are of the form S-m<meter number> are deemed to be meters and their underlying data will be read from the meter data files. You will see from the line plot that there is a line for the parent node which is the sum of its children and that that node has a plot line name of PLLightingGround. By convention plot line names either start with "PL" or "S-m". (There may be assumptions burried in Joule which would make it inadvisable to break this convention.)

Here is the tree map for the all lighting circuits in the Gates Building:

which gives rise to a more interesting tree structure - in particular you can now go down a level on the tree map diagram. The resulting visualisation is here (in other tab).

Each node in a tree corresponds to a plotLine. So far we have seen plotLines that correspond to a meter or in the case of nodes with children to the sum of the children. We can specify other types of plotLines. They still appear in the functionTree object but refer to plotLines defined in the plotLine object.

A node with children can in fact be such a plotLine, in which case it will not necessarily be the sum of its children, although we probably want to define it so that it is.

Here is a case in point. The metering for the machine room SE18 has one meter that does the whole room and one meter that does the air conditioning, Logically, the parent is the first meter and the children are the meter for the air conditioning and the difference between the two. This is a tree data file for the machine rooms in the Gates Building (at the time this was written, bearing in mind that SE18 is going to be decommissioned).

There are two machine rooms SE18 and GN09. GN09 has meters on the uninterruptable power supply (UPS) to servers, non-UPS to servers and the air conditioning. SE18 has two meters as described above. The tree data provides a uniform presentation despite the fact that the meter arrangments are different.

In the first specially defined plotline we define the PLSETotal to be meter 27. This is done by saying it is the sum of a number of meters of which there is only one. Next we define the server power component, PLSE18Power to be the difference between meter 27 and meter 41 (the meter for air conditioning power). In other words we have subtracted the air conditioning from the totlal to derive the power going to the racks. The resulting visualisations can be seen here. (other tab)

We have seen plotLines define as SUMs (which can have an arbitrary number of components) and DIFFs (which must have exactly two components). The only other composing function is ALT which uses its first component when possible, otherwise uses the second. This can be useful when meters are replaced or reconfigured.