iChemLabs Cloud Services

Introduction

Cloud services provide quick access to advanced cheminformatics algorithms, database access, graphics functions, and other complex features that are not available directly through Javascript. This is done by utilizing the ChemDoodle Java API (the same API that powers the ChemDoodle desktop application). The ChemDoodle Web Components library accesses the ChemDoodle Java API through AJAX XMLHttpRequest Level 2 (XHR2) calls to our server. XHR2 requires that our server recognize your origins (domains). Access to our services from academic organizations is free. Otherwise, our rates are very reasonable, please view our support options.

Licensees of Cloud services can also host the Cloud servlet on their own servers, and use AJAX XMLHttpRequest Level 1 (XHR1) calls instead, which are fully supported in all browsers. Contact us for more information.

Usage

All iChemLabs cloud services are accessed through the ChemDoodle.iChemLabs package. The complete API is listed below. Before we continue, a little background in AJAX is required. AJAX allows a browser to contact a server and update the Javascript state without reloading the current webpage. This is a very powerful technology. Most AJAX calls will be instantaneous, but it is important to note that this is an additional connection to the internet, and lag can occur for any reason. In the case of lag, we don’t want an AJAX call to hold up the loading of a webpage or to prevent responsiveness while the request is being handled, so these calls are made to be asynchronous. This is done by providing a callback function. When the server has finished handling the request, the response is returned to the callback function, which then executes. This is demonstrated in the following code using the readSMILES() function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
  <script>
    ChemDoodle.iChemLabs.readSMILES(
      // SMILES string
      'N1(C)C(=O)N(C)C(C(=C1N1)N(C=1)C)=O',
      // options object
      // set the options here to control how the function performs,
      // these options are just placeholders to demonstrate
      {
        'option1' : value1,
        'option2' : value2
      },
      // callback function
      function(mol){
        // The function completed successfully and the returned
        // molecule is sent to the callback function.
        // Use the mol object to complete your function, here
        // we just alert the number of atoms and bonds.
        alert(mol.atoms.length+' '+mol.bonds.length);
      },
      // errorback function
      function(){
        // something went wrong, handle this case here
        alert('Something went wrong, please contact the webmaster.');
      }
    );
  </script>

The average Cloud function will take the input parameters (in this case, the SMILES string), the options object ({}), and two functions, the callback and errorback functions. When our server completes the work, a signal is sent back to the Cloud function to finish and forward the data to the callback function (in the above case, the generated Molecule) so you may make use of it. If something went wrong, the errorback function will be called instead so you can handle errors. The errorback function is optional, and nothing will happen on error if none is provided.

Static Parameters

There are two static parameters in the iChemLabs package, SERVER_URL and asynchronous.

The SERVER_URL parameter is a String and is the url defining the hosted location of the iChemLabs Cloud services. This value is already set and should never be changed unless you have licensed Cloud services for use on your own server to take advantage of XHR1 or another reason. You can change this url as follows:

1
2
3
  <script>
    ChemDoodle.iChemLabs.SERVER_URL = 'url goes here';
  </script>

You can also tell ChemDoodle to use HTTPS instead of HTTP for cloud services:

1
2
3
4
  <script>
    // force HTTPS, this is useful for certain browsers that do not allow HTTP calls to mix with HTTPS
    ChemDoodle.iChemLabs.useHTTPS();
  </script>

The asynchronous parameter is a boolean and determines whether Cloud calls are asynchronous or not. It is true by default and recommended to be true. However, if you wish to make Cloud calls sychronous (for inclusion in testing suites for instance), which will lock the browser while they complete, then set this parameter to false:

1
2
3
  <script>
    ChemDoodle.iChemLabs.asynchronous = false;
  </script>

API

