Help

About

This is a viewer for decision maps, which record decisions made and places discovered during an exploration process. It has multiple tools for visualizing the sequence of decision graphs that represents an exploration process, including:

• Overview: This view shows a single decision graph, representing one step of the exploration. You can select which step to view, with the last step being the default. You can zoom in and out and pan around. The graph layout is based on force simulation, with a fixed starting layout.
• Focus: This view shows information about a single decision at the current step, including all of its neighbors (but not the rest of the graph). Click on a neighbor to focus on that decision instead.
• Edit: This view always shows the latest exploration step, and includes controls that allow for editing the graph and/or adding steps. Click on blank space to create a new option at the current decision, click on an unexplored option node to add a new step that explores that node, and click on an explored node to add a step that traverses to that node (either via 'take' from the current position if adjacent or via 'warp' if not). TODO
• Chart: This view provides a more abstract view of the exploration trace, showing a histogram or time-series of one of several properties, like the number of transitions at each decision. TODO

At the top left, the controls area shows global controls and view-specific controls (described in the help sections for each view).

At the top right, there is a legend that shows the styles used for the current view. See the legend section for more details.

On the bottom left, the current view is displayed.

On the bottom right, the listing displays the name of each decision, along with its assigned symbol (if any), and a few other stats about that decision. You can click on nodes in the listing to select/deselect them.

Controls

The global controls are:

• The “show” drop-down menu controls which view is displayed.
• The “step” slider and “prev/next” buttons allow you to change which step of the exploration you're viewing. These are disabled in situations where the step is fixed or you're viewing information from all steps
• The “background” file picker allows you to upload a background image.
• The “clear selection” button allows you to deselect all currently selected nodes.
• The “markers” slider which controls how large each node is.
• The “transparency” check box controls whether node symbols are displayed using solid or transparent colors. Transparency helps the labels stand out a bit more, especially if you are going to display a visualization in grayscale.
• The “start from scratch” button allows you to create a new empty exploration. It puts you into the "edit" view automatically.
• The “rerun analysis” button allows you to run analysis on the entire current exploration. Use it after you've made some edits if you want to update analysis results
• The “load” button allows you to load a new exploration from a file.
• The “save” button allows you to save the current exploration to a file.

Overview

The overview displays the connections among all nodes in the graph at the current step, using one of several automatic layouts, plus a force simulation that tries to ensure most connections aren't too long but also that decisions don't get too close to each other.

You can drag around the nodes to adjust their position, but when you do that, those nodes will become fixed in place (you can click the tab that this adds to remove the pin). By hovering over a node or selecting nodes (by clicking on them), you can limit which edges are shown, and hovering on a node or edge for a moment will display information about it.

The controls for this view are:

• The “layout” selector, which allows you to switch between the “strict,” “loose,” and “relaxed” layouts (see below), plus pick a layout strategy for their initial positions.
• The “reset layout” button, which puts nodes back to their original positions for the selected layout.
• The “relax further” button, which allows the nodes to settle more under the physical simulation rules (see below).

The position of the nodes is governed by two processes: the initial layout, and a physical simulation that includes several simulated forces.

Initial Layout

The initial layout results can be viewed without running the physical simulation at all by selecting the “strict” layout option. Here's how each layout option works:

1. The “hive” layout places nodes on a triangular grid. To place each node, the following algorithm is used:

   1. At each step, select a single decision to place on the graph, based on the order in which decisions were observed during exploration, breaking ties alphabetically by decision name.
   2. Next, place that node on the graph:
      • For the first step, place it at the origin (0, 0).
      • For subsequent nodes, examine all empty grid locations that are adjacent to an already-placed node:
        • At each location, compute the cost for that location as the sum of the link lengths of each link from this node to a node that’s already been placed.
        • Pick the location that has the lowest total cost, and put the node there. Ties are broken by choosing locations that are closer to the origin, and double-ties are broken by choosing the edge position that was added to the list of edge positions first.
      • Finally, repeat steps 1 and 2 until all nodes have been placed (including nodes not connected to the original node).

   This algorithm normally results in a roughly hexagonal group of nodes, even when connections aren’t thick, because it breaks ties towards the origin. The default listing sort order for this view shows the order in which nodes were added, which can help understand the layout.

