Skip to content

Latest commit

 

History

History
829 lines (603 loc) · 25.4 KB

iteration.md

File metadata and controls

829 lines (603 loc) · 25.4 KB
layout title nav_order detailed_menu_toc
default
Iteration
10
label subtitle
Nodes
true
label id
#.nodes
nodes-array
label
#.forEachNode
label
#.mapNodes
label
#.filterNodes
label
#.reduceNodes
label
#.findNode
label
#.someNode
label
#.everyNode
label
#.nodeEntries
label subtitle
Edges
true
label id
#.edges
edges-array
label
#.forEachEdge
label
#.mapEdges
label
#.filterEdges
label
#.reduceEdges
label
#.findEdge
label
#.someEdge
label
#.everyEdge
label
#.edgeEntries
label subtitle
Neighbors
true
label id
#.neighbors
neighbors-array
label
#.forEachNeighbor
label
#.mapNeighbors
label
#.filterNeighbors
label
#.reduceNeighbors
label
#.findNeighbor
label
#.someNeighbor
label
#.everyNeighbor
label
#.neighborEntries

Iteration

It is possible to iterate over the following things:

Iteration methods

The library basically proposes three ways to iterate:

  • Methods returning arrays of keys.
  • Methods using callbacks.
  • Methods creating JavaScript iterable iterators for lazy consumption.

Nodes

Those methods iterate over the graph's nodes.

Examples

const graph = new Graph();

graph.addNode('Thomas');
graph.addNode('Elizabeth');

// Using the array-returning method:
graph.nodes();
>>> ['Thomas', 'Elizabeth']

// Using the callback method
graph.forEachNode((node, attributes) => {
  console.log(node, attributes);
});

// Using functional-style iteration method
const degrees = graph.mapNodes((node) => {
  return graph.degree(node);
});

// Using the iterator
for (const {node, attributes} of graph.nodeEntries()) {
  console.log(node, attributes);
}

#.nodes

Returns an array of node keys.

#.forEachNode

Iterates over each node using a callback.

Arguments

  • callback function: callback to use.

Callback arguments

  • node string: the node's key.
  • attributes object: the node's attributes.

#.mapNodes

Returns an array containing the result of a callback applied on each node of the graph.

Arguments

  • callback function: callback to use.

Callback arguments

  • node string: the node's key.
  • attributes object: the node's attributes.

#.filterNodes

Returns an array of node keys for which the given predicate function returned true.

Arguments

  • callback function: predicate to use.

Callback arguments

  • node string: the node's key.
  • attributes object: the node's attributes.

#.reduceNodes

Returns the accumulated result of applying a callback combining our current value with a computation evaluated on each node of the graph.

Contrary to JavaScript Array.reduce, you must provide it because the callback takes more than one argument and we cannot infer the initial value from our first iteration.

Arguments

  • callback function: callback to use.
  • initialValue any: the initial value to use.

Callback arguments

  • accumulator any: the accumulated value.
  • node string: the node's key.
  • attributes object: the node's attributes.

#.findNode

Returns the key of the first node matching given predicate function or undefined if no matching node could be found.

Arguments

  • callback function: predicate to use.

Callback arguments

  • node string: the node's key.
  • attributes object: the node's attributes.

#.someNode

Returns whether any node in the graph matches the given predicate function.

Arguments

  • callback function: predicate to use.

Callback arguments

  • node string: the node's key.
  • attributes object: the node's attributes.

#.everyNode

Returns whether all nodes in the graph match the given predicate function.

Arguments

  • callback function: predicate to use.

Callback arguments

  • node string: the node's key.
  • attributes object: the node's attributes.

#.nodeEntries

Returns an iterator over the graph's nodes.

Entries

  • node string: the node's key.
  • attributes object: the node's attributes.

Edges

These methods iterate over the graph's edges.

Examples

const graph = new Graph();

graph.mergeEdgeWithKey('T->R', 'Thomas', 'Rosaline');
graph.mergeEdgeWithKey('T->E', 'Thomas', 'Emmett');
graph.mergeEdgeWithKey('C->T', 'Catherine', 'Thomas');
graph.mergeEdgeWithKey('R->C', 'Rosaline', 'Catherine');
graph.mergeEdgeWithKey('J->D1', 'John', 'Daniel');
graph.mergeEdgeWithKey('J->D2', 'John', 'Daniel');

// Using the array-returning methods:
graph.edges();
>>> ['T->R', 'T->E', 'C->T', 'R->C']

