JavaScript APIdoc

Frontend components

class appDescription()

The main component of the SMARTSexplore app.

appDescription.computed

Computed properties of the SMARTSexplore app.

appDescription.computed.displayMatches()

Whether to display molecule matches, based on matchesLoaded and settings.showMatches.

Returns

boolean –

appDescription.computed.nodeColorFn()

The current coloration function for the SMARTS nodes. Switched based on displayMatches:

  • If displayMatches is true, uses the number of matches relative to the maximum number of matches of all SMARTS to color each SMARTS node.

  • If displayMatches is false, uses the mapping of libraries to colors to color each SMARTS node.

appDescription.computed.nodeVisibleFn_()

The current visibility functions for the SMARTS nodes. Nodes are visible if they are included in the library selection and the search regexp matches their name (or is empty).

appDescription.computed.nodeClassFn()

The current CSS class function for the SMARTS nodes. Sets ‘hidden’ if the node is not visible, ‘muted’ if it has been muted (by DFS actions), ‘highlighted’ if it is highlighted (by selection via hovering/clicking), and ‘transparent-border’ if molecule matches are displayed and this node has none.

appDescription.computed.nodeActiveFn()

The function determining if nodes are active (included in the simulation, DFS, …). Currently returns the exact same value as nodeVisibleFn.

appDescription.computed.edgeColorFn()

The edge coloration function. Uses the current similarity->color mapping, see the similarityToColor computed prop.

appDescription.computed.edgeStyleFn()

The edge CSS style function. Determines the numerical edge width based on the similarity value, using a quadratically proportional formula with upper and lower width bounds. Equal edges are all displayed with the maximum thickness.

appDescription.computed.edgeClassFn()

The edge CSS class function. Mostly combines results for the nodes this edge connects. If at least one node is hidden or muted, the edge is, too. Apart from this, sets ‘highlighted’ if the edge is selected, and ‘equal’ if it is an equal edge.

appDescription.computed.edgeActiveFn()

The function determining if an edge is active (included in the simulation, DFS, …). For the edge to be active, both connected nodes must be visible, and the edge must fall within the chosen edge similarity range.

appDescription.computed.graphLibraries()

All SMARTS libraries stored in the graph, see getLibrariesFromGraph.

appDescription.computed.libraryToColor()

Maps libraries to colors, see librariesToColorMapping.

appDescription.computed.similarityToColor()

Maps edge similarity to a color value, based on the edgeSimilarity settings. Configured by the number of quantization steps, the chosen color map (all from d3-scale-chromatic are available), and the currently chosen similarity range (for normalization).

appDescription.watch

Watchers of the SMARTSexplore app

appDescription.watch.selectedObject()

Watches ‘selectedObject’ and updates the ‘highlighted’ meta attribute on both the previously selected and the newly selected object.

appDescription.watch.graphLibraries()

Watches ‘graphLibraries’ and keeps the library selection up to date, by dropping removed libraries and adding new libraries with a default ‘true’ value for the selection

appDescription.watch."settings.searchString"()

Watches ‘searchString’ to parse it as a regular expression, updates ‘searchRegexp’ if parsing is successful, and sets an error flag if parsing fails.

appDescription.beforeMount()

Before mounting this component, starts to fetch the initial graph from the backend.

appDescription.data()

Generates initial data for the SMARTSexplore app.

getLibrariesFromGraph(graph)

Returns all SMARTS libraries referred to by a graph’s nodes, sorted alphabetically by name.

Arguments

  • graph (Graph|Object) – an object containing nodes that all have a ‘library’ property

librariesToColorMapping(libraries, colors)

Returns an object that maps SMARTS libraries to colors, by order in the libraries array parameter (using the Kelly colors by default).

Arguments

  • libraries (Array) – The libraries to map colors for

  • colors (Array) – (optional) The colors to map to. Kelly colors, if not given.

Returns

An object mapping libraries (strings) to colors (strings).

matchesSearchRegexp(node, regexp)

Verifies if a SMARTS node matches a search regexp. A falsy (empty/null) regex will lead to a truthy result.

Arguments

  • node (Node) – A node object (generally, an object with a name property).

  • regexp (Regexp) – A Regexp to match against the node’s name.

Returns

true if the regex matches or if the regex is falsy (empty/null). false otherwise.

Graph components

class SmartsGraph()

Vue component that renders a directed SMARTS graph as an interactive SVG.

SmartsGraph.computed

Computed props of this component

SmartsGraph.computed.activeEdges()

The currently active edges (determined by the edgeActiveFn prop)

SmartsGraph.computed.activeNodes()

The currently active nodes (determined by the nodeActiveFn prop)

SmartsGraph.computed.nodeClassFn_()

Merges external nodeClassFn behavior with component-internal behavior

SmartsGraph.methods

The methods of this component