2. The “final” layout places nodes into a square, going first across to the right and then down rows by node ID (IDs are assigned in the order nodes are created).
3. The “baryeccentric” layout places nodes according to the baryeccentricLayout function in the exploration.display module. It selects three distant-from-each-other nodes as triangulation points and places each other node between or around them according to its path distance from those three nodes.
4. The “path” layout places nodes on a gentle arc according to the order in which they were visited, putting unvisited nodes above the nodes they are options from. This layout tries to avoid straight lines by putting nodes in an arc so that relaxing it will be unambiguous and so that otherwise overlapping edges are more visible.

Physical Simulation

Once the nodes are positioned in this grid, in the “loose” and “relaxed” layouts, or when the “relax further” button is pressed, we relax those positions by simulating a few physical forces acting on the nodes in two dimensions. The main forces are:

• A repulsion force that pushes all nodes away from each other when they get too close. This prevents nodes from piling up and obscuring each other, but it also is the primary source of distortion that causes nodes not to be positioned as close to their neighbors as they would naturally be.
• A weaker repulsion force that pushes all nodes away from each other over any distance. This helps avoid nodes clustering too closely together and ideally keeps the layout more legible.
• An attraction force along each link, pulling them closer to each other until they reach an ideal distance or pushing them apart if they're too close. This gets stronger the farther the link is stretched or compressed. Ideal distances are smaller for nodes in the same zone compared to nodes in different zones.

In addition to these two main forces, there is a gathering force that pulls all nodes towards the origin. This ensures that disconnected nodes do not drift away from the main part of the graph. This force is fairly weak, so it does not introduce very much distortion.

The “loose” and “relaxed” layouts apply different amounts of simulation to relax the graph. The “relax further” button can always be used to see the consequences of more simulation updates. The “loose” layout is an intermediate between the rigid grid of the “strict” layout and the more relaxed positions of the “relaxed” layout.

Focus

This view shows detailed information about all of the options at a single decision at a particular exploration step. This focus node is in the center, and can be switched by picking from the listing on the right, or by clicking on another non-focus node (TODO: implement this). All nodes that are connected to the focus node are arrayed in a circle around the focus node, ordered by their order of appearance in the exploration, starting from 0 degrees on the right and proceeding clockwise.

The control area for this view displays the ID of the focus decision.

Edit

In this view, the last exploration step is always displayed, and you can click or use the controls to edit the graph and/or add exploration steps.

By default the current step's primary decision is selected. Clicking on the graph area can do a few different things:

• Clicking on blank space will add a new unexplored decision at that location, connected to the currently-selected decision by a new transition. The new decision will be named according to its layout coordinates and the new transition will be named automatically according to its direction from the selected decision. TODO
• Clicking on an unexplored decision will add a new step to the exploration which explores that decision, taking the alphabetically first transition that leads there from the current primary decision. If the unexplored decision you selected was no connected to the current primary decision, then two steps are added: one that transitions to (if adjacent) or warps to (if not) one of the unexplored node's explored neighbors (first by ID), and a second that explores a transition from that neighbor to the clicked-on node. TODO
• Clicking on a transition adds a step that takes that transition, exploring its destination if it had been unexplored. If the transition is outgoing from the current primary decision, we just take/explore it; if not, we add two steps: one that moves/warps to the source of the transition and another that takes it. TODO
• Clicking on an explored decision adds a new step to the exploration that moves to that decision, either via a transition if it's adjacent to the current primary decision, or via a warp. TODO

Additional controls for the edit view allow for:

• Undoing the most recent edit or re-doing an undone edit. Full undo/redo history is maintained, although redo history is reset when a new edit is made. TODO
• Adding a 'wait' step to the current exploration in which no action is taken. This can be useful for splitting observations of unexplored options across multiple steps if that makes sense. TODO