graph.edges('Thomas');
>>> ['T->R', 'T->E', 'C->T']

graph.edges('John', 'Daniel');
>>> ['J->D1', 'J->D2']

// Using the callback methods
graph.forEachEdge(
  (edge, attributes, source, target, sourceAttributes, targetAttributes) => {
  console.log(`Edge from ${source} to ${target}`);
});

// And the counterparts to target a node or path's edges
graph.forEachEdge('Thomas', callback);
graph.forEachEdge('John', 'Daniel', callback);

// Using functional-style iteration method
const weights = graph.mapEdges((edge, attr) => {
  return attr.weight;
});

// Using the iterators
for (const {edge, attributes, ...} of graph.edgeEntries()) {
  console.log(edge, attributes);
}

#.edges

Returns an array of relevant edge keys.

Variants

#.inEdges
#.outEdges
#.inboundEdges (in + undirected)
#.outboundEdges (out + undirected)
#.directedEdges
#.undirectedEdges

Arguments

  1. None: iterate over every edge.
  2. Using a node's key: will iterate over the node's relevant attached edges.
  • node any: the related node's key.
  1. Using source & target: will iterate over the relevant edges going from source to target.
  • source any: the source node's key.
  • target any: the target node's key.

#.forEachEdge

Iterates over relevant edges using a callback.

Variants

#.forEachInEdge
#.forEachOutEdge
#.forEachInboundEdge (in + undirected)
#.forEachOutboundEdge (out + undirected)
#.forEachDirectedEdge
#.forEachUndirectedEdge

Arguments

  1. Callback: iterate over every edge.
  • callback function: callback to use.
  1. Using a node's key: will iterate over the node's relevant attached edges.
  • node any: the related node's key.
  • callback function: callback to use.
  1. Using source & target: will iterate over the relevant edges going from source to target.
  • source any: the source node's key.
  • target any: the target node's key.
  • callback function: callback to use.

Callback arguments

  • edge string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object: attributes of the edge's target.
  • undirected boolean: whether the edge is undirected.

#.mapEdges

Returns an array containing the result of a callback applied on the relevant edges.

Variants

#.mapInEdges
#.mapOutEdges
#.mapInboundEdges (in + undirected)
#.mapOutboundEdges (out + undirected)
#.mapDirectedEdges
#.mapUndirectedEdges

Arguments

  1. Callback: iterate over every edge.
  • callback function: callback to use.
  1. Using a node's key: will iterate over the node's relevant attached edges.
  • node any: the related node's key.
  • callback function: callback to use.
  1. Using source & target: will iterate over the relevant edges going from source to target.
  • source any: the source node's key.
  • target any: the target node's key.
  • callback function: callback to use.

Callback arguments

  • edge string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object: attributes of the edge's target.
  • undirected boolean: whether the edge is undirected.

#.filterEdges

Returns an array of edge keys for which the given predicate function returned true.

Variants

#.filterInEdges
#.filterOutEdges
#.filterInboundEdges (in + undirected)
#.filterOutboundEdges (out + undirected)
#.filterDirectedEdges
#.filterUndirectedEdges

Arguments

  1. Callback: iterate over every edge.
  • callback function: callback to use.
  1. Using a node's key: will iterate over the node's relevant attached edges.
  • node any: the related node's key.
  • callback function: callback to use.
  1. Using source & target: will iterate over the relevant edges going from source to target.
  • source any: the source node's key.
  • target any: the target node's key.
  • callback function: callback to use.

Callback arguments

  • edge string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object: attributes of the edge's target.
  • undirected boolean: whether the edge is undirected.

#.reduceEdges

Returns the accumulated result of applying a callback combining our current value with a computation evaluated on the relevant edges.

Contrary to JavaScript Array.reduce, you must provide it because the callback takes more than one argument and we cannot infer the initial value from our first iteration.

Variants

#.reduceInEdges
#.reduceOutEdges
#.reduceInboundEdges (in + undirected)
#.reduceOutboundEdges (out + undirected)
#.reduceDirectedEdges
#.reduceUndirectedEdges

Arguments

  1. Callback: iterate over every edge.
  • callback function: callback to use.
  • initialValue any: the initial value to use.
  1. Using a node's key: will iterate over the node's relevant attached edges.
  • node any: the related node's key.
  • callback function: callback to use.
  • initialValue any: the initial value to use.
  1. Using source & target: will iterate over the relevant edges going from source to target.
  • source any: the source node's key.
  • target any: the target node's key.
  • callback function: callback to use.
  • initialValue any: the initial value to use.

