Pasi: A Tool for Creating Ontological Diagrams

Pasi is a Java applet that makes it possible to create diagrams with an output format suitable for inclusion in TeX or LaTeX files. It relies on Peter Kabal’s texdraw package, which can be downloaded from here, or, as part of the MiKTeX distribution of LaTeX, from here. The diagrams for which Pasi is specialized are simple circle-and-arrow diagrams, where the arrows are intended to express relationships between entities. Although such diagrams can also be created with many other programs, Pasi has some unique additional features related to this task. For example, it is very easy in Pasi to add circles (i.e., ‘entity nodes’) to existing arrows, which are then thought of as denoting the relationships expressed by the arrows themselves. Since these circles can in turn be connected via arrows to other entity nodes, the user can conveniently represent higher-order relationships, i.e., relationships between relationships.

The name ‘Pasi’ (read ‘PAH-see’) is short for ‘pasigraphy’, a goal which it of course doesn’t reach, but for which it is (hopefully) nevertheless useful. I had originally written the applet, in the last few months of 2006, as a tool to help me create some diagrams for a term paper.

There also exists a non-text version of this page, which contains only the applet.

Here is a list of the main features that (I think) help to make Pasi unique:

• Variability of arrow heads. The user can choose between twelve basic kinds of connectors (i.e., arrows and other lines) that can be varied on several dimensions. In addition, two or more connectors between the same two nodes can be combined into a ‘compound arrow’ (yielding, e.g., a bidirectional arrow if the original two run in opposite directions, as shown below).

• Auto-flexing. This feature really consists of two parts: First, when two nodes linked by a connector are moved too close together (so that a straight line would look too short), the latter’s contact points on the peripheries of the two nodes are moved apart, resulting in a curved connector. (Similarly if a node is connected with itself.) Second, whenever a node is connected with two or more other nodes, Pasi strives to keep the contact points of these arrows on the first node at a certain minimal distance from each other, so as to prevent the arrowheads from overlapping.

• Support for higher-order connectors. By clicking on the center of any given connector, a small further node can be made visible that denotes the corresponding relationship itself. This node can then again be connected to other nodes, have labels attached to it, etc. (see diagram). I call connectors that are attached to such a node ‘higher-order connectors’.

• LaTeX-friendliness. Since Pasi’s output is a piece of LaTeX code, it is possible to combine its drawing capability with the type-setting power of LaTeX. Text is added to the diagram by attaching a label to a node. On the screen as well as in Pasi’s output, the content of such a label will appear exactly as entered by the user. But when the output is included in a file and processed by LaTeX, that content will be type-set like ordinary LaTeX code.

If the features just listed should seem unnecessary (or some are needed that Pasi doesn’t have), yWorks offer a very attractive alternative with their freely available yEd graph editor. On the other hand, yEd does not have auto-flexing, does not support second-order connectors as naturally as Pasi does, falls far short in its variety and customizability of arrowheads, and does not generate LaTeX-readable output. Freely available programs that at least offer this latter option include: Ipe, TpX, jfig, TexCAD, and Dia. The first four of these are multi-purpose vector graphics editors, while Dia is designed specifically for the task of drawing diagrams. Ipe has some very clever snapping mechanisms, and TpX sports a wide variety of pre-defined arrow-heads as well as a highly useful hatching tool. Jfig is a Java-based version of the classic xfig. In none of these multi-purpose programs, however, do the arrows or lines stay attached to the connected nodes when the latter are moved; hence, none of them offers auto-flexing. Nor do they support second-order connectors. However, Dia is an extremely versatile tool for drawing diagrams, with a very large variety of predefined vector-graphics objects and customizable arrows. And though it does lack Pasi’s auto-flexing feature (as well as support for second-order connectors), its arrows and lines do stay attached to the objects they’re supposed to connect.

That arrows and lines stay attached to the objects they are supposed to connect when these are moved may not sound like a very important feature. But it is a perfectly natural upshot from a design policy that tries to steer a reasonable middle course between a purely logic-driven and a purely graphics-driven interface. By ‘purely logic-driven’, I mean a kind of interface where all one has to do in order to create a diagram is to specify what entities and what relationships between these should be represented. Such an interface could be realized simply in the form of a programming language, which is more or less what LaTeX’s own approach to type-setting suggests. Accordingly, there are several software packages (e.g., xypic, dot2tex) that allow users directly to program diagrams into their LaTeX files. On the other hand, a ‘purely graphics-driven’ interface expects nothing except for the specification of visual information: what colors are displayed at which points, what kinds of lines connect which coordinates, and so on. Though this information can also be expressed with a text-based interface (such as PostScript), a much more natural way seems to be via a graphical user interface.

