Design Hub developer guide - plugins

    Design Hub's functionality can be extended by plugins in several workflows to meet the expectations for different user groups and use-cases. Plugins are generally implemented as NodeJS modules implementing a simple stateless API, connecting to one or more web services or databases.

    Table of contents:

    Plugin types

    Realtime plugins

    Realtime plugins encapsulate functionality that describe 1 virtual compound in 1 specific area of phys-chem properties, ADMET, commercial availability, literature data, in-silico assay data, structure checks or modeling.

    For more information specifically related to realtime plugins, check the Developer guide - real time plugins.

    Resolver plugins

    A resolver plugin converts a corporate identifier into a chemical structure using a structure database lookup.

    For more information specifically related to resolver plugins, check the Developer guide - resolver plugins.

    Storage plugins

    A storage plugin establishes and maintains a flat database of all virtual compounds in Design Hub. Typically implemented with a SQL database connection, this can be used to support advanced analysis, visualizations, or a backup.

    For more information specifically related to storage plugins, check the Developer guide - storage plugins.

    Registry plugins

    A registry plugin helps lookup the synthesis status and substance ID of a compound by periodically executing searches in a compound registration system or ELN.

    For more information specifically related to registry plugins, check the Developer guide - registry plugins.

    Import plugins

    Import plugins load chemical structures into Design Hub based on user input or automatically, followed by deduplication and processing of records.

    For more information specifically related to import plugins, check the Developer guide - import plugins.

    Company plugins

    A company plugin assists authorizing a user by fetching project and group membership for the user.

    For more information specifically related to registry plugins, check the Developer guide - company plugins.

    Configuration

    All plugins are loaded by the automatically during start up of the application. The definition of plugins to load are set in the configuration guide. For more, check the Configuration guide's servicesDirectory section.

    Development

    For the successful development of a plugin, we recommend the following preparation:

    • an instance of Design Hub available for development purposes, i.e.: the ability to stop and start it, to try different configuration options
    • familiarity with JavaScript, NodeJS and its module system
    • good understanding of Promises / async await

    {info} NodeJS introduction material: https://www.youtube.com/watch?v=_l96hPlqzcI (78m), https://www.youtube.com/watch?v=hKQr2DGJjUQ (19m), https://www.youtube.com/watch?v=cJVXP1bU68Y (48m) NodeJS module description: https://nodejs.org/api/modules.html Promise introduction: https://www.html5rocks.com/en/tutorials/es6/promises/#toc-async, https://github.com/kriskowal/q#readme

    Utility functions

    Most Design Hub plugins benefit from a library of commonly used functions. Chemaxon is providing one as an npm package called @chemaxon/dh-utils, including the following functions:

    • chemical file format conversion using JChem Microservices IO, used whenever a non-Chemaxon backend is involved in the plugin functionality
    • 2D rendering of chemical structures using JChem Microservices IO, used whenever the (realtime) plugin needs to depict molecules
    • a general purpose HTTP library for REST/JSON, multipart or form-urlencoded requests, with basic or Bearer token authentication
    • a utility library for processing PDB files

    Download @chemaxon/dh-utils

    This utility library is published as a scoped npm package. The @chemaxon scope can be accessed by obtaining a Chemaxon account and setting up an npm registry for the scope to Chemaxon's public package repository. The full list of steps to configure this npm registry is:

    # first command obtained from any download page includes your credentials. see Public Repository above.
curl -o ~/.npmrc -u<your email address>:<your auth token> https://hub.chemaxon.com/artifactory/api/npm/auth
# second command from public download page extended with a hack based on https://github.com/npm/cli/issues/4763
npm config set registry https://hub.chemaxon.com/artifactory/api/npm/npm/ --registry=https://hub.chemaxon.com/artifactory/api/npm/npm/
# actually setting @chemaxon registry. cannot be done as step 2.
npm config set @chemaxon:registry https://hub.chemaxon.com/artifactory/api/npm/npm/ --@chemaxon:registry=https://hub.chemaxon.com/artifactory/api/npm/npm/
# optional cleanup 
npm config delete registry

npm install @chemaxon/dh-utils

    Example usage

    const dhutils = require("@chemaxon/dh-utils");