Callback arguments

  • accumulator any: the accumulated value.
  • edge string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object: attributes of the edge's target.
  • undirected boolean: whether the edge is undirected.

#.findEdge

Returns the key of the first edge matching given predicate function or undefined if no matching node could be found.

Variants

#.findInEdge
#.findOutEdge
#.findInboundEdge (in + undirected)
#.findOutboundEdge (out + undirected)
#.findDirectedEdge
#.findUndirectedEdge

Arguments

  1. Callback: iterate over every edge.
  • callback function: callback to use.
  1. Using a node's key: will iterate over the node's relevant attached edges.
  • node any: the related node's key.
  • callback function: callback to use.
  1. Using source & target: will iterate over the relevant edges going from source to target.
  • source any: the source node's key.
  • target any: the target node's key.
  • callback function: callback to use.

Callback arguments

  • edge string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object: attributes of the edge's target.
  • undirected boolean: whether the edge is undirected.

#.someEdge

Returns whether any edge in the graph matches the given predicate function.

Variants

#.someInEdge
#.someOutEdge
#.someInboundEdge (in + undirected)
#.someOutboundEdge (out + undirected)
#.someDirectedEdge
#.someUndirectedEdge

Arguments

  1. Callback: iterate over every edge.
  • callback function: callback to use.
  1. Using a node's key: will iterate over the node's relevant attached edges.
  • node any: the related node's key.
  • callback function: callback to use.
  1. Using source & target: will iterate over the relevant edges going from source to target.
  • source any: the source node's key.
  • target any: the target node's key.
  • callback function: callback to use.

Callback arguments

  • edge string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object: attributes of the edge's target.
  • undirected boolean: whether the edge is undirected.

#.everyEdge

Returns whether all edges in the graph match the given predicate function.

Variants

#.everyInEdge
#.everyOutEdge
#.everyInboundEdge (in + undirected)
#.everyOutboundEdge (out + undirected)
#.everyDirectedEdge
#.everyUndirectedEdge

Arguments

  1. Callback: iterate over every edge.
  • callback function: callback to use.
  1. Using a node's key: will iterate over the node's relevant attached edges.
  • node any: the related node's key.
  • callback function: callback to use.
  1. Using source & target: will iterate over the relevant edges going from source to target.
  • source any: the source node's key.
  • target any: the target node's key.
  • callback function: callback to use.

Callback arguments

  • edge string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object: attributes of the edge's target.
  • undirected boolean: whether the edge is undirected.

#.edgeEntries

Returns an iterator over relevant edges.

Variants

#.inEdgeEntries
#.outEdgeEntries
#.inboundEdgeEntries (in + undirected)
#.outboundEdgeEntries (out + undirected)
#.directedEdgeEntries
#.undirectedEdgeEntries

Arguments

  1. None: iterate over every edge.
  2. Using a node's key: will iterate over the node's relevant attached edges.
  • node any: the related node's key.
  1. Using source & target: will iterate over the relevant edges going from source to target.
  • source any: the source node's key.
  • target any: the target node's key.

Entries

  • edge string: the edge's key.
  • attributes object: the edge's attributes.
  • source string: key of the edge's source.
  • target string: key of the edge's target.
  • sourceAttributes object: attributes of the edge's source.
  • targetAttributes object: attributes of the edge's target.

Neighbors

These methods iterate over the neighbors of the given node or nodes.

Examples

const graph = new Graph();

graph.mergeEdge('Thomas', 'Rosaline');
graph.mergeEdge('Thomas', 'Emmett');
graph.mergeEdge('Catherine', 'Thomas');
graph.mergeEdge('Rosaline', 'Catherine');
graph.mergeEdge('John', 'Daniel');
graph.mergeEdge('John', 'Daniel');

// Using the array-returning methods
graph.neighbors('Thomas');
>>> ['Rosaline', 'Emmett', 'Catherine']

// Using the callback methods
graph.forEachNeighbor('Thomas', function(neighbor, attributes) {
  console.log(neighbor, attributes);
});

// Using functional-style iteration method
const neighborDegress = graph.mapNeighbors((neighbor) => {
  return graph.degree(neighbor);
});

// Using the iterators
for (const {neighbor, attributes} of graph.neighborEntries()) {
  console.log(neighbor, attributes);
}

#.neighbors

Returns an array of relevant neighbor keys.

Variants

#.inNeighbors
#.outNeighbors
#.inboundNeighbors (in + undirected)
#.outboundNeighbors (out + undirected)
#.directedNeighbors
#.undirectedNeighbors

