Interaction

NetPanorama supports interactivity by allowing users to define parameters whose values are updated by interactions, and by using these parameters to update visualization.

It supports two main types of parameters:

Variable parameters, which can be updated by UI controls such as sliders or checkboxes.
Selection parameters, which can be updated by clicking on elements, using a rectangular brush, or making a lasso selection

Interaction without parameters

Some forms of interaction occur directly, without adjusting the value of intermediate parameters.

To disambiguate between multiple interactions that involve the cursor, you can specify a list of modifier keys that must be held down during an interaction (modifierKeyRequired) and/or keys that must not be held down (modifierKeyAbsent).

Tooltips

Mousing-over an element can display text in a tooltip.

The contents of the tooltip are set by the tooltip attribute on the mark, which can be either a field-name or an expression.

{
      "entries": "net.nodes",
      "layout": "net-layout",
      "mark": {
        "type": "circle",
        "area": 70,
        "fill": "steelblue",
        "tooltip": {  "field": "label" }
      }
    }

    {
      "entries": "le-mis-network.links",
      "layout": "l",
      "mark": {
        "type": "square",
        "size": 100,
        "fill":  {"expression": "datum.source.id < datum.target.id ? 'red' : 'blue' " },
        "tooltip": {"expression": "datum.target.name + '<-->' + datum.source.name "}

      }
    }

Dragging to re-position nodes

For example, if the positions of elements were determined by a layout, then they can be made draggable such that dragging them with a mouse directly updates the underlying layout.

    {
      "entries": "le-mis-network.nodes",
      "layout": "le-mis-layout",
      "actions": [
          { "interaction": "drag" }
      ],
      "mark": {
        "type": "circle",
        "area": { "field": "degree", "scale": "radius" },
        "fill":   { "field": "degree", "scale": "color" }
      }
    }

Panning and zooming

Adding a zoom attribute to the top-level of the specification enables zooming. A zoom object can also have optional min: number and/or max: number attributes to specify the minimum and maximum scaling factor possible.

Adding a pan attribute to the top-level of the specification enables panning. A pan object can also have optional min: [number, number] and/or max: [number, number] attributes to specify the minimum and maximum x,y panning values.

View example in editor

Fixing coordinates

Any mark or layout specification can also be given a fixPanZoom: "x" | "y" | "both" attribute to fix the x, y or both coordinates of a group of mark.

View example in editor

Variable parameters

Variable parameters can be bound to UI controls.

note

The scope of places where parameters can be used will be increased.

Their values can then be used to set properties.

  "parameters": [
    {
      "name": "r",
      "bind": {
        "input": "range",
        "label": "Size",
        "min": "20",
        "max": "400",
        "step": "2"
      }
    },
    {
      "name": "color",
      "bind": {
        "input": "color",
        "label": "Color",
        "value": "#ef2929"
      }
    }
  ],

Attribute	Type	Description
name	string	The name of the parameter.
value?	any	The default vale of the parameter.
bind?	Binding	Binds the parameter to an input element.
animate?	Animation	Specification for how the parameter should be animated.

Binding to UI Elements

Binding a parameter to a UI element allows a user to update the parameter's value by interacting with a control such as a slider or selection box.

Attribute	Type	Description
input?	"checkbox" or "radio" or "range" or "select"	The type of input element to use.
element?	string	An optional CSS selector string indicating the parent element to which the input element should be added.
label?	string	Label to use for the input element (by default, the name of the bound signal will be used).
a	string	Values for attributes to set on the HTML element.

Additional attributes for a radio or selection box:

Attribute	Type	Description
input	"radio" or "selection"
options	any[]	Array of the available options.
labels?	string[]	Array containing labels for the options. By default, the label is the obtained by converting the option value to a string.

options???

Additional attributes for a range input:

Attribute	Type	Description
input	"range"
max?	number	Maximum slider value. Defaults to 100 (or the default signal value, if that is larger).
min?	number	The minimum slider value. Defaults to 0 (or the default signal value, if that is smaller).
step?	number	The minimum slider increment.

