NetworkFrame

A <Frame> that displays topological data, which differs from other forms of data visualization in that x and y position are less important than connections and enclosures. Examples include network diagrams, word trees, sankey diagrams and bubble charts. <NetworkFrame> charts render nodes and edges from arrays of nodes (which are optional) and arrays of edges (which are optional). Rendering and styling is based on each element's corresponding properties. NetworkFrame data elements are accessible by tabbing to the data group (nodes or edges) and hitting enter to arrow-key navigate through the data elements.

Nodes are automatically generated from edge references to source or target that do not exist, these nodes have createdByFrame: true if you want to treat them differently. Nodes are also decorated with a degree attribute, which is simple degree centrality (number of connections) if you want to use that.

import { NetworkFrame } from 'semiotic'

<NetworkFrame
   nodes={[{name: "Susie"}, {name: "Shirley"} ...]}
   edges={[{source: "Susie", target: "Xianlin"},{source: "Shirley", target: "Susie"}]}
   nodeStyle={{ fill: "blue" }}
   edgeStyle={{ stroke: "red" }}
   nodeIDAccessor={"name"}
/>

<API Reference>

• General Properties
  • size: {[width, height]}
  • networkType: {string | object | function }
  • title: {string | JSX}
  • margin: {number | object}
  • zoomToFit: { boolean }
• Node Rendering
  • nodeIDAccessor: {string | function}
  • nodeStyle: {object | function}
  • nodeLabels: { boolean | function }
  • nodeSizeAccessor: { number | function }
  • customNodeIcon { function }
• Edge Rendering
  • sourceAccessor: {string | function}
  • targetAccessor: {string | function}
  • edgeStyle: {object | function}
  • customEdgeType { string | object | function }
• Annotation and Decoration
  • tooltipContent: { function }
  • axis: { object }
  • oLabel: { bool | function }
  • annotations: { array }
  • legend: { object }
  • svgAnnotationRules: { function }
  • htmlAnnotationRules: { function }
  • annotationSettings: { object }
  • backgroundGraphics: { array | JSX }
  • foregroundGraphics: { array | JSX }
• Interaction
  • hoverAnnotation: { bool }
  • customHoverBehavior: { function }
  • customClickBehavior: { function }
  • customDoubleClickBehavior: { function }
  • interaction: { object }
• Miscellaneous
  • name: { string }
  • position: { array }
  • additionalDefs: { JSX }
  • download: { bool }
  • downloadFields: { array }

General Properties

size: {[width, height]}

If size is specified, sets the width and height of the frame from the array of values. The array must contain two numbers which represents the width and height, respectively.

Note: Margin will not be added to the frame size. It's more like CSS padding.

<NetworkFrame size={[500,500]} ... />

networkType: {string | object | function }

If networkType is specified, sets the network visualization method. Currently supports "force" or "motifs" or "wordcloud". Each type organizes network data differently, with "force" providing a typical force-directed network layout, motifs creating the same but with disconnected components placed as tiles, and "wordcloud" trying to use rectangular collision detection. Sending an object allows you to adjust advanced settings, like number of iterations and method specific settings like font size for "word cloud".

Another advanced setting for a hierarchical networkType is hierarchyChildren, which takes a function. By default this is equivalent to d => d.children. By setting it to d => d.values, for example, one can then use NetworkFrame with a hierarchy as returned by the nest().entries() function of d3-collection.

This will also support a "per-tick" function once the specifications can be figured out.

<!-- String option -->
<NetworkFrame networkType={"motifs"} ... />

<!-- Object option -->
<NetworkFrame networkType={{ type: "wordcloud" , rotate: d => d.topic_score < 1, fontSize: 36, fontWeight: 900 }} ... />

title: {string | JSX}

If title is specified, sets the text for the chart title, which appears centered at the top of the chart. The title can be either a string or JSX object.

<!-- String option -->
<NetworkFrame title={"Chart Title"} ... />

<!-- JSX option -->
<NetworkFrame title={<g><circle r={5} /><text>Chart Title</text></g>} ... />

margin: {number | object}

If margin is specified, sets the margin(s) on the frame. The margin can be set to one number, which is applied equally to all sides, or as an object.

<!-- Single number option -->
<NetworkFrame margin={10} ... />

<!-- Object option -->
<NetworkFrame margin={{ top: 5, bottom: 10, left: 15, right: 20 }} ... />

zoomToFit: { boolean }

If zoomToFit is set to true then the layout will be dynamically resized to fit within the available space. This could cause distortion but also prevents the disappearance of disconnected nodes and components.

