Node Labeling

Node label logic

Network Canvas calculates the label to be used when rendering a node using the the following logic:

0. use worker (see below)
1. In the codebook for the stage's subject, look for a variable with a name property of "name" (regardless of case), and try to retrieve this value by key in the node's attributes

Specifically for nodes created from external data that have no corresponding variables in codebook for the above

2. Look for a property on the node with a key of ‘name’ (regardless of case), and try to retrieve this value as a key in the node's attributes.

Fallback option

3. Show the text "No 'name' variable!"

External data

To control the labeling of nodes created from external data sources, the following options are available, and will be applied in this order:

1. Create an attribute for your nodes called "name".

Custom Node Labeling (Advanced)

For more flexible labeling of nodes, you can implement a custom labeling function. To accomplish this, you would:

• Add nodeLabelWorker.js to your protocol
• Define a function named nodeLabelWorker
• Return a string from that function, which will be used as the label.

nodeLabelWorker is called with an object containing information about the node & network, and should return the label (a string) for the given node. Conceptually: f(node, network) -> label. Thus you can update labels for nodes based on the changing state of the network.

Here's a simple example which will label every node with a compound property (initial + surname):

/**
 * @param  {Object} data
 * @param  {Object} data.node All props for the node requiring a label
 * @param  {string} data.node.networkCanvasId Unique ID for the node. Note that if your data
 *                                            happens to already contain a property named
 *                                            "networkCanvasId", your prop will take precedence,
 *                                            and this cannot be used to identify edge connections.
 * @param  {Object} data.network The current state of the network in this session
 * @param  {Array} data.network.nodes Each node has a unique `networkCanvasId` prop
 * @param  {Array} data.network.edges Edges contain `to` and `from` props which
 *                                    correspond to nodes' `networkCanvasId` values
 *
 * @return {string|Promise} a label for the input node, or
 *                          a promise that resolves to the label
 */
function nodeLabelWorker({ node, network }) {
  return `${node.first_name[0]} ${node.last_name}`;
}

In addition to attributes specified from a protocol, each node will contain a unique networkCanvasId property which can be used to identify the node in the network.

The nodeLabelWorker function will be executed asynchronously in a Web Worker environment. It will be further restricted by the Content Security Policy of the app; you should not rely on network access within the labeling function.

For a more complete example, see the nodeLabelWorker in the development protocol.