Tree Charts

Note: See our Tree Module Gallery for inspiration on all the different tree chart possibilities.

Tree Chart Type

To specify the chart type, add a type attribute to the chart object. Our standard tree chart (aka network diagram) is specified by the tree value.

{
  type: 'tree'
}

Graph Tree Chart

To create a graph tree chart, set aspect: 'graph in the options object. Graph tree charts have a specific way of entering and linking node data.

Data Format

Tree-module charts support data in the form of a series array of objects. Each object in the series array represents nodes or links.

Family Nodes

For this type of tree chart, there will be a main node (family node) object that will link to other nodes that will contain the information, such as the images. Family node objects will have a few attributes needed for it to work. First, you'll need to add the type attribute with a value of 'node' to your series array, meaning each series will be a floating node.

Each object will also need the id attribute. This main node holds the family trees together and will be called n1, n2, n3 and so forth.

Note: You can include an optional cls attribute to set a class on the object for styling (discussed further below).

A standard family node will take this format:

{
  type: 'node', 
  id: 'n1', 
  cls : 'fam', //optional class for styling
  text: '', //optional text for label- empty string value for family nodes
  dataFullname: '' //optional custom token- empty string value for family nodes
}

With each new family or group on the graph tree charts, we need to have a new hub node so that the families will have their own hub to link to (the id values of n1, n2 and so forth). The best way to organize these for ease of reading and use would be to have the main hub series above the same family series that will be tied to that hub. An example is:

{
  series: [
    { // main node hub 1
      type: 'node',
      id: 'n1',
      cls: 'fam',
      text: ' ',
      dataFullName: ''
    },
    {
      type: 'node',
      id: 'Ned Stark',
    },
    {
      type: 'node',
      id: 'Brandon Stark',
      text: 'Brandon',
      dataFullName: 'Brandon Stark',
    },
    { // main node hub 2
      type: 'node',
      id: 'n2',
      cls: 'fam',
      text: ' ',
      dataFullName: ''
    },
    {
      type: 'node',
      id: 'Lyarra Stark',
    },
  ]
}

Data Nodes

With each main node hub, we can link other data objects to it. The data node objects will have a few attributes that we need to fill out, the first being type: 'node'. Furthermore, we need to assign an id to this object so that we can target and link it to the hub nodes. The id attribute for data nodes can be assigned anything and will most likely describe what the data node represents.

Adding a text attribute will give your node a label. dataFullname is a custom token that can be used to display more information in your tooltips. For family node objects, these attributes take empty strings as values.

Note: You can include an optional cls attribute to set a class on the object for styling (discussed further below).

A standard data node will take this format:

{
  series: [
    { //data node object
      type: 'node',
      id: 'Ned Stark',
      text: 'Ned',
      dataFullName: 'Ned Stark',
    },
  ]
}

Link Objects

Once we have our families and data nodes set, we can link them together using link objects in the same series array. First, you'll need the type attribute with a value of 'link'.

Link objects will target the id attribute and draw a link from the source value to the target value. In our case, the source will be the main node hubs of n1, n2 and n3, and the target will be the id of data nodes.

Every data node will need a link object so that it will be connected to the chosen hub node. A data node can be linked to multiple family trees by linking them to multiple hub nodes.

{
  series:[
    {
      type: 'link',
      source: 'n1',
      target: 'Ned Stark'
    },
  ]
}

Link-Node Attraction and Interactions

For graph tree charts, the springLength, attractionConstant, repulsionConstant, and repulsionDistanceFactor attributes will determine the length, repulsion, attraction and interactions of the links and nodes.

The attractionConstant and repulsionConstant attributes are used to determine the amount of magnetization between each node in a graph tree chart . The constants used in the Game of Thrones demo gives the graph tree chart a balanced amount of distance and attraction:

{
  options: {
    aspect: 'graph',
    springLength: 75,
    attractionConstant: 0.8,
    repulsionConstant: 4000,
    repulsionDistanceFactor: 20,
  }
}

Node Styling

To style individual nodes, create a style object within the applicable series object. This is where we will be able to set the backgroundImage, size and many other ZingChart styling basics for the nodes.

Note: When using backgroundImage, it is useful to use background-fit: 'xy' so that the image will be centered and show properly inside the small node area.

Note: Learn more about styling nodes with our Chart Plot & Series Styling Tutorial.

{
  series: [
    {
      type: 'node',
      style: {
        "background-fit": "xy",
        backgroundImage: "https://i.imgur.com/OFrvsvv.png"
      }
    },
  ]
}

To style hub nodes, use the node[cls-fam] object inside the options object. node[cls-fam] can take the same attributes as the node objects except that it will target the hub nodes instead of the data nodes. The cls-fam nomenclature stems from how we set the series array in the tree chart.

{
  options: {
    'node[cls-fam]': {
      size: 12,
      borderWidth: 2,
      borderColor: '#000',
      backgroundColor: 'white',
      label: {
        visible: false
      }
    },
  }
}

Chart-Specific Properties

Use the options object to configure the tree-module.

Aperture

Sets the total radial aperture for the radial trees.

{
  type: 'tree',
  options: {
    aspect: 'tree-radial',
    aperture: 100,
  },
}

Damping Step

Sets the damping factor for each step of the force directed graph iteration. The default value is 0.005. Higher values will force the graph to stop faster, with the cost of not reaching an optimal state for the layout.

https://app.zingsoft.com/demos/embed/8X9Q5Q45
https://app.zingsoft.com/demos/embed/8X9Q5Q45
{
  type: 'tree',
  options: {
    dampingStep: 0.05,
  },
}

Depth Ratio

Sets a ratio for the curvature of the links. Note that this only applies with links are curved.

