@cylynx/motif

This is the core library of Motif.

Installation

npm install --save @cylynx/motif

Usage

import React from 'react';
import { Client as Styletron } from 'styletron-engine-atomic';
import { Provider as StyletronProvider } from 'styletron-react';
import { BaseProvider } from 'baseui';
import Motif, { MotifLightTheme, MotifDarkTheme } from '@cylynx/motif';
import { Provider } from 'react-redux';
import store from './redux-store';
import '@cylynx/motif/dist/motif.css';

const engine = new Styletron();

const App = () => {
  return (
    <StyletronProvider value={engine}>
      <BaseProvider theme={MotifLightTheme}>
        <Provider store={store}>
          <Motif
            name='Motif'
            primaryTheme={MotifLightTheme}
            secondaryTheme={MotifDarkTheme}
            accessors={{
              nodeID: 'id',
              edgeID: 'id',
              edgeSource: 'source',
              edgeTarget: 'target',
            }}
          />
        </Provider>
      </BaseProvider>
    </StyletronProvider>
  );
};

export default App;

Folder Structure

Main elements are highlighted below

├── cypress # e2e tests
├── demo # Test application for development using vite
├── dist
├── node_modules
├── src
│   ├── assets # svg file
|   ├── components # ui components (no states)
│   ├── constants 
|   ├── containers # application components with state
│   │   ├── Graph # graph initialisation, behaviour, hook, styles
│   │   ├── ImportWizardModal # Import data wizard component
│   │   ├── SidePanel # Layers, options, filter, search panels
│   │   ├── Toolbar
│   │   ├── VariableInspector
│   │   ├── [...other folders]
│   │   └── Explorer.tsx # Assembles all the components
|   ├── redux # application logic and state
│   │   ├── graph # graph state
│   │   ├── import # import state
│   │   ├── investigate # combine reducer and selectors
│   │   ├── ui # ui state (fetch, import, modal, toasts)
│   │   ├── widget # controls which widget is displayed
│   │   └── import # import state
|   ├── theme # baseui theme
|   └── utils # data and graph utils for styling and aggregating
└── index.ts # all exports

Graph Format

Please refer to graph types for up-to-date information on the exact specifications.

JSON

The basic graph structure is represented as a JSON object and is similar to a D3 like graph data structure. Here's are the typings from the GraphData object:

export interface GraphData {
  nodes: Node[];
  edges: Edge[];
  metadata?: Metadata;
  key?: number | string;
}

It requires two keys nodes and edges with array of objects as values.

nodes requires an id field to uniquely identify the nodes. edges requires id, source and target field to join a source node to a target node. The source and target should correspond to the nodes.id. Sample format for a simple json import is shown below:

{
  "nodes": [
    {
      "id": "cat"
    },
    {
      "id": "dog"
    }
  ],
  "edges": [
    {
      "id": "txn cat-dog",
      "source": "cat",
      "target": "dog"
    }
  ]
}

A key attribute, if provided is used for de-deuplication purposes when multiple graphData is imported. The metadata field is parsed and inserted by the program at the data import stage. This contains information on the field typings.

CSV

The application provide flexibilities for the user to upload single edge list or separate node and edge dataset in CSV format. A first row header is required and is used to infer the columns of datasets. Each line that follows is taken as a data record.

Edge List (One File)

Edge List CSV requires id, source and target column to specify the relationship of nodes. The source and target field will be mapped to the underlying properties in the edge object in the graph. Other attributes will be treated as edge properties.

Node and Edge (Two Files)

The Edge CSV is mapped to the edge object in the graph and Node CSV is mapped to the node object. The source and target field in the Edge CSV should correspond with the id in the Node CSV.

Neo4j

The demo also comes with a sample database connection with Neo4j via its default javascript library through websocket connection. Queries written in the Cypher query language will be sent to Neo4j for processing and returned to the application for visualization.

Widgets

Widgets hook into the graph state and provide more information on it as well as other controls to modify the state.

Layers Panel

Located in ./src/containers/SidePanel/LayersPanel

Displays information on the overall graph imports exposes a node properties and edge properties panel which can be toggled to manage the tooltips of the graph.

Styles Panel

Located in ./src/containers/SidePanel/OptionsPanel

Allows configuration of layouts, node and edge styles

Filter Panel

Located in ./src/containers/SidePanel/FilterPanel

Allows adding of filters to limit the data that is displayed. Filters apply additively.

Search Panel

Located in ./src/containers/SidePanel/SearchPanel

Retrieve information on nodes / edges by searching on their id. Also displays results when users select nodes or edges on the graph.

Variable Inspector

Located in ./src/containers/VariableInspector

Adds a soft filter to the graph for a user to focus on particular areas of interest. It can be used on a time-series attribute with the playback action buttons to visualise activities over time.

Toolbar

Located in ./src/containers/Toolbar

Some helpful buttons to configure legend, expand to fullscreen, undo, redo, zoom-in, zoom-out, and clear canvas.

State Management

State is managed by redux. See the respective slice.ts in the redux folder for more information on the actions and reducers.

It is recommended that an application controls the state of the graph through this action/reducer framework to ensure that the rest of the user interface is correctly rendered.

License

MIT © cylynx