A Tree is a special type of graph that maintains a tree structure.
A tree is best thought of as a hierarchical structure where all nodes in the tree are the descendant of a single root node "the root". Every node in a tree can have only 1 parent, with the exception being the root which has no parents.
Every node in a tree can have 0 or more children. A node without any children is considered a leaf.
One of the important characteristics of a tree is that each node has a depth. The depth refers to how many ancestors a node is removed from the root. If a node has the root for a parent, then its depth will be 1 and its children will have a depth of 2. The root has a depth of 0.
var tree = new thinkmap.graph.Tree(node);
var tree = new thinkmap.graph.Tree();
tree.root(tree.createNode({label:'root'})
.addEdge(tree.root(),tree.createNode({label: 'Node A'})
.addEdge(tree.root(),tree.createNode({label: 'Node B'});
Creates a new Tree
The root of the tree
var tree = new thinkmap.graph.Tree(node);
var tree = new thinkmap.graph.Tree();
tree.root(tree.createNode({label:'root'})
.addEdge(tree.root(),tree.createNode({label: 'Node A'})
.addEdge(tree.root(),tree.createNode({label: 'Node B'});
Adds an entity (or set of entities) to this tree.
Adding entities to a tree behaves very differently than adding entities to a graph.
Typically, you only add edges to a tree as adding a node to a tree will just be ignored because a tree must maintain a hierarchy structure. (The only exception is when the tree is empty. Adding a node to an empty tree will make the added node the root).
When adding edges to a tree, one of the edge's nodes (the from or to) must not exist in the tree. If both nodes already exist in the tree, then the edge is ignored because adding it will result in a node having two parents which breaks the tree structure. Moreover, if both nodes don't exist in the tree, then the edge is ignored as orphaned nodes also break the tree structure. If the edge satisfies both conditions, the node that doesn't exist in the tree will be made a child of the edge's other node.
the entities to be added to this tree
this tree
Add this tree to the given tree. Adds this tree to another tree.
If the given tree has the same root as this tree, then all the edges of this tree are added to the given tree, skipping any edges that break the "treeness" of the given tree.
If the given tree does not share a root with this tree, nothing is added, unless the given tree is the empty tree, in which case, the given tree becomes a copy of this tree.
the tree to add this
this tree
Returns the child edges of the given node.
Each node in this tree can have 0 or more child edges.
The node to be evaluated
Returns the child nodes of the given node.
Each node in this tree can have 0 or more children.
The node to be evaluated
Returns the depth of the given entity or the maximum depth of this tree if called with no arguments.
The depth refers to how many ancestors a particular node is removed from the root node. In simpler terms, it is the level of a node in the tree. If a node is a direct, descendant of the root, it will have a depth of 1. The root node has a depth of 0.
The optional entity that you want to determine the depth of.
Returns the leaves of this tree. A leaf is a node that has no child edges.
An optional node that is used at the start point in searching for leaves. If no value is passed in, this tree's root will be used
Returns the parent node of a given entity. Every node in a tree has 1 parent. The only exception is the root which has no parent.
a node
returns the parent node
Returns the parent edge of a given node. Every node in a tree has 1 parent edge. The only exception is the root node which has no parent edge.
a node
returns the parent edge
Removes the entity from the tree. Removing an entity from a tree forces all descendants to be removed from the tree. For instance, removing the root entity from a tree will result in an empty tree.
the entity to remove from the tree
Sets or gets the root node of this tree.
If this method is called without arguments, this tree's root is returned.
If this method is passed a node, the root is set to the given node and this tree is returned. If this tree has a size greater than 0, this method will remove all entities and then set the root. Setting the root of a tree always results in this tree having a single node of depth 0.
the node to set as the root of this tree
The current root if called without arguments. Else, this tree is returned.
Visits this tree in breadth-first order.
The callback function when visiting the tree. The parameter is either a node or edge, depending on the value of the edges parameter.
The optional node to start visiting from. If null or undefined, the root is used.
Set to true if edges should be passed as the parameter to the visitFn. The default is false so nodes are passed to the visit function.
Add a graph loader to this graph
the loader to add
the loader that was added
Create an annotation that allows you to associate arbitrary data with entities in this graph. The special thing about annotations is that they allow you to weakly associate data. When the annotation is garbage-collected, all data associated with the annotation is garbage collected, even though the graph may still contain the entities that have been annotated.
However, data in the annotation is not garbage collected when entities are
removed from the Graph. You MUST remove the annotated data manually when
entities are removed from the Graph. This is typically done by adding a
listener to the Graph's 'removenode' and 'removeedge' events.
the annotation.
Returns this graph as a tree.
The tree is built by performing a visit on this graph. This graph can be visited in either depth first or breadth first order.
the node that will be the root of the tree
set to true if the tree should be built by visiting this graph in depth first order. If not true, this graph will be visited in breadth-first order.
the optional filter function that should return true if the edge should be visited
Find an entity by internal entity id.
the id of the entity to retrieve
the entity with that id, or null no entity with that id exists in this graph.
Test whether an entity (or selection of entities) can be removed. This will return false if a retention policy is in place for an entity, and that policy prevents the entity from being removed from this graph.
true if this entity (or selection) can be removed
Returns true if this graph contains the given entity.
Create an edge that may be added to this graph at a later time.
the from node (required)
the to node (required)
true if this is a directed edge. The default is false
optional data to be associated with this edge
optional type of this edge, the default is "edge"
var actor = graph.createNode({name:'Harrison Ford'});
var movie = graph.createNode({title:'Star Wars'});
// add a new non-directed edge
var edge = graph.add(graph.createEdge(actor,movie,false,{role:'Han Solo'}));
Create a full-text index on this graph. Full-text indexes allow search queries to run faster.
full-text index specification in JSON format
the name of the entity type to index - the default is all entities
the resulting index, or an existing index if one with this specification existed.
// create an employee type
graph.createType('employee','node');
// create the index
graph.createFullTextIndex({'lastname':true,'firstname':true},'employee');
Create an index on this graph. Indexes allow queries to run faster.
index specification in JSON format
true if this index should enforce uniqueness
the name of the entity type to index - the default is all entities
the resulting index, or an existing index if one with this specification existed.
// create an employee type
graph.createType('employee','node');
// create the index
graph.createIndex({'lastname':true,'firstname':true},true,'employee');
Create a node that may be added to this graph at a later time.
the newly added node.
var newnode = graph.add(graph.createNode({name:'John Smith'}));
var newnode = graph.add(graph.createNode({title:'Star Wars'},'movie'));
var newnode = graph1.createNode({name:'John Smith'});
graph2.add(newnode);
Create an entity type.
the name of the new type
required parent type - usually 'node' or 'edge'
this graph
// create a node entity type called "movie"
var movies = graph.createType('movie','node');
Tell this graph that a given entity (or entities) have had their data updated.
the entity or entities to be updated
Connect this graph to a remote Thinkmap 2.9.2+ datasource at the given URL
the graph loader associated with the datasource
Find an edge by internal entity id.
the id of the node to retrieve
the edge with that id, or null if no entity with that id exists.
Select edges from this graph.
If this function is called with no arguments, it selects all the edges in the graph.
a reference node to start from
the direction to traverse from the reference node. The default is Edge.Direction.BOTH.
an optional filter function used to filter the selection
Asynchronously fetch the entities related to the given entity, using any associated graph loaders to retrieve the related entities.
This method is typically not called by users, but is called by the query API when fecthing remote data.
the entity to fetch data for
the current query (part) being executed
a future entity that will be fulfilled when all data related to the given entity has been loaded.
Return a filtered view of this Graph.
a function used to filter this graph into a new graph
set to true if you want the resulting Graph to be kept up to date with the original graph by listening to it for changes. If set to false, the returned graph will be a point-in-time snapshot of this graph.
a new graph, filtered by the given function.
Call the given function once for every entity in this graph.
the value to use as "this" when calling the callback
Returns an array of indexes that have been created on this graph.
Returns true if the given entity type descends from the given parent type.
true if the given type name descends from the given parent
// create a node entity type called "movie"
var movies = graph.createType('movie','node');
// prints true to the console
console.log( graph.isType('movie','node' ) );
Get the graph loaders associated with this graph.
Find a node by internal entity id.
the id of the node to retrieve
the node with that id, or null if no node with that id exists.
Select nodes from this graph.
If this function is called with no arguments, it selects all the nodes in the graph.
a reference entity to start from (either a node or edge)
the direction to traverse from the reference entity. The default is Edge.Direction.BOTH.
an optional filter function used to filter the selection
Link this graph to another, so that any entities that are added to the other graph are added/removed from this graph.
the graph to observe
a filter function that must return true for entities to be reflected in this graph
this graph
Returns this graph as a precedence tree.
A precedence tree is a tree ordered by dependencies such as a schedule. More specifically, the tree is the result of a topological sort on a directed graph. A directed graph is a graph where all edges are directed and has no cycles (i.e. a node doesn't have a directed edge pointing to any ancestors). If this method is called on a graph with cycles, an error is thrown.
For example, if this graph has Node A which has an edge to nodes
B and C and C is also connected to B, the result of calling this method is a tree with:
A -> C -> B
The starting point of the precedence tree.
an optional error callback useful when trying to debug any cycles when building the precedence tree. The parameters are the tree built, the visited nodes, and the removed edges so far, both stored as bitsets.
Compile a Query object for executing queries on this Graph. Queries are specified as a JSON object in Thinkmap Graph Query Language. See the Thinkmap Graph Query Language documentation for details.
a Thinkmap query in JSON query format
the parsed query object
graph.query({$search:'breakfast',$t:'node'}).execute().oncomplete(function() {
console.log('found', this.count(), 'results' );
});
Set a retention policy for an entity (or selection) of entities. A policy function takes one argument (an entity) and returns true if that entity MAY NOT be removed from the graph. Returning false or undefined means that the entity MAY be removed. Retention policies are cumulative. That means that if more than one policy is in place, if any one of the policies return true for an entity, that entity cannot be removed.
If the same exact policy function is added more than once for any entity, only one copy is retained.
a function that determines if an entity is retained.
Remove all entities, except the ones contained in the given selection.
the selection to retain
this graph
Select entities from this graph
selection parameter
Create a selection on this Graph from a BitSet that contains the ids of the entities to select.
Unlinks this graph from a graph it was previously observing via the Graph.observe() method.
the graph to stop observing
this graph
Add a listener to this EventSource
the name of the event to listen for
the callback to add
this eventsource
Dispatch an event from this EventSource, supplying arguments to the listeners via an Array, rather than var-args.
the name of the event to dispatch
this EventSource
Dispatch an event from this EventSource
the name of the event to dispatch
optional arguments sent to the event listeners
this EventSource
Fire an event from this EventSource
the name of the event to dispatch
optional arguments sent to the event listeners
this EventSource
Remove a listener from this EventSource
the name of the event to remove the listener for
the callback to remove
this eventsource
Add a listener to this EventSource
the name of the event to listen for
the callback
this eventsource
Add a listener to this EventSource, which will be called at most once and will be removed the first time the given event fires.
the name of the event to listen for
the callback to add
this eventsource
Remove a listener from this EventSource
the name of the event to remove the listener for
the callback to remove
this eventsource
This event is fired each time a node is added to the graph. The parameter is the node added.
This event is fired each time an edge is added to the graph. The parameter is the edge added.
This event is fired each time a node is removed from the graph. The parameter is the node removed.
This event is fired each time an edge is removed from the graph. The parameter is the edge removed.
This event is fired each time each time dataUpdate on graph is called. This typically signifies that some change occured to the entity's data object. The single parameter is the entity passed to the graphs dataUpdate method.