Histogram

This view helps provide context for the edge weights used in the other views. By displaying a histogram of values (such as interactions, which is total initiated + received weight) this view gives a sense of how large or small a particular value is relative to all of the nodes in the graph. Each histogram displays a list of numbers along the x-axis, which are the distinct values present among all nodes, and for each value, there’s a bar indicating how many nodes had that much total edge weight, with a number on top indicating the precise count. So the x-axis is the combined edge weight (or # of neighbors) depending on which graph is selected, and the y-axis is the total number of nodes that have that combined edge weight (or # of neighbors).

This view can plot a histogram of the initiated weight, the received weight or the initiated + received weight (interactions). It can also plot a histogram of the number of neighbors each node has. In addition, you can select two histograms at once and it will plot one above the x-axis and one below so you can compare them visually (this really only makes sense for comparing among initiated, received and initiated + received graphs).

The width of each bar is determined by how many bars can fit in the graph area, but there is a minimum, and so if there are too many distinct values to display, you will have to scroll the graph horizontally to see them all. The height of the bars is determined such that the largest bar fills up the available vertical space, so only relative heights are relevant. When two graphs are shown, they are not scaled independently, so that the relative height of bars above and below the x-axis can be compared directly.

The controls for this view are:

• The “graph” and “compare” selectors, along with a check box for “compare.” The check box can be used to disable or enable comparison, and the selectors let you decide which values to plot.
• The “collapse values” check box controls how the x-axis is laid out. If checked (the default) then the x-axis will be compressed and numbers for which there is no node that has that much total weight (or that many neighbors) are not shown. This view makes it easier to see all of the bars at once, but means that distance along the x-axis is an unreliable indicator of relative total weight. If this box is unchecked, every integer will be shown on the x-axis up to the number for the node with the largest total weight (or largest neighborhood), which will usually force the graph to be scrolled to view all bars. Numbers where there are no corresponding nodes will have no bar above them. In this view, scrolling is usually necessary, but horizontal comparisons of position are valid.

In the histogram view, selection works a bit differently than in other views. You can still use the listing to select individual nodes, and this will highlight the bar(s) that they belong to (hovering on a bar will also display the ID of all nodes associated with it, although in some cases the list may be too long to fit on the screen). However, clicking on a bar will select all nodes that belong to that bar, and any other bar(s) they belong to (in the comparison view). Whether all or only some nodes at a bar are selected (e.g., because they were selected using the listing), clicking on that bar deselects all of them. So if you want to know which nodes have a total outgoing weight of exactly 5, you can select the “initiated” histogram, and click on the bar above the number 5 on the x-axis.

Legend

In the top-right of the window, there is a “Legend” panel which displays a legend for the current graph. In the overview, focus, and path views, this displays one style for each region, along with the name of that region. In the histogram view, it displays the different styles used for each different value that can be used to plot a histogram, which is useful when comparing histograms to distinguish which is which.

The regions and their names are defined as part of the dataset (we use level-1 zones by default).

Listing

The listing area is on the right of the screen, and contains a list of all decisions in the graph. It has controls for sorting or filtering decisions, and also displays key statistics for each decision.

The stats displayed are TODO

The controls for the listing area are:

• The “sort by” drop-down menu allows you to pick a property to sort by. Each property includes various fall-backs for breaking ties, usually in terms of whatever hasn’t been considered in the initial sort. The “default” sort order depends on the current view:
  • For the overview and path views, it sorts according to the order nodes were discovered during exploration.
  • For the focus view, it sorts first by whether or not a decision is a neighbor of the current focus node, and then by step discovered.
  • For the histograms view the graph is sorted by the property used in the currently selected primary histogram.
• The “find” text field allows you to type part of a decision name and the listing will be filtered as you type to show only nodes that contain the fragment you’ve typed as part of their ID (ignoring case). The clear button directly after the filter input just clears what you’ve typed and resets the filter; deleting everything in the text box also effectively resets the filter.

Legend ?