@hownetworks/tracegraph

tracegraph is a JavaScript library for plotting graphs of traceroute or similar data.

Check out the small Observable HQ notebook demonstrating how it can be used.

Installation

$ npm install @hownetworks/tracegraph

Usage

import { tracegraph } from "@hownetworks/tracegraph";

tracegraph()

const graph = tracegraph();

graph(traceData)

const layout = graph(traces);

traces should be an array where each item has the following properties:

• trace.hops - an array of hops that belong to the trace, each hop can be whichever object suits your purpose

layout.bounds is the bounding box of the layout, returned as a DOMRect-like object with some extra convenience properties:

• bounds.cx, bounds.cy - the coordinates for the center point of the box
• bounds.expanded(left, [top, [right, bottom]]) - a function that returns a new box that has been expanded by the given amount(s)

layout.traces is an array where each item is a defined/undefined segment is a trace and has the following properties:

• trace.index - the index of the trace
• trace.width - the width of the trace
• trace.hops - the hops belonging to the trace
• trace.defined - whether the segment is defined or not
• trace.points - points for drawing the segment
• trace.smoothness - the layout's smoothness value
• trace.horizontal - whether the layout is horizontal or vertical

layout.nodes is an array where each item has the following properties:

• node.bounds - the bounding box of the node, returned as a DOMRect-like similar to layout.bounds above
• node.horizontal - whether the layout is horizontal or vertical
• node.hops - an array of hops that belong to the node
• node.traceIndexes - an array of indexes of the traces that are connected to the node
• node.traceStops - used for creating (optional) linear gradient for the node to match the positions of its connected traces

graph.horizontal([horizontal])

Defines whether the layout is either horizontal or vertical. Evaluated without arguments for each layout.

Default: false (the layout is vertical)

graph.traceWidth([width])

Defines the width of a trace. Evaluated for each trace with the arguments trace, traceIndex, and traces.

Default: 1

graph.traceSmoothness([smoothness])

A coefficient used in calculating the trace curves. The value should be between 0 and 1 (inclusive), a larger value generally meaning a more round appearance for the curves. Evaluated without arguments for each layout.

Default: 0.5

graph.hopDefined([defined])

Tark traces a hop as either defined or undefined. Evaluated for each hop, with hop, hopIndex, trace, traceIndex, and traces as the arguments.

Default: true

graph.hopLevel([level])

A hop's position (depth, level) in the trace. Evaluated for each hop, with hop, hopIndex, trace, traceIndex, and traces as the arguments.

Default:

function hopLevel(hop, hopIndex) {
  return hopIndex;
}

graph.nodeSize([size])

A node's minimum size as [width, height], used for layout. The final size of the node may be larger. Evaluated without arguments for each output node, with node as the argument. node won't have its position data such as node.x0 set, as the layout won't be finished at the time of the evaluation.

Default: [10, 10]

graph.nodeId([id])

A string identifier for the node a hop belongs to. Evaluated for each hop, with hop, hopIndex, trace, traceIndex, and traces as the arguments.

Default:

function nodeId(hop, hopIndex, trace, traceIndex) {
  return `${traceIndex}-${hopIndex}`;
}

graph.levelMargin([margin])

Margin size around each level of nodes. Evaluated without arguments for each layout.

Default: 10

Helper Functions

import { traceCurve, nodeGradient, genUID } from "@hownetworks/tracegraph";

traceCurve(traceSegment)

Return a string suitable for plotting a layouted trace segment.

svg
  .selectAll(".trace")
  .data(layout.traces)
  .enter()
  .append("path")
  .attr("class", "trace")
  .attr("d", traceCurve());

nodeGradient(node) and genUID()

nodeGradient is a helper method for coloring nodes based on the traces that go through them. genUID can be used to generate the ids for the gradients.

const ids = nodes.map(() => genUID());

svg.append("defs")
  .selectAll("linearGradient")
  .data(layout.nodes.map(nodeGradient))
  .enter().append("linearGradient")
    .attr("id", (d, i) => ids[i].id)
    .attr("gradientUnits", d => d.gradientUnits)
    .attr("x1", d => d.x1)
    .attr("y1", d => d.y1)
    .attr("x2", d => d.x2)
    .attr("y2", d => d.y2)
  .selectAll("stop")
  .data(d => d.stops);
  .enter().append("stop")
    .attr("offset", d => d.offset)
    .attr("stop-color", d => ["red", "green", "blue"][d.traceIndex % 3]);

svg.selectAll("circle")
  .data(layout.nodes)
  .enter().append("circle")
    .attr("fill", "white")
    .attr("stroke", (d, i) => ids[i])
    .attr("r", d => 10)
    .attr("cx", d => d.bounds.cx)
    .attr("cy", d => d.bounds.cy);

License

This library is MIT licensed. See LICENSE.