async function calculate(body) {
  const smiles = await dhutils.convert(body.compounds[0].mrvSource, "smiles");
}

    API

    async get(data): String | Buffer | Object

    Sends an HTTP GET request using the NodeJS fetch API. For parameters see below at async req.

    Returns (a Promise of) the response body depending on encoding specified in the request.

    async post(data): String | Buffer | Object

    Sends an HTTP POST request using the NodeJS fetch API. For parameters see below at async req.

    Returns (a Promise of) the response body depending on encoding specified in the request.

    async req(data): String | Buffer | Object

    Sends an HTTP request using the NodeJS fetch API. Parameters:

    Name Type Required Description
    url URL or string yes the HTTP URL to make the request to
    jar CookieJar no See tough-cookie
    formData FormData no See FormData Web API docs
    isMultipartFormData boolean no Some APIs require passing multipart/form-data header even if binary data is not present
    json boolean no Shorthand property to sending the body as stringified text with application/json headers and parsing the response as JSON as well
    method string no GET (default), POST, PUT, PATCH, DELETE
    headers Object no Key-value pair of request headers
    body any no Body/payload of the request
    followRedirect boolean no Follow redirects
    timeout number no Number of milliseconds after which the request is aborted and an error is thrown
    qs Object no Key-value pair of URL encoded query strings (search params) to append to the path of the URL. See URLSearchParams
    auth Object no Allows Basic authentication using Base64 encoded credentials when username and password is specified. Allows sending Bearer tokens when bearer is specified
    auth.username string no Username of basic authentication for base64 encoding
    auth.password string no Password of basic authentication for base64 encoding
    auth.bearer string no Value of bearer token

    Returns (a Promise of) the response body depending on encoding specified in the request.

    async convert(structure, toFormat): String

    Converts the input chemical structure to the specified format using JChem Microservices IO.

    Parameters:

    • structure (string): the chemical structure to convert
    • toFormat (string): the desired format string. See File Formats.

    Note: use of this method requires configuring the following environment variable:

    Returns:

    • the input chemical structure converted to the desired format.

    async convertFile(fileContents, toFormat): Buffer

    Converts the input chemical structure file to the specified format using JChem Microservices IO.

    Parameters:

    • fileContents (Buffer | String): the chemical structure file to convert
    • toFormat (string): the desired format string. See File Formats.

    Note: use of this method requires configuring the following environment variable:

    Returns:

    • the input converted to the desired format.

    async batchConvert(structures, toFormat): string[]

    Converts the input chemical structure to the specified format using JChem Microservices IO.

    Parameters:

    • structures (string[]): an array of chemical structure to convert
    • toFormat (string): the desired format string. See File Formats.

    Note: use of this method requires configuring the following environment variable:

    Returns:

    • the input chemical structure array converted to the desired format.

    async append(structures, toFormat): string[]

    Merges multiple input chemical structure into a single one in the specified format using JChem Microservices IO.

    Parameters:

    • structures (string[]): an array of chemical structures
    • toFormat (string): the desired format string. See File Formats.

    Note: use of this method requires configuring the following environment variable:

    Returns:

    • the input chemical structure array merge into a single multistructure file.

    async clean(structure, dimension, format): string

    Rearranges of the atomic coordinates of the input structure.

    Parameters:

    • structure (string): the chemical structure to process
    • dimension (number): dimension to clean to. Values: 2, 3. Optional. Default: 2.
    • format (string): the desired format string. See File Formats. Optional. Default: mrv.

    Note: use of this method requires configuring the following environment variable:

    Returns:

    • the input chemical structure with new atomic coordinates in the desired format.

    async getImageURLs(structures, width?, height?): string[]

    Generates data URLs with base64 encoded PNG images of the input chemical structures using the following format configuration: w${width},h${height},transbg,cpk,wireframe,nosource,marginSize2,maxscale28. See File Formats for specifications.

    Parameters:

    • structures (string[]): an array of chemical structure to render as images
    • width (number): width of the image. Optional. Default: 400.
    • height (number): height of the image. Optional. Default: 260.

    Note: use of this method requires configuring the following environment variable:

    Returns:

    • an array of data URLs with base64 encoded PNG images as strings. For more details see Data URLs.

    async getCleanedImageURLs(structures, width = 400, height = 200): string[]

    Rearranges the atomic coordinates of the input chemical structures, and then generates data URLs with base64 encoded PNG images using the following format configuration: w${width},h${height},transbg,cpk,wireframe,nosource,marginSize2,maxscale28. See File Formats for specifications.

    Parameters:

    • structures (string[]): an array of chemical structure to render as images
    • width (number): width of the image. Optional. Default: 400.
    • height (number): height of the image. Optional. Default: 260.

    Note: use of this method requires configuring the following environment variable:

    Returns:

    • an array of data URLs with base64 encoded PNG images as strings. For more details see Data URLs.

    async PDBUtilities.load(pdbCode): string

    Downloads a PDB file with the specified 4 letter code from the Protein Data Bank.

    Parameters:

    • pdbCode (string): the 4 letter code of a PDB file

    Returns:

    • the PDB file

    async PDBUtilities.findLigands(pdbCode): string[]

    Downloads a PDB file with the specified 4 letter code from the Protein Data Bank and extracts the list of available ligands.

    Parameters:

    • pdbCode (string): the 4 letter code of a PDB file

    Returns:

    • the residue codes of the available ligands in the file as an array of strings.

    async PDBUtilities.getResidue(pdbCode, ligandCode): string

    Downloads a PDB file with the specified 4 letter code from the Protein Data Bank and extracts a specific ligand.

    Parameters:

    • pdbCode (string): the 4 letter code of a PDB file
    • ligandCode (string): code of the ligand to extract, e.g.: HEM, A:HEM, or A:HEM350

    Returns:

    • the ligand as a valid minimal PDB file

    async PDBUtilities.findLigandsFromFile(pdbFile): string[]

    Extracts the list of available ligands from the specified PDB file.

    Parameters:

    • pdbFile (string): the contents of the PDB file

    Returns:

    • the residue codes of the available ligands in the file as an array of strings.

    async PDBUtilities.getResidueFromFile(pdbFile, residueCode): string[]

    Extracts a specific ligand from the specified PDB file.

    Parameters:

    • pdbFile (string): the contents of the PDB file
    • ligandCode (string): code of the ligand to extract, e.g.: HEM, A:HEM, or A:HEM350

    Returns:

    • the ligand as a valid minimal PDB file

    History of changes

    v4.2.18

    • with version 4 of dh-utils, the deprecated request dependency is replaced with node-fetch

    v3.1.0

    • added append method

    v3.0.1

    • package renamed from ml-utils to dh-utils

    v2.5.0

    • added convertFile method

    v2.4.0

    • added PDBUtilities.findLigandsFromFile method

    v2.2.2

    • added batchConvert method

    v2.1.6

    • added clean method

    v2.0.0

    • initial version with compatibility to JChem Microservices

    To find all available version numbers, use:

    npm view @chemaxon/dh-utils versions

    Example plugins

    You can find a brief selection of plugins in our Github repository for various plugin types.