Additional attributes for binding to a pre-existing HTML control (not created by NetPanorama):

Attribute	Type	Description
input	undefined
element	string	CSS selector for an input element.
event?	string	The name of the event to listen for (default is oninput).
event?	string	The name of the event to listen for (default is oninput).

It is also possible to bind a parameter to the range of a brush draw on an axis. For example, this can be used to allow a brushing interaction to filter nodes based on their degree. In order to determine the scale for this axis, it is necessary to specify which network is to be filtered, whether nodes or links are to be filtered, and which field wll be filtered on.

Attribute	Type	Description
axisType	"linear" or "time"
network	string	Name of the network to be filtered.
for	"nodes" or "links"	Whether this control will be used to filter nodes or edges.
field	string	The field on the node or link to be filtered.
updateContinuously?	boolean	If set to true, parameter will be updated continuously as the brush is moved, without waiting for interaction to end.
updateContinuously?	boolean	If set to true, parameter will be updated continuously as the brush is moved, without waiting for interaction to end.

Animation

It is possible to animate between successive values of a parameter. Note that NetPanorama currently re-renders for each new parameter frame, rather than smoothly interpolating.

Attribute	Type	Description
label?	string	Label displayed by animation controls (by default, the name of the parameter will be used)
min	number	Minimum values for the animation
max	number	Maximum value for the animation.
values	(string or number)[]	Array of discrete values to transition between.
stepTime?	number	Time, in seconds, between updates to the parameter's value. Incompatible with totalTime option.
totalTime?	number	Time taken for a complete cycle of the animation. Incompatible with stepTime option.
stepSize?	number	Value by which the parameter should be increased on each update. Incompatible with the numSteps option.
numSteps?	number	Total number of updates in one cycle of the animation. Incompatible with the stepSize option.
autoStart?	boolean	If true, the animation will start automatically; if false, animation will not start until the pay button is pressed.
loop?	boolean	If true, the animation will loop: after reaching the max value, the parameter wil reset to the min value and begin increasing again.
showPauseControl?	boolean	If true, display a play/pause button.
showStepControl?	boolean	If true, display a button that allows users to step the next/previous state of the animation.
showJumpControl?	boolean	If true, display a button allowing users to jump to the first/last state of the animation.
showValue?	boolean	If true, display the current value of the parameter.
showValue?	boolean	If true, display the current value of the parameter.

Selection parameters

Selection parameters contain a set of nodes and a set of edges.

They can be updated by interacting with a visualization. Optionally, dragging can reposition all selected nodes simultaneously.

Specifically, you can define actions that update a selection (by adding elements, removing elements, toggling whether elements are present, or replacing the elements in the selection), in response to a specific type of interaction (clicking on an element, using a rectangular brush, or making a lasso selection), when certain modifier keys are held down and others are not.

Selection definitions

Selections are defined in the selections attribute of the top-level of the specification.

Attribute	Type	Description
name	string	Name of the selection parameter.
value?	string[]	Initial value of selection.
type	"selection"	Initial value of selection.
network	string	Name of the corresponding network.
dragging?	Dragging	If set, then dragging whilst holding down these keys will move the selected nodes.
clearOnBackgroundClick	Boolean	If true, then clicking on the background will clear the current selection.

Dragging:

Attribute	Type	Description
modifierKeyRequired?	ModifierKeys[]	Key that must be held down whilst the interaction occurs (default is "any").
modifierKeyAbsent?	ModifierKeys[]	Key that must be not held down whilst the interaction occurs (default is none).

Interaction definitions

The interactions that modify selections (like interactions that allow dragging) are defined in the actions attribute of the vis block that defines the visual marks to which they apply.

Attribute	Type	Description
interaction	"select"
event?	"click" or "mouseenter" or "mouseleave" or "mouseover" or "mouseout"	The type of event that triggers this interaction (default is "click").
using?	"rect" or "lasso" or "cursor"	The interaction type to be handled.
selection	string	The name of the selection to update
action	"add" or "remove" or "replace" or "toggle"	How to update the selection (default is "replace")
modifierKeyRequired?	ModifierKeys[]	Key that must be held down whilst the interaction occurs (default is "any").
modifierKeyAbsent?	ModifierKeys[]	Key that must be not held down whilst the interaction occurs (default is "any").
modifierKeyAbsent?	ModifierKeys[]	Key that must be not held down whilst the interaction occurs (default is "any").