The approach taken by Pasi lies between these two poles, in the following sense: on the one hand, it offers a GUI for the easy placement of nodes and shapes at various locations on the canvas. On the other hand, connectors are not specified by their end points on the canvas, but instead by selecting the nodes they are supposed to connect – just as it would be done on a purely logic-driven approach. If lines and arrows are defined in this way, it is only natural that they should also stay attached to the objects connected by them. Another way of describing this feature would be to say that logic-related effects of logic-related input (i.e., what nodes to connect) cannot be cancelled by the graphics-related input of what object goes where. But this policy can be taken even further, since sometimes graphics- and logic-related input can combine in visually undesirable ways, leading to worries such as: Will my diagram still look good if I connect node A with node B, given that I’ve placed them at such-and-such locations on the canvas? As long as there are worries of this sort, the purpose of having a logic-driven interface could only be fully realized by a system that is able to detect and eliminate aesthetic flaws – clearly an unrealistic task. And at any rate, it seems natural (if not necessary) to let the user impose her own aesthetics on the diagrams she wants to create. So a GUI is clearly called for, but this does not mean giving up on the motivation behind the logic-driven approach. It is still possible to take some measures that help to make sure that a diagram will at least look half-way decent regardless of how the nodes are connected. In Pasi, this is attempted by the auto-flexing feature.

A user guide with a more detailed description of Pasi’s features is available here.

Note that the presentation of figures and labels on Pasi’s canvas may not in every aspect be the same as what one will see in the DVI or PDF file that results from processing its output as part of a LaTeX document. In particular, the text of labels is shown in completely unprocessed form and may appear at slightly different locations in the output than on the canvas. Also, the coordinates of arrows and other objects are, on the canvas, rounded to integer values (in pixels) and may consequently differ from the output.

• The drawing area for entity nodes may be slightly smaller than the nodes themselves. This results in missing pixels, so that the nodes do not appear as perfect circles on the screen. (This problem does not affect the generated LaTeX code.)

• It may be neither possible to send the LaTeX code to the webpage, nor to copy and paste it by using a browser command. However, it should still be possible to use the mouse cursor to drag the generated code from the applet window into a text editor.

A diagram in Pasi consists, on the ‘ground level’, of nodes that are in some way connected with each other or decorated with labels or pointers. There are two kinds of nodes: ‘entity nodes’ and ‘contour nodes’. The former are connected with various kinds of lines or arrows (and only these can have labels and pointers). Contour nodes, on the other hand, are connected with each other by Bézier curves running through their centers, so as to form various kinds of different figures called ‘contours’. Since it is also possible to ‘turn off’ individual curves between any two successive nodes, these figures can be both open and closed.

Entity nodes are added to the diagram by clicking the Add Node button in the top-right corner of the window. The user can select multiple locations first by shift-clicking onto the canvas at the locations where the new nodes should be placed. Essentially the same applies to contours, which are created using the Add Contour button. Note that there is no need to control the placement of diagram elements relative to the boundary of the canvas, since the texdraw package will automatically center the diagram within the available space during the eventual processing of the LaTeX file.

Once a number of entity nodes have been created, the next step is typically to attach ornaments to them or to create connectors between them. The steps for this are as follows. First, one or more entity nodes are selected, either by clicking (holding the Shift key pressed to select more than one) or by drawing a ‘box’ around them, and then the pull-down menu on the right side of the interface can be used to choose the kind of connector or ornament to be created. Clicking on the ‘Create’ button will then create the corresponding number of ornaments or connectors. In the case of connectors, the order in which the nodes are selected determines how they are connected with each other. For example, if three nodes are selected (each of them once), then clicking on ‘Create’ will result in one connector from the first node to the second, and another connector from the second to the third. There is also a variant to this: by using the keyboard command Shift+Space, one can connect the first selected node to each of the others.