SmartsGraph.methods.initGraphSimulation()

Initialize the graph simulation and return the SimulatedGraph instance

SmartsGraph.methods.initSimulation()

Set up and store a simulation with the devised forces and parameters.

SmartsGraph.methods.restartSimulation(alpha, alphaDecay)

Restart the simulation, optionally setting a new alpha and alphaDecay.

Arguments

  • alpha (Number) – The ‘temperature’ of the simulation (see d3-force docs)

  • alphaDecay (Number) – The ‘temperature decay speed’ of the simulation (see d3-force)

SmartsGraph.methods.onSimulationTick()

Runs on each tick of the force simulation. Updates node and edge positions efficiently. Note that this function somewhat bypasses Vue render logic and only works when the getId function is ensured to work properly to link up exactly the correct nodes with exactly the correct SMARTS objects.

SmartsGraph.methods.initGraphZoom()

Sets up panning & zooming for the graph.

SmartsGraph.methods.handleNodeDragStart()

Handles the user dragging a node, by removing nodes that are not in the same CC from the force simulation. Improves responsiveness.

SmartsGraph.methods.handleNodeDrag()

Handles the user dragging a node, by taking its dragged position as fixed.

SmartsGraph.methods.handleNodeDragEnd()

Handles the user stopping to drag a node, by resetting the choice of nodes currently active in the force simulation

SmartsGraph.methods.handleNodeDblClick()

Handles the user double-clicking a node, by unfixing it

SmartsGraph.methods.handleBackgroundClick()

Emits an event when the user clicks on the background.

SmartsGraph.props

The props of this component.

SmartsGraph.props.graph

The Graph instance to render

SmartsGraph.props.nodeClassFn

A function that returns a (CSS class) -> (boolean) mapping given a node. Only if the boolean is true, the class will be added to the node. No classes by default.

SmartsGraph.props.nodeColorFn

A function that returns a color given a node (white by default).

SmartsGraph.props.nodeStyleFn

A function that returns a (key)->(value) CSS style mapping given a node. No styles by default

SmartsGraph.props.nodeActiveFn

A function that determines if a node is active (shown, included in the layout and force simulation, visited during DFS)

SmartsGraph.props.edgeClassFn

A function that returns a (CSS class) -> (boolean) mapping given an edge. Only if the boolean is true, the class will be added to the edge. No classes by default.

SmartsGraph.props.edgeColorFn

A function that returns a color given a node (black by default).

SmartsGraph.props.edgeStyleFn

A function that returns a (key)->(value) CSS style mapping given an edge. No styles by default

SmartsGraph.props.edgeActiveFn

A function that determines if an edge is active (shown, included in the layout and force simulation, traversed during DFS)

SmartsGraph.beforeMount()

Sets up a watcher to reinitialize the graph simulation if the graph or the active edges change (not deep-watching, so only triggers when these are replaced)

SmartsGraph.mounted()

Sets up the zoom functionality for the graph

class ArrowheadMarker()

Vue component that renders an SVG marker for an arrowhead. Used implicitly by the SmartsSubsetEdge component.

class ArrowheadMarkers()

Vue component that renders multiple SVG markers for an arrowhead, given a set of colors. Used implicitly by the SmartsSubsetEdge component.

class SmartsNode()

Vue component that renders a single SMARTS node.

class SmartsNodes()

Vue component that renders a collection of SMARTS nodes.

class SmartsSubsetEdge()

Vue component that renders a single directed SMARTS subset edge.

class SmartsSubsetEdges()

Vue component that renders a collection of directed SMARTS subset edges.

Information components

class AboutButton()

The about button of the app, containing a modal that explains the application to the user.

class MatchesGrid()

A Vue component that renders a grid of matches, optionally with custom CSS classes attached to each rendered match, based on an arbitrary function’s return values.

MatchesGrid.methods

The methods of MatchesGrid.

MatchesGrid.methods.getMoleculeImageURL(molecule_id)

Gets the appropriate image URL given a molecule id. Doesn’t do any validation, neither for existence nor for input data.

Arguments

  • molecule_id (integer) – The molecule ID to get an image URL for.

Returns

string – The image URL for that molecule.

MatchesGrid.props

The props of MatchesGrid.

MatchesGrid.props.matches

type: array

An array of matches, which must each be an object containing a molecule_name (string) and a molecule_id (integer).

MatchesGrid.props.classFn

type: function

An optional function that associates a CSS class (or multiple, in one space-separated string) with every rendered molecule match.

class InfoBox()

Vue component that renders the information box of SMARTSexplore, displaying an appropriate image and otherwise wrapping the SmartsInfo and SmartsSubsetEdgeInfo components (depending on whether it’s showing a SMARTS node or a subset edge).

InfoBox.computed

Computed props of this component

InfoBox.computed.objType()

The tupe of the rendered object (as a string). Possible return values are ‘node’, ‘edge’ and ‘null’.