<NetworkFrame zoomToFit={true} ... />

Node Rendering

(Also known as "vertices" or "friends")

nodeIDAccessor: {string | function}

If nodeIDAccessor is specified, determines how id values are accessed from the nodes array. In the case the data consists of an array of objects, a string can be used to assess the id value(s). A function can also be used to access the id value(s).

<!-- String option -->
<!-- e.g. data=[{employee: "Red"}, {employee: "Andy"}, ... ] -->
<NetworkFrame nodeIDAccessor={"employee"} ... />

<!-- Function option -->
<!-- e.g. data=[{employee: "Red"}, {employee: "Andy"}, ... ] -->
<NetworkFrame nodeIDAccessor={d => d.employee} ... />

nodeStyle: {object | function}

If nodeStyle is specified, determines the style of each rendered node. This can be a React style object or a function that takes the node datapoint and returns a React style object.

<!-- Object option -->
<NetworkFrame nodeStyle={{ stroke: "white", fill: "blue" }} ... />

<!-- Function option -->
<NetworkFrame nodeStyle={d => ({ stroke: "white", fill: d.color })} ... />

nodeClass: {string | function}

If nodeClass is specified, determines the CSS class of each rendered node. This can be a string or a function that takes the node datapoint and returns a string.

// Object option
<NetworkFrame nodeClass="friend" ... />

// Function option
<NetworkFrame nodeClass={d => d.friendType} ... />

nodeRenderMode: {string | function}

If nodeRenderMode is specified, determines the renderMode of the underlying Mark (such as "sketchy").

// Object option
<NetworkFrame nodeRenderMode="sketchy" ... />

// Function option
<NetworkFrame nodeRenderMode={d => d.friendshipLevel === "no so great" ? "sketchy" : undefined} ... />

nodeLabels: { boolean | function }

If nodeLabels is set to true then each node will have a text label with the id of the node. Will also accept a function that takes the node and returns SVG JSX to be placed in the label position.

<!-- Boolean option -->
<NetworkFrame nodeLabels={true} ... />

<!-- Function option -->
<NetworkFrame nodeLabels={d => d.degree > 5 ? <text>{d.id}</text> : null} ... />

nodeSizeAccessor: { number | function }

By default nodes are represented as SVG <circle> elements with r=5. Use nodeSizeAccessor to set a fixed size (with a number) or a dynamic size (with a function).

<!-- Number option -->
<NetworkFrame nodeSizeAccessor={10} ... />

<!-- Function option -->
<NetworkFrame nodeSizeAccessor={d => d.degree * 5} ... />

customNodeIcon { function }

A function taking the node datapoint and returning SVG JSX representation of the node.

<NetworkFrame customNodeIcon={d => <rect
    width={d.degree}
    height={d.degree}
    x={-d.degree / 2}
    y={-d.degree / 2}
    style={{ fill: d.createdByFrame ? "rgb(0, 162, 206)" : "rgb(179, 51, 29)" }}
/>} ... />

Edge Rendering

(Also known as "links" or "connections")

sourceAccessor: {string | function}

If sourceAccessor is specified, determines how source values are accessed from the edges data array. In the case the data consists of an array of objects, a string can be used to assess the source value(s). A function can also be used to access the source value(s).

<!-- String option -->
<!-- e.g. data=[{manager: "Red", report: "Andy"}, {manager: "Warden", report: "Red"}, ... ] -->
<NetworkFrame sourceAccessor={"manager"} ... />

<!-- Function option -->
<!-- e.g. data=[["Red", "Andy"], ["Warden", "Red"], ... ] -->
<NetworkFrame sourceAccessor={d => d[0]} ... />

targetAccessor: {string | function}

If targetAccessor is specified, determines how target values are accessed from the edges data array. In the case the data consists of an array of objects, a string can be used to assess the target value(s). A function can also be used to access the target value(s).

<!-- String option -->
<!-- e.g. data=[{manager: "Red", report: "Andy"}, {manager: "Warden", report: "Red"}, ... ] -->
<NetworkFrame targetAccessor={"report"} ... />

<!-- Function option -->
<!-- e.g. data=[["Red", "Andy"], ["Warden", "Red"], ... ] -->
<NetworkFrame targetAccessor ={d => d[1]} ... />

edgeStyle: {object | function}

If edgeStyle is specified, determines the style of each rendered edge. This can be a React style object or a function that takes the edge datapoint and returns a React style object.

<!-- Object option -->
<NetworkFrame edgeStyle={{ stroke: "red", fill: "darkred" }} ... />