Arguments

  • node any: the node's key.

#.forEachNeighbor

Iterates over the relevant neighbors using a callback.

Variants

#.forEachInNeighbor
#.forEachOutNeighbor
#.forEachInboundNeighbor (in + undirected)
#.forEachOutboundNeighbor (out + undirected)
#.forEachDirectedNeighbor
#.forEachUndirectedNeighbor

Arguments

  • node any: the node's key.
  • callback function: callback to use.

Callback arguments

  • neighbor string: the neighbor's key.
  • attributes object: the neighbor's attributes.

#.mapNeighbors

Returns an array containing the result of a callback applied on the relevant neighbors.

Variants

#.mapInNeighbors
#.mapOutNeighbors
#.mapInboundNeighbors (in + undirected)
#.mapOutboundNeighbors (out + undirected)
#.mapDirectedNeighbors
#.mapUndirectedNeighbors

Arguments

  • node any: the node's key.
  • callback function: callback to use.

Callback arguments

  • neighbor string: the neighbor's key.
  • attributes object: the neighbor's attributes.

#.filterNeighbors

Returns an array of neighbor keys for which the given predicate function returned true.

Variants

#.filterInNeighbors
#.filterOutNeighbors
#.filterInboundNeighbors (in + undirected)
#.filterOutboundNeighbors (out + undirected)
#.filterDirectedNeighbors
#.filterUndirectedNeighbors

Arguments

  • node any: the node's key.
  • callback function: callback to use.

Callback arguments

  • neighbor string: the neighbor's key.
  • attributes object: the neighbor's attributes.

#.reduceNeighbors

Returns the accumulated result of applying a callback combining our current value with a computation evaluated on the relevant neighbors.

Contrary to JavaScript Array.reduce, you must provide it because the callback takes more than one argument and we cannot infer the initial value from our first iteration.

Variants

#.reduceInNeighbors
#.reduceOutNeighbors
#.reduceInboundNeighbors (in + undirected)
#.reduceOutboundNeighbors (out + undirected)
#.reduceDirectedNeighbors
#.reduceUndirectedNeighbors

Arguments

  • node any: the node's key.
  • callback function: callback to use.
  • initialValue any: the initial value to use.

Callback arguments

  • accumulator any: the accumulated value.
  • neighbor string: the neighbor's key.
  • attributes object: the neighbor's attributes.

#.findNeighbor

Returns the key of the first neighbor matching given predicate function or undefined if no matching node could be found.

Variants

#.findInNeighbors
#.findOutNeighbors
#.findInboundNeighbors (in + undirected)
#.findOutboundNeighbors (out + undirected)
#.findDirectedNeighbors
#.findUndirectedNeighbors

Arguments

  • node any: the node's key.
  • callback function: callback to use.

Callback arguments

  • neighbor string: the neighbor's key.
  • attributes object: the neighbor's attributes.

#.someNeighbor

Returns whether any neighbor in the graph matches the given predicate function.

Variants

#.someInNeighbors
#.someOutNeighbors
#.someInboundNeighbors (in + undirected)
#.someOutboundNeighbors (out + undirected)
#.someDirectedNeighbors
#.someUndirectedNeighbors

Arguments

  • node any: the node's key.
  • callback function: callback to use.

Callback arguments

  • neighbor string: the neighbor's key.
  • attributes object: the neighbor's attributes.

#.everyNeighbor

Returns whether all neighbors in the graph match the given predicate function.

Variants

#.everyInNeighbors
#.everyOutNeighbors
#.everyInboundNeighbors (in + undirected)
#.everyOutboundNeighbors (out + undirected)
#.everyDirectedNeighbors
#.everyUndirectedNeighbors

Arguments

  • node any: the node's key.
  • callback function: callback to use.

Callback arguments

  • neighbor string: the neighbor's key.
  • attributes object: the neighbor's attributes.

#.neighborEntries

Returns an iterator over the relevant neighbors.

Variants

#.inNeighborEntries
#.outNeighborEntries
#.inboundNeighborEntries (in + undirected)
#.outboundNeighborEntries (out + undirected)
#.directedNeighborEntries
#.undirectedNeighborEntries

Arguments

  1. Using a node's key: will iterate over the node's relevant neighbors.
  • node any: the node's key.
  1. Using two nodes' keys: will return whether the two given nodes are neighbors.
  • node1 any: first node.
  • node2 any: second node.

Entries

  • neighbor string: the neighbor's key.
  • attributes object: the neighbor's attributes.