InfoBox.computed.title()

The title of the info box. For SMARTS, shows their name. For edges, shows the subset (or equality) relationships by connecting both SMARTS’ names with an appropriate symbol.

When no object is displayed, shows an instructional string.

InfoBox.computed.previewHref()

Determines the href (URL) of the preview image to show.

class SmartsInfo()

Vue component that displays information about a SMARTS node.

class SmartsSubsetEdgeInfo()

Vue component that displays information about a directed SMARTS-SMARTS subset edge.

SmartsSubsetEdgeInfo.computed

Computed props of this component

SmartsSubsetEdgeInfo.computed.commonMatches()

An array of the molecule matches that are common to both of this edge’s SMARTS. Returns nothing if the showMatches prop is not truthy.

SmartsSubsetEdgeInfo.computed.differentMatches()

An array of the molecule matches that are different between both of this edge’s SMARTS. Returns nothing if the showMatches prop is not truthy.

SmartsSubsetEdgeInfo.props

Props of this component

SmartsSubsetEdgeInfo.props.edge

The Edge object to display

SmartsSubsetEdgeInfo.props.showMatches

Whether to show molecule matches on the edge (based on data stored on its SMARTS)

Settings components

class RangeSlider()

A bidirectional range slider component, wrapping Materialize’s noUiSlider variant.

RangeSlider.props

Props of the range slider.

RangeSlider.props.modelValue

type: array

The model value, which is an array of length 2, the currently chosen [min, max] interval.

RangeSlider.props.min

type: number

The minimum range value available to the user

RangeSlider.props.max

type: number

The maximum range value available to the user

RangeSlider.props.step

type: number

The step size between available values

RangeSlider.props.startMin

type: number

The initially selected minimum value

RangeSlider.props.startMax

type: number

The initially selected maximum value

RangeSlider.mounted()

creates slider with materialize noUiSlider with defaults as described in app.js connect set to true so that current range is highlighted orientation horizontal, pips describe labelling and ticks under the range

Internal graph representation

class Node(plainNode, defaultMeta=null)

Represents a node in a SMARTS graph. Stored properties are:

  • id: a unique ID (preferably int or string)

  • name: A descriptive name of this node (string)

  • pattern: The SMARTS pattern of this node (string)

  • library: The name of the SMARTS library this node belongs to (string)

  • outgoingEdges: An array of outgoing edges (to be attached by an enclosing Graph)

  • incomingEdges: As above, but incoming edges.

  • incidentEdges: Combines outgoing and incoming edges.

  • meta: A dictionary to store arbitrary metadata about this node.

Constructs a new Node object from a “plain node”, i.e. an object that has all properties documented for this class, apart from all the …*Edges properties and the .meta property.

Arguments

  • plainNode (Object) – A “plain node” object as described above

  • defaultMeta (Object) – (optional) an object containing keys with default values that will be assigned to the .meta property.

class Edge(plainEdge, defaultMeta=null, getNodeFn=null)

Represents an edge in a SMARTS graph. Stored properties are:

  • id: a unique ID (preferably int or string)

  • mcssim: MCS similarity (float between 0.0 and 1.0)

  • spsim: SP similarity (float between 0.0 and 1.0)

  • type: a string describing the type this edge has (equal / subset)

  • source: the unique ID of the source Node object

  • target: the unique ID of the target Node object

  • meta: A dictionary to store arbitrary metadata about this edge.

Constructs a new Edge object from a “plain edge”, i.e., an object that has all properties documented for this class, apart from the .meta property.

Can attach arbitrary metadata to the .meta property by passing default values as an object defaultMeta.

If the getNodeFn function parameter is passed, it will be called with the source and target IDs to replace the .source and .target properties on the returned Edge, by whatever values that function returns.

Arguments

  • plainEdge (Object) – A “plain edge” object as described above

  • defaultMeta (Object) – (optional) an object containing keys with default values that will be assigned to the .meta property.

  • getNodeFn (function) – (optional) A function that will be used to retrieve matching Node object for the source and target IDs. If not passed, .source and .target will be stored unchanged, i.e. as their IDs.

class Graph(nodes, edges, defaultNodeMeta=null, defaultEdgeMeta=null, markEqualEdges=true)

A directed graph consisting of Node obejcts and Edge objects.

Constructs a new Graph object from arrays ‘nodes’ and ‘edges’. Allows the attachment of metadata to every node and edge using a dictionary of default values for both.

Arguments

  • nodes (Array) – An array of plain-object nodes. See Node class for details.

  • edges (Array) – An array of plain-object edges. See Edge class for details.

  • defaultNodeMeta (Object) – (optional) an object containing default values for arbitrary keys, to be attached as metadata to every node.

  • defaultEdgeMeta (Object) – (optional) an object containing default values for arbitrary keys, to be attached as metadata to every edge.

  • markEqualEdges (Boolean) – (optional) If true (default), automatically detect equal edges, i.e., a pair of edges (l,r) and (r,l), and mark them as having .type == ‘equal’. Will also remove one of each pair’s edges, and sort the stored edges so that equal edges come last (useful for rendering order).