<!-- Function option -->
<NetworkFrame edgeStyle={d => ({ stroke: "white", fill: d.source.color })} ... />

edgeClass: {string | function}

If edgeClass is specified, determines the CSS class of each rendered edge. This can be a string or a function that takes the edge datapoint and returns a string.

// Object option
<NetworkFrame edgeClass="friend" ... />

// Function option
<NetworkFrame edgeClass={d => d.friendType} ... />

edgeRenderMode: {string | function}

If edgeRenderMode is specified, determines the renderMode of the underlying Mark (such as "sketchy").

// Object option
<NetworkFrame edgeRenderMode="sketchy" ... />

// Function option
<NetworkFrame edgeRenderMode={d => d.friendshipLevel === "no so great" ? "sketchy" : undefined} ... />

edgeType { string | object | function }

A string (One of 'none','linearc','ribbon','arrowhead','halfarrow','nail','comet','taffy') or an object with { type } equal to one of these strings (with additional options depending on which edge type is selected) or a function that takes an edge datapoint and returns SVG JSX representation of the connection between two edges.

<!-- String option -->
<NetworkFrame edgeType="halfarrow" ... />

<!-- Object option -->
<NetworkFrame edgeType={{ type: "taffy", centerWidth: 1 }} ... />

<!-- Function option -->
<NetworkFrame edgeType={d => <line 
    x1={d.source.x}
    x2={d.target.x}
    y1={d.source.y}
    y2={d.target.y}
    style={{ stroke: "red" }}
/>} />

Annotation and Decoration

tooltipContent: { function }

A function returning JSX HTML to display in the tooltip (only active if hoverAnnotation is set to true). The tooltip is passed the node datapoint being hovered. The content is placed on and directly above the hovered point, so take that into account when using CSS to style the position and any additional elements. You can drop any HTML into this floating div, including another frame, if you want to have data visualization in your data visualization so you can visualize while you visualize.

annotations: { array }

An array of objects to be processed using the frame's built-in annotation rules or the custom defined rules. By default NetworkFrame supports the following annotation types:

• node: An object with an id value that corresponds to the ID value of a single node.
• d3-annotation or a D3-Annotation annotation class function: An object with an id that corresponds to a single node, along with traditional D3-Annotation object settings, which will then be modified to have the XY position of the referenced node.
• enclose: An object with an array of ids that corresponds to nodes that will be circled using the D3-Annotation CalloutCircle method.

legend: { object }

An object that defines the legend to be displayed on the frame. It uses the format seen in

<NetworkFrame legend={{
        legendGroups: [
          {
            styleFn: d => ({ fill: d.color, stroke: "black" }),
            items: [
              { label: "Area 1", color: "red" },
              { label: "Area 2", color: "blue" }
            ]
          }
        ]
      }} ... />

svgAnnotationRules: { function }

A function that takes an annotation object and returns a JSX SVG element. The function is sent { d, i, networkFrameProps, networkFrameState, nodes, edges }

htmlAnnotationRules: { function }

A function that takes an annotation object and returns a JSX HTML element. The function is sent { d, i, networkFrameProps, networkFrameState, nodes, edges }. Elements can be placed using CSS left and top and will overlay on the chart. Internally, the default annotation for tooltips uses this method.

annotationSettings: { object }

An object with { layout, pointSizeFunction, labelSizeFunction } containing custom annotation settings to enable annotations bumping out of each others' way or placing them in the margins.

backgroundGraphics: { array | JSX }

A JSX or array of JSX to display behind the chart.

foregroundGraphics: { array | JSX }

A JSX or array of JSX to display in front of the chart.

Interaction

hoverAnnotation: { bool }

Turn on automatic tooltips for each node. Content of the tooltips defaults to the id value and can be customized with tooltipContent.

customHoverBehavior: { function }

A function to fire on hover of the node being hovered over.

customClickBehavior: { function }

A function to fire on click of the node being hovered over.

customDoubleClickBehavior: { function }

A function to fire on doubleclick of the node being hovered over.

interaction: { object }

An object passed to the interaction layer that could be used to create an XY brushable region but this hasn't been tested. Likely will be used to implement brush/lasso or other interaction that makes sense in topological space.

Miscellaneous

name: { string }

Used internally to identify frames, which comes in handy when you need to link frames together.

position: { array }

Just an offset and hardly ever useful

additionalDefs: { JSX }

JSX to be injected into the visualization layer's SVG defs.

download: { bool }

Enable a Node Download button and Edge Download button to download the data as a CSV.

downloadFields: { array }

The field keys to download from each datapoint. By default, the CSV download only shows the id, source and target values.