Almost any kind of shape can be created by modifying a contour. Clicking on the ‘Add Contour’ button will make a contour appear in the middle of the canvas or at whichever location has been selected last. Initially, this contour will consist of eight nodes defining a rectangle with rounded corners. More nodes can be added to an existing contour by clicking the ‘Add Node’ button in the editor pane (the left-most tab below the two ‘create’ buttons). To delete a node from a contour, first select it and then click on the ‘Delete’ button (i.e., the right-most in the row of buttons below the editor pane). There is also a number of keyboard commands for these and other purposes.

Selecting any object will make a corresponding set of controls appear in the editor pane, where the object in question can be modified. For example, to edit the text of a label, one would first click on that label and then edit its text in the text area that is shown in the editor pane. Connectors deserve special mention here, since they can’t strictly speaking be selected themselves: instead, one selects just their corresponding connector-nodes. But in the editor pane of such a node, one can then also modify parameters of the corresponding connector. Indeed, the parameters relating to the connector will make up the majority of the entries, which are organized in up to three groups: ‘Line Properties’, ‘Arrow Head’ (where applicable), and ‘Node Properties’. Only the last group relates to the parameters of the connector node itself.

The objects that can be selected comprise entity nodes, contour nodes, and ornaments, such as labels and pointers. It is also possible to select mere locations on the canvas simply by clicking at them. (Entity and contour nodes can also be selected by drawing a box around them. Usually, however, this will ignore ‘implicit’ – and thus invisible – connector nodes. Hold the Alt key pressed in order to select those as well.) When a contour node is selected, all the other nodes of that contour will usually also become selected, but only the marker of the primarily selected node will be blinking. This node is the one whose values are displayed in the editor pane. The other nodes are selected by virtue of their being members of the same group as the primarily selected node.

All and only contour nodes are members of a special kind of group, called ‘contour node group’. Entity nodes, ornaments, and groups themselves can, by contrast, become members of ‘standard groups’. The sole effect of two objects’ being members of the same group is that, if one is selected, all other members will be selected as well (although the details are a little more complicated, due to the fact that (a) groups can themselves be members of other groups, and (b) memberships can be temporarily ‘suspended’, or, in the shorter terms of the button-labels: a member can ‘leave’ its group and later ‘rejoin’ it). But this simple fact nevertheless makes grouping a powerful tool, since, along with the primarily selected object, every object selected will also be edited, as long as it has the feature that is being edited. Similarly, by dragging one object to another location, the other selected objects will be dragged along with the former, complete with their labels, pointers, and the connectors between them. The same applies to copying and the transformations available under the Transform tab.

Already selected node can be deselected by clicking on or drawing a box around them while holding the Control key pressed. On the other hand, clicking on an unselected node with the Control key pressed will select only that node and deselect all others, even if they belong to the same group as the first one. By pressing both Ctrl and Shift, the user can add a node to the selection without at the same time selecting all the other nodes of its group. The ‘Focus’ (F) and ‘Defocus’ (D) keys are also useful for changing the selection (see Keyboard Commands).

When the diagram is finished, the corresponding LaTeX code (together with annotations to help later reconstruction, called ‘metadata’) can be generated by clicking on the Generate button in the bottom-right corner of the window. The code will appear in a text area below the diagram, from where one can copy and paste it directly into a LaTeX-file. If this is for some reason not possible (e.g., in some operating systems), there will still be the option of sending the code to this very web-page by clicking on the button to the bottom right of the applet’s text area. The code will then appear in a text area below that part of the applet that contains the ‘New Window’ button, in the previous section. (Apple Users may have to rely exclusively on drag-and-drop.)

The following code example shows how the generated code is inserted into a LaTeX file. The blue portion is the code generated by Pasi:

Once the code is copied into a LaTeX file, LaTeX can be run in the usual way to create (for instance) a DVI file. DVI files can in turn be translated into PNG image files using the program dvipng, which is already included, e.g., in the MiKTeX distribution of LaTeX. Finally, standard image conversion software can be used to translate a created PNG file into a JPG, GIF or other kind of image file.

The code generated by Pasi can be ‘read back’ into the applet using the following procedure. First, click on the Load... button in the bottom-right corner: this will open a text area in the lower half of the window, and another Load button will appear along with it. Then paste the code into the text area, and click on this second Load button. Unless the entered code contains changes made after it was generated, Pasi will then reconstruct the original diagram.

Finally, I should note that a web-connection is necessary only for loading Pasi into one’s browser. Once loaded, it will stay fully functional even if the connection is interrupted.

I would like to thank my teachers Gillian Russell and Joe Ullian for giving seminars that provided me with the opportunity to develop Pasi.