Graph._createEdge(plainEdge)

Creates and inserts an Edge object from a plain-object description into this graph, using the Edge constructor.

Arguments

  • plainEdge (*) –

Graph._createNode(plainNode)

Creates and inserts a Node object from a plain-object description into this graph, using the Node constructor.

Arguments

  • plainNode (Object) – The plain-object description of the node, e.g. received as JSON.

Graph._findMarkAndSortEqualEdges()

Finds and marks edges a->b where b->a exists as well, implying node equality. Also re-orders edges such that equal edges come last (useful for rendering order). Mutates this.edges: When the second edge of a pair is found, it is filtered out from this.edges.

Graph.addEdge(edge)

Adds a new Edge to this graph.

Arguments

  • edge (Edge) – The Edge object to add. Must have a newly unique ID, or the behavior of this Graph is undefined.

Graph.addNode(node)

Adds a new Node to this graph.

Arguments

  • node (Node) – The Node object to add. Must have a newly unique ID, or the behavior of this Graph is undefined.

Graph.getCCs(edgeFilter=null, nodeFilter=null)

Calculates the connected components of this graph. Returns a 2-tuple of:

  • a dict mapping (CC id) -> (list of nodes in CC)

  • a dict mapping (node id) -> (id of CC that contains this node)

Arguments

  • edgeFilter (function) – (optional) a predicate to filter which edges will be traversed

  • nodeFilter (function) – (optional) a predicate to filter which nodes will be visited

Graph.getEdgeById(id)

Returns an Edge by ID if present, undefined otherwise.

Arguments

  • id (any) – The ID of the Edge to be returned.

Graph.getNodeById(id)

Returns a Node by ID if present, undefined otherwise.

Arguments

  • id (any) – The ID of the Node to be returned.

Graph.plainClone()

Returns a clone of this graph simply by reusing the plain nodes, plain edges, and their default meta values.

Accordingly, will not copy any data updated after creation of this graph.

Graph.runDFS(startNodes, direction, maxDepth, visitedNodeCallback=null, visitedEdgeCallback=null)

Runs a depth-first search through this graph starting from some Node, calling arbitrary callback functions at each visited node and edge.

Arguments

  • startNodes (Array) – The Node object(s) to start the DFS from. Must be part of this Graph. Can pass a list of Nodes or a single Node.

  • direction (String) – The direction(s) to traverse edges in. Can be ‘outgoing’, ‘incoming’, or ‘all’.

  • maxDepth (Number) – The maximum depth of the DFS. Convention: If maxDepth == 1, then exactly all directly adjacent nodes of selectedNode are visited.

  • visitedNodeCallback (function) – (optional) A callback that will be called for every visited node, with arguments: (visited node {Node}, current DFS depth {Number}).

  • visitedEdgeCallback (function) – (optional) A callback that will be called for every traversed edge, with arguments: (traversed edge {Edge}, edge outgoing? {Boolean}) TODO document new params

Graph.setPositionsFromCCs(edgeFilter, nodeFilter)

Sets node positions (x, y) to a grid, based on the connected components.

  • Every node in one CC will be assigned the same position.

  • Nodes in CCs with at least 2 nodes are put into one–roughly quadratic–regular grid, ordered by corresponding CC size

  • Nodes in CCs with only one node (isolated nodes) are put into another –roughly quadratic–regular grid, separate from the first one.

Arguments

  • edgeFilter (function) – (optional) a predicate to filter which edges will be traversed

  • nodeFilter (function) – (optional) a predicate to filter which nodes will be visited

class SimulatedGraph(graph, simulation, activeEdgeFilter, activeNodeFilter)

A special implementation for executing a force layout simulation on the graph was required, due to performance-degrading interactions between the force layout by the d3 library and the update logic of the VueJS library. When a d3 force layout is running, it stores the required position and velocity data directly on the node objects. It repeatedly overwrites these values several times even before each single simulation step (tick) is complete. When VueJS recognises changes in data, it attempts to update the visual components presenting this data. Therefore, when VueJS is instructed to present the same node objects that the d3 force layout is working on, a significant performance hit is incurred by the large amount of intermediate position data updates. Because of this, we designed this class, which contains two copies of the same graph: (1) a copy that VueJS presents, storing all presentational data except for node positions, and (2) a copy that the force layout works on, storing only nodes, edges and the force layout data. These copies are then linked in the frontend code by shared node and edge IDs, and the positions of the displayed nodes are only updated once after each force simulation tick is complete. This approach fully avoids the performance hit.