https://app.zingsoft.com/demos/embed/8PWDTME9
https://app.zingsoft.com/demos/embed/8PWDTME9
{
  type: 'tree',
  options: {
    depthRatio: 10,
    link: {
      aspect: 'arc'
    },
  },
}

Fake

Sets the node as a branch point for other nodes to branch off from.

https://app.zingsoft.com/demos/embed/OEO4YQER
https://app.zingsoft.com/demos/embed/OEO4YQER
{
  type: 'tree',
  series: [
    {
      id: 'fake1',
      fake: true,
      name: '1',
      parent: 'parent',
    },
    ...
  ],
}

Layout

Sets the layout to use when there are multiple top-level parent nodes present.

https://app.zingsoft.com/demos/embed/1THRLTGG
https://app.zingsoft.com/demos/embed/1THRLTGG
{
  type: 'tree',
  options: {
    layout: 'h',
  },
}

Max Iteration

Sets the max number of iterations executed before stabilizing the force directed graph.

https://app.zingsoft.com/demos/embed/22FPNZ9L
https://app.zingsoft.com/demos/embed/22FPNZ9L
{
  type: 'tree',
  options: {
    aspect: 'graph',
    maxIterations: 20,
  },
}

Max Link Width

Sets the max width for the links between nodes (available in the force directed graphs).

https://app.zingsoft.com/demos/embed/5DPPFXFC
https://app.zingsoft.com/demos/embed/5DPPFXFC
{
  type: 'tree',
  options: {
    maxLinkWidth: 15, // default is 5
  },
}

Minimum and maximum Size

Sets the minimum and maximum size for nodes.

https://app.zingsoft.com/demos/embed/O912F4N4
https://app.zingsoft.com/demos/embed/O912F4N4
{
  type: 'tree',
  options: {
    minSize: 4,
    maxSize: 20, // default is 4
  },
}

Organizational Tree Diagram

Set to true to enable the organizational tree diagram.

https://app.zingsoft.com/demos/embed/OEO4YQER
https://app.zingsoft.com/demos/embed/OEO4YQER
{
  type: 'tree',
  options: {
    orgChart: true,
  },
}

Packing Factor

Sets a factor of the packing algorithm (how close the nodes are forced). Only applies to organizational tree diagrams (options.orgChart = true).

https://app.zingsoft.com/demos/embed/WT5KK2M1
https://app.zingsoft.com/demos/embed/WT5KK2M1
{
  type: 'tree',
  options: {
    orgChart: true
    packingFactor: 10, // default is 1
  },
}

Progression

Sets the progression of the distance between nodes. Accepts values between -1 (decreasing) to 1 (increasing), where 0 sets the nodes to have equal distance.

https://app.zingsoft.com/demos/embed/9EFBMY8T
https://app.zingsoft.com/demos/embed/9EFBMY8T
{
  type: 'tree',
  options: {
    progression: 0.5, // default is 1
  },
}

Reference Angle

When aspectType is set to "tree-radial", the refAngle attribute is used to set the reference angle for radial trees.

https://app.zingsoft.com/demos/embed/IFZS6KHW
https://app.zingsoft.com/demos/embed/IFZS6KHW
{
  type: 'tree',
  options: {
    aspectType: 'tree-radial',
    refAngle: 180, // default is 0
  },
}

Weighted Links

When set to true, disables collapsible nodes.

https://app.zingsoft.com/demos/embed/4L7XZV26
https://app.zingsoft.com/demos/embed/4L7XZV26
{
  type: 'tree',
  options: {
    weightedLinks: true,
  },
}

Weighted Nodes

Sets whether the size of the nodes will be considered when performing the logic for force directed graphs.

https://app.zingsoft.com/demos/embed/UZ9TSCGB
https://app.zingsoft.com/demos/embed/UZ9TSCGB
{
  type: 'tree',
  options: {
    weightedNodes: 0.05,
  },
}

Methods

To update the tree, you must use the setdata method.

zingchart.exec('myChart', 'setdata', {
  data: chartConfigObj
});

Further Customization

Once you have your basic grid, you can customize and style it to fit your data visualization needs.

Palette

Use the palette array to specify colors to be used by the nodes. Provide the color values as strings inside the array.

https://app.zingsoft.com/demos/embed/2LDSFPU0
https://app.zingsoft.com/demos/embed/2LDSFPU0
{
  options: {
    palette: ['#2196F3', '#3F51B5', '#42A5F5', '#5C6BC0', '#64B5F6', '#7986CB', '#90CAF9', '#9FA8DA', '#BBDEFB', '#C5CAE9'],
  },
}

Styling Attributes

The following attributes can be used to style tree charts:

Attribute Description
link Defines the style for links between nodes
link[cls-n] Defines the style for links with class 'n'
link[container-n] Defines the style for links belonging to container 'n'
link[group-n] Defines the style for links belonging to group 'n'
link[level-n] Defines the style for links in level 'n'
link[parent-n] Defines the style for links with parents 'n'
link[sibling] Defines the style for links between sibling nodes
link[source-n] Defines the style for links coming for source 'n'
link[target-n] Defines the style for links going to target 'n'
links Defines the style for links specified by 'SOURCEID-TARGETID' keys
node Defines the style for nodes
node[cls-n] Defines the style for nodes with class 'n'
node[collapsed] Defines the style for collapsed nodes
node[container-n] Defines the style for nodes belonging to container 'n'
node[group-n] Defines the style for nodes belonging to group 'n'
node[leaf] Defines the style for leaf nodes (nodes without any children)
node[level-n] Defines the style for nodes in level 'n'
node[parent] Defines the style for parent nodes
node[parent-n] Defines the style for nodes that has parent 'n'
nodes Defines individual styles for nodes specified by their id