A javascript library for visualizing hierarchical data, specifically tailored towards rendering dependency parses.
A javascript library for visualizing hierarchical data, specifically tailored towards rendering dependency parses.
There are two ways to use hierplane:
Add the following <script> tag to your web page:
<script src="//unpkg.com/hierplane/dist/static/hierplane.min.js"></script>
Add the following styles to your web page, likely in the <head /> tag:
<link rel="stylesheet" type="text/css" href="//unpkg.com/hierplane/dist/static/hierplane.min.css">
Then invoke hierplane.renderTree(tree[, options]) as is desired.
- `tree` *object* the tree to visualize, see <a href="#tree-structure">a detailed description of
the tree structure.</a>
- `options` *object* optional overrides
- `options.theme` *string* the theme to use, one of 'dark' or 'light',
defaults to 'dark'.
- `options.target` *string* a css selector targeting the element where
the resulting DOM should be rendered, defaults to 'body'.
The renderTree() method returns a function that will unmount the rendered
content, if you want to remove the visualization:
const unmount = hierplane.renderTree(tree, { target: '#hierplane', theme: 'light' });
// Don't do this
const target = document.getElementById('hierplane');
target.removeChild(target.firstElementChild);
// Do this
unmount();
You can see a full example here.
Install the hierplane dependency:
npm install --save hierplane
Then, simply import the Tree component, and pass it the tree you'd like to render:
import { Tree } from 'hierplane';
import React from 'react';
const aTree = { ... };
class TreeContainer extends React.PureComponent {
render() {
return <Tree tree={aTree} />;
}
}
A tree is an object with the following structure:
/**
* @type object
*/
Tree
/**
* The text being visualized.
* @type string
* @required
*/
text: 'Sam likes eating hot dogs.'
/**
* Map used to apply node styles (see `Style Maps` section).
* @type object
* @optional
*/
nodeTypeToStyle: { ... }
/**
* Map used to set node positioning (see `Style Maps` section).
* @type object
* @optional
*/
linkToPosition: { ... }
/**
* Map used to override link labels (see `Style Maps` section).
* @type object
* @optional
*/
linkNameToLabel: { ... }
/**
* The root node of the tree.
* @type object
* @required
*/
root: Node { ... }
The root property refers to the root node of the tree to be visualized. Each node has the following
structure:
/**
* @type object
*/
Node
/**
* The text content of the node
* @type string
* @required
*
* TODO: This will likely be migrated to be named `text` in a future version, as it's less specific.
*/
word: 'eating'
/**
* A string specifying the "type" of node. This is used to determine it's color -- all nodes of
* the same type will be assigned the same color.
* @type string
* @required
*/
nodeType: 'verb'
/**
* A string specifying describing the relationship between the node and it's parent. This text
* will be displayed on an element connecting the node and it's parent.
* @type string
* @optional
*/
link: 'direct object'
/**
* An array of strings, which will be displayed on the node.
* @type string[]
* @optional
*/
attributes: [ 'action', ... ]
/**
* An array of spans, where each span represents a series of characters in the `text` property (
* of the Tree) that should be highlighted when the node is hovered.
* @type object[]
* @optional
*/
spans: [ Span { ... }, ... ]
/**
* An array containing the children of the node.
* @type object[]
* @optional
*/
children: [ Node, ... ]
Each span refers to a sequence of characters in the original sentence (the text property of the
Tree) that should be highlighted when the node and is hovered. Each span should have the
following properties:
Span
/**
* The index indicating where the span begins.
* @type number
* @required
*/
start
/**
* The index (exclusive) where the span ends.
* @type number
* @required
*/
end
/**
* An optional identifier indicating the type of span. As of now, the only value you'll likely
* put here is "ignored", which indicates that the span shouldn't be emphasized when the node
* is hovered.
* @type string
* @optional
*/
spanType
You can see a full example of a tree here.
The Hierplane data format supports three optional style maps (objects containing a set of key-value pairs) that can be added to a Tree object:
nodeTypeToStyle applies specified styles to nodes with particular nodeType values.linkToPosition tells the app how to position nodes with particular link values.linkNameToLabel translates particular link values into custom display labels.A nodeTypeToStyle mapping applies specified styles to nodes with particular nodeType values. In the following example, any node with a nodeType value of "verb" will have "color1" and "strong" styles applied. This gets rendered as CSS modifier classes.
"nodeTypeToStyle": {
"verb": ["color1", "strong"],
"noun": ["color2"],
"modifier": ["color3"],
"sequence": ["seq"],
"reference": ["placeholder"]
}
Note: Hierplane will automatically color-code nodes based on their nodeType values, so out-of-the-box, you do not need to worry about nodeTypeToStyle mapping. However, as soon as you add this map and introduce a custom style on any nodeType, you will need to manually apply all node styles, as the automatic styling will be disabled at that point.
Supported nodeTypeToStyle Keys:
Any potential nodeType value is a valid key, whether it's being used in the current tree or not.
Supported nodeTypeToStyle Values:
Valid values are arrays of strings. While you are free to apply any string as a style, only the following strings are supported by the built-in stylesheet:
"color0" colors node gray."color1" colors node green."color2" colors node blue."color3" colors node pink."color4" colors node yellow."color5" colors node purple."color6" colors node aqua."strong" makes node text larger and bold."seq" renders node as a sequence container. Note that this style is required to correctly render nodes that have at least one child node with a nodeType value of "inside". Also note that a node with a "seq" style will have its default node text hidden to make room for its "inside" children."placeholder" renders node with a transparent background and light dotted outline (to communicate a placeholder status, recommended for certain linguistic concepts such as relative references).Note: at this time, the only supported colors are the 7 mentioned above.
A linkToPosition mapping tells the app how to position nodes with particular link values. In the following example, any node with a link value of "subj" will be given a position of "left", while nodes with link values of "obj" will be given a position of "right" and so on.
"linkToPosition": {
"subj": "left",
"obj": "right",
"seqChild": "inside"
}
Supported linkToPosition Keys:
Any potential link value is a valid key, whether it's being used in the current tree or not.
Supported linkToPosition Values:
inside - Positions node inside of its parent. This was added mainly to support linguistic sequences (e.g. "The land has trees, grass, and animals." where the object of the sentence is a sequence of nouns).
left - Positions a node to the left of its parent (well suited for subjects of a sentence).
right - Positions a node to the right of its parent (well suited for objects of a sentence).
down - Positions a node directly underneath its parent (we call this layout "canonical"). All nodes have a position of down by default, so it is not necessary to explicitly set this.
A linkNameToLabel mapping translates particular link values into custom display labels. In the following example, any node with a link value of "subj" will be displayed as "S". This is especially useful for nodes positioned "left" and "right", as those configurations lose aesthetic value with long link labels.
"linkNameToLabel": {
"subj": "S",
"obj": "O"
}
Supported linkNameToLabel Keys:
Any potential link value is a valid key, whether it's being used in the current tree or not.
Supported linkNameToLabel Values:
Any string is a valid value.
To run the code locally and verify your changes, follow these steps:
$ git clone git@github.com:allenai/hierplane.git
Install nodejs. This was built against version v6.11.5. You're free
to try something more recent.
Install the dependencies:
$ cd hierplane/
$ npm install
watch target:$ npm start
If you want to change the port on which the webserver is bound, set the HIERPLANE_DEV_SERVER_PORT
environment variable to one of your choosing.
In order to publish, you will need to be a collaborator on the Hierplane NPM project.
package.json.hierplane project folder, enter npm login and log in with your NPM credentials.node bin/publish.js.FAQs
A javascript library for visualizing hierarchical data, specifically tailored towards rendering dependency parses.
We found that hierplane demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.