Visual Encodings

Each specification has a vis entry, which contains a list of visual mappings.

Each of these is a mappings from a set of data elements to set of visual marks.

The definition of this mapping has several parts:

• Which data elements are to be mapped. This may be specified by setting the entries attribute to the name of a a loaded dataset, grouping, or the nodes or links or a network. Alternatively, they may be the entries of a table.
• How the representation of each element should be positioned. If a table is being used, then the positions will be set automatically. Otherwise, the layout attribute to the name of a layout. Alternatively, the position can be set explicitly for each mark.
• What visual marks should actually be drawn for each data element. This is specified as a list of mark definitions.
• optionally, whether rendering should be restricted to data elements that belong to a particular selection

Types of Vis Entry

For Non-tables

Attribute	Type	Description
entries	string	Name of the dataset/grouping/network to render.
layout?	string	Name of the layout ot be used to assign a position to each element.
drawAxes?	boolean	If true, will draw axes corresponding to the layout.
border?	boolean or BorderSpec	If true, will draw rectangular border around entry. Can be an object, with stroke/strokeWidth/strokeOpacity/strokeDash attributes controlling appearance.
ifInSelection?	string	The name of a selection: if set, the mark will only be drawn for data elements that are included in the selection.
if?	string	An optional expression: if specified, the mark will only be drawn for data elements for which the expression evaluates to true.
mark	Mark[]	Mark to be created for each data element.
occlusion?	OcclusionSpec	If specified, remove overlaps between marks with an occlusion mechanism.

An OcclusionSpec object is defined by:

Attribute	Type	Description
importance?	Field or Expression	Importance function to use to determine which node is removed first when an overlap is detected. A field can be specified to show in priority the entries with the highest value. A random order is used if not specified
density?	number	Specify a factor on the dimensions of the labels used when computing the occlusion. For higher values, less labels will be shown with larger gaps. Default to 1.
shrinkLabels?	boolean	If true, when labels overlap, starts by dividing the fontsize by two before removing them. Default to false.

For Tables

Attribute	Type	Description
table	string	Name of the table to render.
rowLabels?	any	Specification for row labels.
colLabels?	any	Specification for column labels.
rowLines?	any	Properties for ruled horizontal lines between each row in the table.
rowMidLines?	any	Properties for ruled horizontal lines through the middle of each row in the table.
colLines?	any	Properties for ruled vertical lines between each column in the table.
colMidLines?	any	Properties for ruled vertical lines through the middle of each column in the table.
colMidLines?	any	Properties for ruled vertical lines through the middle of each column in the table.
ifInSelection?	string	The name of a selection: if set, the mark will only be drawn for data elements that are included in the selection.
if?	string	An optional expression: if specified, the mark will only be drawn for data elements for which the expression evaluates to true.
mark	Mark[]	Mark to be created for each data element

Conditional rendering

You can control the appearance of elements conditionally (including setting the fill color or opacity so that they are not visible) by using an expression or using a condition.

You can specify that an entry in the vis block should only be rendered for elements in the corresponding list of entries if they belong to a specified selection. This allows you to render labels or highlighting halos for only selected nodes.

{
  "entries": "le-mis-network.nodes",
  "ifInSelection": "neighbours.nodes",
  "layout": "le-mis-layout",
  "mark": {
    "type": "circle",
    "area": 600,
    "fill": "lightblue"
  }
}

Nesting

Rather than directly defining a list of visual marks, an entry in the vis array can also include definition for other objects (scales, groupings etc.) and a vis block.

This allows the creation of nested visualizations.

View example in editor

Marks

note

NetPanorama uses a similar set of graphical marks and properties to the marks in Vega. However, there are some additions:

• more options for visually representing links
• conditions are similar to Vega-lite conditions, but are extended to allow multiple conditions, and conditions referring to selections
• supprot for rendering map tiles

The values of specific property of marks encoding a data element may be specified as:

• a constant value (e.g, "fill": red")
• a parameter (e.g, "fill": { "parameter": "color" })
• the value of a specific field of the data element (e.g,"fill": { "field": "color" })
• the value of a specific field of the data element, after transformation by a scale (e.g, "fill": { "parameter": "age", "scale": "colorScale" })
• the value of an expression or formula (which can reference the data element as datum) (e.g, "tooltip": { "expression": "datum.name + ' (' + datum.age + ')' " })

Additionally, a condition may specify alternative ways of setting the value depending on a particular expression (or membership of a selection)

Scaling

Netpanorama integrates zooming easily with the global zoom property. By default, for better readability, the size of visual marks is not scaled with the zoom, meaning that a circle will always have the same radius, before of after zooming in. The scaling property inside a mark definition can be set to true to make marks scale proportionally to the active zoom.

Clipping

The clip property can be used on a visual mark definition similarly as in vega. However, it behaves slightly differently and is used to clip marks when a translation is applied through panning and zooming.

Using an expression

You can set the value of a visual property using an expression . This may use a JavaScript ternary operator.

{
      "entries": "network.nodes",
      "layout": "layout",
      "mark": {
        "type": "circle",
        "area": { "field": "degree", "scale": "radius" },
        "fill": {"expression": "datum._type === 'person' ? 'red' : 'white' "}
      }
}

Using a condition

When specifying the value of a property, you can provide a condition object. If this evaluates to true, then the value that it provides overrides whatever other value is provided.

The condition can be specified as one of:

• a test attribute, containing an expression
• an inSelection attribute, with the name of a selection as a value
• a selectionIsEmpty attribute, with the name of a selection as a value
• a selectionIsNotEmpty attribute, with the name of a selection as a value

{
  "entries": "le-mis-network.nodes",
  "layout": "le-mis-layout",
  "mark": {
    "type": "circle",
    "area": { "field": "degree", "scale": "radius" },
    
    "fill":   {
        // if a node has a degree > 10, color it blue
        "condition": {
            "test": "datum.degree > 10",
            "value": "blue"
        },
        // otherwise, apply the color scale to the degree
        "field": "degree", "scale": "color"
     }
  }
}

A series of conditions can be provided as an array of conditions:

      "mark": {
        "type": "circle",
        "area": { "field": "degree", "scale": "radius" },
        "fill":   {
            "conditions": [
                // if the node is selected, highlight it in blue
                {
                    "inSelection": "my_selection.nodes",
                    "value": "blue"
                },
                // if the node wasn't selected, but no nodes were, use the color scale
                {
                    "selectionIsEmpty": "my_selection.nodes",
                    "field": "degree", "scale": "color"
                }
            ],
            // otherise, some nodes were selected but this one wasn't, so draw it in grey
           "value": "lightgrey"
         }
      }

Nested Conditions

Conditions can also be specified in a nested way te following:

"mark": {
    "type": "circle",
    "fill": {
      "conditions": [
        {
          "test": "params.node_selection.nodes.length > 0",
          "value": {
            "conditions": [{
              "inSelection": "node_selection.nodes",
              "value": "red"
            }],
            "value": "blue"
          }
        },
        {
          "inSelection": "node_selection2.nodes"
          "value": "lightgray"
        }
      ],
      "value": ""
    },
  }

Maps

We also provide a specific map mark that is used to render map tiles, providing context for networks using a geographic layout.

This mark has type map, and a map attribute that contains the name of the map to be rendered.

See the maps section of the documentation for more details.

Links

We provide a specific linkpath mark that is intended to represent links, and is more customizable than a simple line.

As well as line properties such as color, dash pattern, stroke width, and stroke opacity, a marker can be added to one or both ends of the line.

Directionality can be encoded in several different ways:

• markers at one or both ends of the link
• a color gradient along the link
• representing the link as a sequence of glyphs, and applying a color gradient to these
• representing the edge as a wedge or triangle, rather than a line of uniform thickness
• using asymmetric curvature

Common attributes of all links types

Attribute	Type	Description
shape	string	The shape of the linkPath mark.
start	string	The name of the field in the link object pointing at the source node.
end	string	The name of the field in the link object pointing at the target node.
startMarker?	MarkerSpec	Definition of marker to be drawn at the start of an edge.
endMarker?	MarkerSpec	Definition of marker to be drawn at the end of an edge.
tooltip?	Value	Definition of marker to be drawn at the end of an edge.
directionForShape?	directionForShape	For some link types, the shape of the link depends on which node is treated as the source or target. If set, this determines how the two nodes will be interpreted by applying an ordering; this has no effect on the drawing of endMarkers.
colorGradient?	boolean or ColorGradient	Create a color gradient using the stroke color.

The directionForShape type can have the following attributes:

Attribute	Type	Description
ordering?	string	Name of an order to apply.
cyclic?	boolean	If true, will reverse the direction of edges from final element in order to first element in order.This is useful, for examples, when drawing hive plots.
reverse?	boolean	If true, reverse the ordering when it is applied.

The MarkerSpec type has the following attributes:

Attribute	Type	Description
stepBack?	number	Offset (in pixels) between the end of the edge and the marker.
shape	MarkerShape or LiteralOrFieldOrExpression	The marker shape.
direction?	"forwards" or "reverse"	If the direction is set to "reverse" then the marker will point towards the source node (rather than the target node).
fill?	string	Fill color for the marker.
opacity?	number	Opacity of the marker (0 is fully transparent, and 1 is fully opaque).
stroke?	string	Stroke color for the marker.
size?	number	Area of the bounding-box of the marker.

MarkerShape can be one of "triangle", "circle-triangle", "circle", "tee", "vee", "square", "diamond". "triangle-tee", or "triangle-cross".

LinkPathSpecWedge

Represent edges by wedges/triangles.

Attribute	Type	Description
shape	"wedge"
stroke?	string	Stroke color for the wedges.
strokeOpacity?	number	Opacity of the stroke around the edge of the wedge (0 is fully transparent, and 1 is fully opaque).
fill?	string	Fill color for the wedges.
opacity?	number	Opacity of the wedge (0 is fully transparent, and 1 is fully opaque).
direction?	"forwards" or "reverse"	If the direction is set to "reverse" then the wedge will point towards the source node (rather than the target node).
width?	number	Width of the widest past of the wedge.

LinkPathSpecGlyphs

Represent edges by a series of glyphs positioned along their lengths.

Attribute	Type	Description
shape	"glyphs"
glyphShape	MarkerShape	The shape of glyph to be used.
colorGradient?	ColorGradient	Specifies a color gradient along the line.
separation?	number	Distance between glyphs.
stroke?	string	Stroke color for outer edge of the glyphs.
strokeWidth?	number	Stroke width for the outer edge of the glyphs (in pixels).
strokeOpacity?	number	Opacity for the outer edge of the glyphs (0 is fully transparent, and 1 is fully opaque).
fill?	string	Fill color for the line.
opacity?	number	Opacity of the line (0 is fully transparent, and 1 is fully opaque).

LinkPathSpecLine

Represent edges by straight lines.

Attribute	Type	Description
shape	"line"
colorGradient?	ColorGradient	Specifies a color gradient along the line.
stroke?	string	Stroke color for the line.
strokeDash?	[number, number]	Dash pattern for the line ([dash length, gap length]).
strokeWidth?	number	Stroke width for the line (in pixels).
strokeOpacity?	number	Opacity for the curve (0 is fully transparent, and 1 is fully opaque).

LinkPathSpecCurveSymmetric

Represent edges by symmetric curves.

Attribute	Type	Description
shape	"curveSymmetric"
stroke?	string	Stroke color for the curve.
strokeDash?	[number, number]	Dash pattern for the line ([dash length, gap length]).
strokeWidth?	number	Stroke width for the curve (in pixels).
strokeOpacity?	number	Opacity for the curve (0 is fully transparent, and 1 is fully opaque).
swap?	boolean or "reverse"	If set to true, apply positiveAngle by using positions of two ends only, ignoring which is the source and which is the target.This can be useful if you are drawing an arc diagram and want to draw all arcs on the same side of the line of nodes, regardless of their direction.

LinkPathSpecCurve

Represent edges by asymmetric curves, with curvature distinguishing the source and target nodes.

Attribute	Type	Description
shape	"curve"
angle?	number	The angle controls the amount of curvature.The curve is a cubic Bezier curve, with control points positioned at the start and end nodes.The intermediate control point is obtained by taking the line segment from the source node to the midpoint of the source and edge, and rotating from the line joining the source and edge by angle.The angle is in degrees, so a value or 0 or 180 gives a straight line.
stroke?	string	Stroke color for the curve.
strokeDash?	[number, number]	Dash pattern for the line ([dash length, gap length])
strokeWidth?	number	Stroke width for the curve (in pixels).
strokeOpacity?	number	Opacity for the curve (0 is fully transparent, and 1 is fully opaque).

LinkPathSpecArc

Represent edges by semi-circular arcs curves.

Attribute	Type	Description
shape	"arc"
stroke?	string	Stroke color for the curve.
strokeDash?	[number, number]	Dash pattern for the line ([dash length, gap length])
strokeWidth?	number	Stroke width for the curve (in pixels).
strokeOpacity?	number	Opacity for the curve (0 is fully transparent, and 1 is fully opaque).
positiveAngle?	boolean	If positiveAngle is true (the default), then sweep-flag=1 for the generated path, and the path will be drawn in a "positive-angle" direction.As defined by the SVG Specification:"(i.e., the ellipse formula x=cx+rxcos(theta) and y=cy+rysin(theta) is evaluated such that theta starts at an angle corresponding to the current point and increases positively until the arc reaches (x,y))"
swap?	boolean or "reverse"	If set to true, apply positiveAngle by using positions of two ends only, ignoring which is the source and which is the target.This can be useful if you are drawing an arc diagram and want to draw all arcs on the same side of the line of nodes, regardless of their direction.

LinkPathSpecDiagonal

Represent edges by sigmoidal curves (the Vega LinkPath transform calls this a "diagonal").

Attribute	Type	Description
shape	"diagonal"
orientation?	"vertical" or "horizontal"	This parameter determines the orientation of the asymptotes of the sigmoid.
stroke?	string	Stroke color for the curve.
strokeDash?	[number, number]	Dash pattern for the line ([dash length, gap length])
strokeWidth?	number	Stroke width for the curve (in pixels).
strokeOpacity?	number	Opacity for the curve (0 is fully transparent, and 1 is fully opaque).

LinkPathSpecOrthogonal

Represent edges by a pair of vertical and horizontal lines.

Attribute	Type	Description
shape	"orthogonal"
orientation?	"vertical" or "horizontal"	Which direction to move first.
stroke?	string	Stroke color for the curve.
strokeDash?	[number, number]	Dash pattern for the line ([dash length, gap length])
strokeWidth?	number	Stroke width for the curve (in pixels).
strokeOpacity?	number	Opacity for the curve (0 is fully transparent, and 1 is fully opaque).

LinkPathSpecSquiggle

Represent edges by AbySS-Explorer style squiggles. The number of oscillations cna be set directly (as n), or indirectly by setting the spacing between them.

Attribute	Type	Description
shape	"squiggle"
n?	number	The number of squiggles.
spacing?	number	The spacing between squiggles.
amplitude?	number	The amplitude of the squiggles
stroke?	string	Stroke color for the curve.
strokeDash?	[number, number]	Dash pattern for the line ([dash length, gap length])
strokeWidth?	number	Stroke width for the curve (in pixels).
strokeOpacity?	number	Opacity for the curve (0 is fully transparent, and 1 is fully opaque).