A ModifierKeys is one of "alt", "ctrl", "meta" (i.e., the Apple or Window key on a keyboard), "shift".

Derived selections

A selection may be transformed to give a new, derived, selection (e.g., by selecting the neighbours of selected nodes).

Attribute	Type	Description
name	string	Name of the derived selection.
source	string	Name of the selection from this selection is derived.
transform	SelectionTransform[]	List of selections that will be applied to the source selection to obtain this selection.

Transformations

As well as the individual attributes listed below, all transformations also have an action attribute that can be either "add" or "replace", depending on whether or not their output should include the original nodes and edges.

Shortest Path

Find the shortest path between a selection containing a pair of nodes (if the selection contains more than 2 nodes, the path is found between the first 2 nodes, and the remained are ignored).If selection contains more than 2 nodes, it will find the shortest path between all pairs of nodes.

Attribute	Type	Description
type	"shortestPath"
weight?	string	Field name containing the edge weight (this could be pre-computed with a calculate transform).As we use Dijiska's algorithm, all weights must be positive.

Prune

Attribute	Type	Description
type	"prune"
remove	"roots" or "leaves" or "isolated"	Specifies whether to remove nodes with no incoming connections ("roots"), nodes with no outgoing connections ("leaves")or no connections at all ("isolated").

Filter

Filter (either nodes or edges) retaining only those for which the expression is true.

Attribute	Type	Description
type	"filter"
affects	"nodes" or "edges"	Whether the filter expression applies to nodes or edges.
expression	string	The expression to evaluate for each edge.

Project

Given a selection, make a new selection containing elements for which the specified fields hae the same values.

Attribute	Type	Description
type	"project"
affects	"nodes" or "edges"	.Whether the operation applies to nodes or edges.
fields	string[]	List of fields to match on.
semantics?	"separate" or "combined"	If selection contains "red cars" and "blue bikes", should we also select "red bikes" and "blue cars"?

Parallel Edges

Select edges with the same source and target nodes as edges in a selection.

Attribute	Type	Description
type	"parallelEdges"
ignoreDirection?	boolean	Select edges with the same source and target nodes as edges in a selection.

Common Neighbours

Select the nodes connected to all the nodes in a selection.

Attribute	Type	Description
type	"commonNeighbours"
direction	"source" or "target" or "both"	Select the nodes connected to all the nodes in a selection.

Connected Nodes

Select the nodes connected to a set of edges.

Attribute	Type	Description
type	"connectedNodes"
direction	"source" or "target" or "both"	Select the nodes connected to a set of edges.

Connected Edges

Select the edges connected to a set of nodes.

Attribute	Type	Description
type	"connectedEdges"
direction	"source" or "target" or "both"	Select the edges connected to a set of nodes.

Edges Between

Find the edges joining nodes in one selection with nodes in a second selection.

Attribute	Type	Description
type	"connectedEdges"
secondSelection	string	Find the edges joining nodes in one selection with nodes in a second selection.
ignoreDirection?	boolean	Find the edges joining nodes in one selection with nodes in a second selection.

Neghbours

Find the neighbours of a node (or set of nodes)

Attribute	Type	Description
type	"neighbours"
direction	"in" or "out" or "both"	Find the neighbours of a node (or set of nodes)
depth?	number or "infinity"	default 1
depth?	number or "infinity"	default 1

Interaction without parameters​

Tooltips​

Dragging to re-position nodes​

Panning and zooming​

Fixing coordinates​

Variable parameters​

Binding to UI Elements​

Animation​

Selection parameters​

Selection definitions​

Interaction definitions​

Derived selections​

Transformations​

Shortest Path​

Prune​

Filter​

Project​

Parallel Edges​

Common Neighbours​

Connected Nodes​

Connected Edges​

Edges Between​

Neghbours​