graphxr-api

graphxr-api is a module which provides an API to GraphXR internals

Documentation

Documentation is hosted on GitHub

Table of Contents

• Algorithm
  • Centrality
    • betweenness
    • closeness
    • pageRank
  • Community Detection
    • connectedComponent
    • louvain
    • stronglyConnectedComponent
  • Path Finding
    • dijkstra
    • traceNeighbors // Highlight all paths of a certain depth from the root node
• Camera
  • flyToCenter // Fly to the center of a group of nodes
  • flyToPosition // Fly to a specific node
  • setCameraRotating
• Events
  • observe // Create a reactive Grove variable. Wraps on()
  • on // Register a callback function with a GraphXR event
• Filter
  • Handy filter functions e.g. GraphXR.getLayoutGraph().getNodes().filter(GraphXR.nodesByCategory("Episodes"))
  • nodesByCategory
  • edgesByRelationship
• Graph
  • e.g. GraphXR.getLayoutGraph() -> LayoutGraph // an API to the main graph rendered in GraphXR
    • Some member functions include
    • addEdges, addNodes, removeEdges, removeNodes
    • getEdges // Returns only visible edges
    • getNodes // Returns only visible nodes
    • Visibility
      • hideEdges, hideNodes
      • showEdges, showNodes
    • Nodes and Edges returned from API functions are immutable, so you need to use these setters
      • setEdgeProperties, setNodeProperties
      • node.setStyle, edge.setStyle
      • setNodeCollection
  • Category
    • getCategoryColor
    • setCategoryCaptionProperties
  • Edge
    • makeEdge
  • Node
    • makeNode
    • makeNodeId
• Layout
  • e.g. GraphXR.getLayoutGraph().applyLayout(GraphXR.cube())
  • alignBy
  • circle
  • cube
  • distributionBy
  • ego
  • grid
  • line
  • Parametric
    • parametric
    • setParametricAxesOptions
  • random
  • rotate
  • scale
  • shift
  • spiral
  • triggerForceLayout
• Legend
  • colorNodesByProperty
• Neo4j
  • expandNodes
  • neo4j // Execute a Neo4j Through Server query
• Project Settings
  • setAutoShowImage
  • setEdgeScale
• Render (THREE.js helpers)
  • getScene
• Sort
  • comparePropertyValues
  • sortByProperty
• Styles
  • makeColor
  • makePosition
  • makeRandomPosition
• Transform
  • e.g. GraphXR.getLayoutGraph().applyTransform(GraphXR.collectNodes())
  • aggregate
  • collectNodes
  • explodeCollections
  • uncollectNodes
  • extract
  • filter
  • link
  • map
  • merge
  • shortcut
• Utility
  • sleep // Returns a Promise which resolves in a number of milliseconds
• Window
  • setFullscreen

Examples

// Latest
GraphXR = (await require('graphxr-api')).getApi()

// Target a version
GraphXR = (await require('graphxr-api@0.0.3')).getApi()

// Get nodes
GraphXR.getLayoutGraph().getNodes()

// Apply Layout
const view = GraphXR.getLayoutGraph()
view.applyLayout(GraphXR.line({
  sort: 'price',
  filter: (node: Node) => node.properties.price > 13,
}))
view.applyLayout(GraphXR.rotate({
  dimension: 'x',
  theta: 90,
}))
view.applyLayout(GraphXR.parametric({
  x: 'price',
}))
view.applyLayout(GraphXR.distributionBy({
  dimension: 'y',
  bin: 'seasonNumber',
}))

// Apply Transform
const view = GraphXR.getLayoutGraph()
view.applyTransform(GraphXR.extract({
  category: "Episodes",
  props: [
    {
      name: "seasonNumber",
      newName: "seasonNumber",
      isSplit: false,
      splitChar: "",
      isKey: true,
    }
  ],
  newCategory: "Season Number",
  newRelationship: "inSeason",
  inheritLinks: false,
  skipEmpty: true,
}))

Minimum Version Requirements

If a version of the API depends on a version of GraphXR which has not been released, please increase the minimum required version in src/minimumRequirements.ts. For example:

export const MINIMUM_GRAPHXR_VERSION = "2.11.0";

On init, the API will ask GraphXR for its version by fetching /api/install/version. If the version is greater than the minimum version, the API will throw an exception.

If GraphXR cannot be detected, init will log a warning to the console.

If the minimum requirements are met, init will return the API.

Build

yarn build

Testing

Integration (cypress/)

The integration tests run the API against a local GraphXR instance.

It assumes auth is disabled. Comment out adminEmail in GraphXR's config.js to disable auth.

First create file .env in the root folder (web/api/.env) with contents.

# Points at a GraphXR instance
CYPRESS_baseUrl=https://localhost:3000

Run once: yarn test or yarn test:integration

Coverage

Running the tests will result in a text report:

-------------------|---------|----------|---------|---------|-------------------
File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------------|---------|----------|---------|---------|-------------------
All files          |     100 |      100 |     100 |     100 |
 addNodes.ts       |     100 |      100 |     100 |     100 |
 clearGraph.ts     |     100 |      100 |     100 |     100 |
 getNodes.ts       |     100 |      100 |     100 |     100 |
 getScene.ts       |     100 |      100 |     100 |     100 |
 index.ts          |     100 |      100 |     100 |     100 |
 makeNode.ts       |     100 |      100 |     100 |     100 |
 removeNodeById.ts |     100 |      100 |     100 |     100 |
 setRuntime.ts     |     100 |      100 |     100 |     100 |
-------------------|---------|----------|---------|---------|-------------------

This project tries to have as near 100% code coverage as possible.

A more detailed report is located at coverage/lcov-report/index.html.

Note: some code is ignored. e.g. anything using observablehq.

Documentation

yarn build:docs will run tsdoc and generate html at docs/index.html

Publishing to NPM

This process will do the following

• ensure you are logged into npm
• ensure working directory is clean
• run tests
• build the API bundle
• build the documentation
• bump the package.json version
• commit the bundle, docs, and package.json
• tag the commit with the new version
• push the commits
• push the tag
• publish the package to npm

In a terminal:

1. yarn login
2. yarn release

Most of the time you will run yarn release

Optional arguments to yarn release

• --no-verify Skips the tests.
• --no-publish-docs Skips building and publishing docs.
• --beta Publishes a new version tagged "beta" so that require("graphxr-api@beta") loads that version, and require("graphxr-api") does not.
• -v, --version <version> Release type: [v]1.0.34 | patch | minor | major.
• -m, --tag-message <message> Tag message. Default is "".