ChemDoodle.iChemLabs

  • static String SERVER_URL: the url to call for iChemLabs Cloud services through AJAX
  • static Boolean asynchronous: this value will determine if calls to AJAX services are synchronous or not
    Default Value: true
    Unit: true/false
  • static Function calculate(Molecule mol, Object options, Function callback, Function errorback): calculates properties and descriptors for the provided Molecule
    Options:
    • Array descriptors: An array of Strings naming the descriptors to calculate for the input Molecule. If this option is not provided, or if this array is empty, then nothing is returned.

    Callback Handling:

    A named array of values is returned. Each value is associated with the name of the descriptor provided in the descriptors option.
    Descriptor    Code    Data Type
    Average Molecular Polarizability (Kang)    pol_kang    Number
    Average Molecular Polarizability (Miller)    pol_miller    Number
    Balaban Index    balaban    Number
    Bertz Molecular Complexity    bertz    Number
    Bioavailability Score    bioavailability    Number
    Branching Index    branching    Number
    Centric Index    centric    Number (Integer)
    Chi Molecular Connectivity Index    0X    Number
    Chi Molecular Connectivity Index    0Xv    Number
    Chi Molecular Connectivity Index    1X    Number
    Chi Molecular Connectivity Index    1Xv    Number
    Chi Molecular Connectivity Index    2X    Number
    Chi Molecular Connectivity Index    2Xv    Number
    Chi Molecular Connectivity Index    3X    Number
    Chi Molecular Connectivity Index    3Xv    Number
    Critical Pressure    Pc    Number
    Critical Temperature    Tc    Number
    Critical Volume    Vc    Number
    Degree of Unsaturation    deg_unsat    Number (Integer)
    Egan Violations Count    egan    Number (Integer)
    Empirical Formula    ef    String
    Enthalpy of Formation (ideal gas at 298K)    Hf298    Number
    Enthalpy of Fusion    Hf    Number
    Enthalpy of Vaporization (at Tb)    Hvb    Number
    Fraction Molecular Framework    fmf    Number
    Cyclomatic Number    cyclomatic    Number (Integer)
    Gibbs Energy of Formation (ideal gas, unit fugacity, at 298K)    G0f298    Number
    Heat Capacity (ideal gas, at 298K)    Cp0    Number
    Hosoya Index    hosoya    Number (Integer)
    Hydrogen Bond Acceptor Count    hba    Number (Integer)
    Hydrogen Bond Donor Count    hbd    Number (Integer)
    Kappa Shape Index    1K    Number
    Kappa Shape Index    1Ka    Number
    Kappa Shape Index    2K    Number
    Kappa Shape Index    2Ka    Number
    Kappa Shape Index    3K    Number
    Kappa Shape Index    3Ka    Number
    Lightest Isotopic Mass    liw    Number
    Lipinski’s Rule of 5 Violations Count    lipinski    Number (Integer)
    Lipophilicity, logP, AlogP98    alogp98    Number
    Lipophilicity, logP, NC + NHET    ncnhet    Number
    Lipophilicity, logP, XlogP v2.0    xlogp2    Number
    Liquid Viscosity (at 298K)    nl    Number
    McGowan Characteristic Volume    mcgowan    Number
    Molar Refractivity (AMR)    amr    Number
    Molar Refractivity (CMR)    cmr    Number
    Molecular Formula    mf    String
    Molecular Mass    mw    Number
    Molecular Topological Index    mti    Number (Integer)
    Monoisotopic Mass    miw    Number
    Normal Boiling Point    Tb    Number
    Normal Freezing Point    Tf    Number
    Platt Index    platt    Number (Integer)
    Ring Complexity    ring_complex    Number (Integer)
    Rotatable Bond Count    rot    Number (Integer)
    Superpendentic Index    super    Number
    Szeged Index    szeged    Number (Integer)
    Topological Diameter    diameter    Number (Integer)
    Topological Polar Surface Area    tpsa    Number
    Total Number of Electrons    electron    Number (Integer)
    Veber Violation Count    veber    Number (Integer)
    Volume as a Sum of Atomic and Bond Contributions    vabc    Number
    Weiner Index    weiner    Number (Integer)
    Zagreb Index    zagreb    Number (Integer)
  • static Function createLewisDot(Molecule mol, Object options, Function callback, Function errorback): creates a molecule that represents the input molecule as a Lewis Dot Structure; this function will use 90° angles and appropriately place lone pairs to satisfy the octet rule, charges will need to be present on the input molecule
    Options:
    none
    Callback Handling:
    A molecule data structure representing the input molecule as a Lewis Dot Structure.
  • static Function generateIUPACName(Molecule mol, Object options, Function callback, Function errorback): generates the IUPAC name for the input molecule
    Options:
    none
    Callback Handling:
    The IUPAC name of the molecule is returned as the parameter to the callback function.
  • static Function generateImage(Molecule mol, Object options, Function callback, Function errorback): generates an image file of the input Molecule in any of the chemical formats that ChemDoodle understands (specified by the ext parameter)
    Options:
    • String ext: The extension of the file format to write.
      Allowed Values: [any of the image file extensions that ChemDoodle desktop understands]
      Default Value: ‘pdf’

    Callback Handling:

    A url to the generated file on our server is sent as a parameter to the callback function.
  • static Function getMoleculeFromContent(String content, Object options, Function callback, Function errorback): generates a molecule data structure from the input content string, specifying the correct format of the content by the extension of its filetype
    Options:
    • String format: The extension of the file format this content is to be interpreted as.
      Allowed Values: [any of the file extensions that ChemDoodle desktop understands, if none is provided, ChemDoodle will attempt to guess the format, but it is recommended that you provide this option]

    Callback Handling:

    The Molecule generated from the input content is sent as a parameter to the callback function.
  • static Function getMoleculeFromDatabase(String query, Object options, Function callback, Function errorback): contacts one of our partner databases to retrieve a structure for the input query
    Options:
    • Number dimension: Either integer 2 or 3, defining the dimensionality of the coordinates of the structure data to retrieve.
      Default Value: 2
      Unit: dimension
    • String database: The database to search through.
      Allowed Values: ['chemexper', 'chemspider', 'pubchem']
      Default Value: ‘pubchem’

    Callback Handling:

    If the molecule is found, a Molecule data structure of the result is sent as a parameter to the callback function.
  • static Function getOptimizedPDBStructure(String id, Object options, Function callback, Function errorback): given an input PDB id, will return the atom, bond and ribbon data for the corresponding structure, if it exists; loading PDB files through this method is several magnitudes faster than by loading and parsing the data from a variable in Javascript
    Options:
    • Boolean withAtoms: If this option is false, atoms and bonds will not be returned, only ribbon data will be returned; this is useful if you want to speed up loading and rendering.
      Default Value: false

    Callback Handling:

    If the PDB data is found, a Molecule data structure of the result is sent as a parameter to the callback function.
  • static Function getSimilarityMeasure(Molecule first, Molecule second, Object options, Function callback, Function errorback): this function will compare two molecules, with a number value representing their similarity measure being returned as a parameter to the callback function; similarity is determined by useing a Dice similarity coefficient to equate two fingerprints generated for each of the input molecules using iChemLabs’ path fingerprint algorithm
    Options:
    none
    Callback Handling:
    The callback function recieves a number value calculated as the similarity measure.
  • static Function getZeoliteFromIZA(String iza, Object options, Function callback, Function errorback): given an IZA code, a Molecule data structure will be generated for the zeolite data, if it exists
    Options:
    • Number xSuper: The supercell dimension along the X axis.
      Default Value: 1
      Unit: cell dimension
    • Number ySuper: The supercell dimension along the Y axis.
      Default Value: 1
      Unit: cell dimension
    • Number zSuper: The supercell dimension along the Z axis.
      Default Value: 1
      Unit: cell dimension

    Callback Handling:

    If the IZA code is found, a Molecule data structure of the result is sent as a parameter to the callback function.
  • static Function isGraphIsomorphism(Molecule arrow, Molecule target, Object options, Function callback, Function errorback): this function will determine if the arrow molecule (which may be a query molecule) is a graph isomorphism of the target molecule, with the boolean value being returned as a parameter to the callback function
    Options:
    none
    Callback Handling:
    The callback function recieves a boolean parameter defining the result of the match.
  • static Function isSubgraphIsomorphism(Molecule arrow, Molecule target, Object options, Function callback, Function errorback): this function will determine if the arrow molecule (which may be a query molecule) is a subgraph isomorphism of the target molecule, with the boolean value being returned as a parameter to the callback function
    Options:
    none
    Callback Handling:
    The callback function recieves a boolean parameter defining the result of the match.
  • static Function isSupergraphIsomorphism(Molecule arrow, Molecule target, Object options, Function callback, Function errorback): this function will determine if the arrow molecule (which may be a query molecule) is a supergraph isomorphism of the target molecule, with the boolean value being returned as a parameter to the callback function
    Options:
    none
    Callback Handling:
    The callback function recieves a boolean parameter defining the result of the match.
  • static Function kekulize(Molecule mol, Object options, Function callback, Function errorback): provided with an input Molecule, this function will kekulize either the entire single bond system, or just the resonance bonds into a valid kekule structure where pi delocalization is maximized
    Options:
    none
    Callback Handling:
    A kekulized copy of the structure will be returned as a parameter to the callback function.
  • static Function optimize(Molecule mol, Object options, Function callback, Function errorback): optimizes the input Molecule’s coordinates given a dimension (2 or 3)
    Options:
    • Number dimension: Either integer 2 or 3, defining the dimensionality of the coordinates to optimize.
      Default Value: 2
      Unit: dimension

    Callback Handling:

    If the dimension is 2, then nothing is sent to the callback function, the coordinates of the input molecule are updated accordingly when the callback function is executed; if the dimension is 3, a new Molecule object is sent as a parameter to the callback function.
  • static Function readIUPACName(String iupac, Object options, Function callback, Function errorback): generates a Molecule given an IUPAC name
    Options:
    none
    Callback Handling:
    The Molecule generated from the input IUPAC name is sent as a parameter to the callback function.
  • static Function readSMILES(String smiles, Object options, Function callback, Function errorback): parses the input SMILES string and produces the corresponding Molecule
    Options:
    none
    Callback Handling:
    The Molecule generated from the SMILES string is sent as a parameter to the callback function.
  • static Function saveFile(Molecule mol, Object options, Function callback, Function errorback): saves the input Molecule in any of the chemical formats that ChemDoodle understands (specified by the ext option)
    Options:
    • String ext: The extension of the file format to write.
      Allowed Values: [any of the chemical file extensions that ChemDoodle desktop understands]
      Default Value: ‘icl’

    Callback Handling:

    A url to the generated file on our server is sent as a parameter to the callback function.
  • static Function simulate13CNMR(Molecule mol, Object options, Function callback, Function errorback): simulates the 13C NMR spectrum for the input molecule, the resulting Spectrum object is sent to the callback function
    Options:
    none
    Callback Handling:
    The Spectrum generated from the input Molecule is sent as a parameter to the callback function.
  • static Function simulate1HNMR(Molecule mol, Object options, Function callback, Function errorback): simulates the 1H NMR spectrum for the input molecule, the resulting Spectrum object is sent to the callback function
    Options:
    none
    Callback Handling:
    The Spectrum generated from the input Molecule is sent as a parameter to the callback function.
  • static Function simulateMassParentPeak(Molecule mol, Object options, Function callback, Function errorback): simulates the parent peak in a mass spectrum for the input molecule (isotopic distribution)
    Options:
    none
    Callback Handling:
    The Spectrum generated from the input Molecule is sent as a parameter to the callback function.
  • static Function version(): a method to determine the version information from the server currently being queried
    Options:
    none
    Callback Handling:
    A string is returned containing version information.
  • static Function writeSMILES(Molecule mol, Object options, Function callback, Function errorback): generates the SMILES string for the input Molecule
    Options:
    none
    Callback Handling:
    The generated SMILES string is sent as a parameter to the callback function.
  • static abstract Function _contactServer(String call, Object content, Object options, Function callback, Function errorback): the core function for contacting our server; this function takes parameters specific to our server protocol, is able to communicate the protocol and then returns the appropriate response to the callback function; this should never be manually called, use the other functions in this package instead; the errorback function is optional, and if provided and any error occurs, the errorback function will be called