Documents > 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 contact us for 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:

  <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(content){
	      // The function completed successfully and the returned
	      // content is sent to the callback function.
	      // Use the content object to complete your function, here
	      // we just alert the number of atoms and bonds for the first molecule.
	      alert(content.molecules[0].atoms.length+' '+content.molecules[0].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 is one static parameter in the iChemLabs package, SERVER_URL.

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:

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

API

ChemDoodle.iChemLabs

• static String SERVER_URL: the url to call for iChemLabs Cloud services through AJAX
• static Function balanceEquation(Object toBeBalanced, Object options, Function callback, Function errorback): balances the input chemical reaction equation, either from drawn reaction data or a typed reaction equation. If the Object toBeBalanced is a String, ChemDoodle will balance the typed equation, otherwise ChemDoodle will assume it is drawn reaction data.
  Options:
  none
  Callback Handling:
  The callback receives 2 parameters: (1) the first is the balanced equation as a formatted HTML String (it will be undefined if the reaction could not be balanced, and (2) a message describing any warnings or errors associated with the function.
• 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 cir(FormData formData, Object options, Function callback, Function errorback): this function recovers a chemical drawing from an image. This is the ChemDoodle Chemical Image Recovery (CIR) function. Others may refer to this function as Optical Structure Recognition (OSR). The FormData object must be appended with the File selected by the user named as "file". A maximum file size of 1MB is allowed.
  Options:
  • Boolean preview: If set to true, an image of the raw interpretation will be sent back as a second parameter to the callback function. The preview parameter will have 3 sub-parameters: imgsrc, width and height. The imgsrc parameter is a String representing the image as formatted Base64 source to be used as the content for the "src" attribute of an "img" element. The width parameter is the image width in pixels as an integer. The height parameter is the image height in pixels as an integer.
    Default Value: false
  
  Callback Handling:
  The callback function recieves 1 parameter by default. This parameter is an object with attributes of molecules (Array of Molecule) and shapes (Array of Shape) data structures generated from the CIR algorithm; the content may be empty.
• 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 elementalAnalysis(Molecule mol, Object options, Function callback, Function errorback): performs elemental analysis on the input molecule, returning a number of results
  Options:
  none
  Callback Handling:
  One parameter is returned to the callback function, an object containing all of the elemental analysis calculations. From the object, you may access molecular_formula providing the molecular formula in HTML format, molecular_mass provides the value for molecular mass in amu, monoisotopic_mass provides the value for monoisotopic mass in amu, composition provides the elemental analysis composition breakdown, peaks provides the isotopic distribution breakdown, and jcamp is a JCAMP file for the isotopic distribution spectrum. If an error occurs, and the only real reason this would happen is if the user inputs an isotope value where there is no natural abundance on earth, a error parameter will be provided with a String description of the problem. In the case of an error, the molecular_formula variable will likely still be provided, but the other parameters will all be undefined.
• static Function fileToImage(FormData formData, Object options, Function callback, Function errorback): this function converts a chemistry file provided by the user using a file input element into an image. The FormData object must be appended with the File selected by the user named as "file". A maximum file size of 1MB is allowed.
  Options:
  none
  Callback Handling:
  The callback function recieves 3 parameters. The first is a String representing the image as formatted Base64 source to be used as the content for the "src" attribute of an "img" element. The second is the image width in pixels as an integer. The third is the image height in pixels as an integer.
• static Function generateIUPACName(Molecule mol, Object options, Function callback, Function errorback): generates IUPAC names for the input molecule, both the traditional name and an attempted PIN
  Options:
  none
  Callback Handling:
  Two parameters are returned to the to the callback function. The first is a String expressing the traditional IUPAC name. The second is a String expressing the attempted PIN.
• 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 2D 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 2D 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 maximumCommonSubstructure(Molecule m1, Molecule m2, Object options, Function callback, Function errorback): this function will find the maximum common substructure (MCS) for the two input molecular structures
  Options:
  • Boolean disconnected: If this option is true, the MCS algorithm will return a disconnected maximum common substructure. By default, a connected maximum substructure is returned.
    Default Value: false
  
  Callback Handling:
  The callback function recieves an object which defines the MCS mapping, where the property names of the object are indexes (Integers as Strings) for m1 and the values for those property names are the corresponding mapped indexes (Integers as Strings) for m2.
• static Function mechanismMatch(Molecule arrow, Array targets, Object options, Function callback, Function errorback): this function will match mechanistic drawings, ensuring that pusher arrows are drawn from the correct objects and in the correct direction for any number of molecules; any number of targets may be sent in to be matched; an array of integer values will be returned as a parameter to the callback function, 0 means no match, 1 means exact match, and 2 means partial match
  Options:
  • Boolean enforceStereo: If this option is true, the mechanism matching algorithm will enforce stereochemistry while matching. By default, stereocenters are not important.
    Default Value: false
  
  Callback Handling:
  The callback function recieves an array of integers with length equal to that of the array of molecules sent in as targets parameter, 0 means no match, 1 means exact match, and 2 means partial match.
• 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:
  An array of Molecule data structures generated from the input IUPAC name is sent as the first parameter to the callback function; the array may be empty. The second parameter is any warning (as a String) associated with the parsing of the IUPAC name, which may be undefined.
• static Function readSMILES(String smiles, Object options, Function callback, Function errorback): parses the input SMILES string and produces the corresponding Molecule(s) and Shape (a reaction arrow may be created) objects
  Options:
  • Number generate_coordinates: The dimension of the coordinates to generate for the structures. A dimension of 0 will instruct the call not to generate coordinates.
    Default Value: 2
  • Boolean kekulize: SMILES with aromatic models enforced will be input using resonance bonds. Setting this option to true will Kekulize those resonance systems.
    Default Value: false
    Unit: true/false
  • Boolean infer_ambiguous_double_bonds: If this option is true, double bonds that do not have stereochemistry defined in the SMILES string will be represented with an ambiguous double bond type.
    Default Value: false
    Unit: true/false
  
  Callback Handling:
  An object with attributes of the molecules (Array of Molecule) and shapes (Array of Shape) generated is sent as a parameter to the callback function.
• static Function readWLN(String wln, Object options, Function callback, Function errorback): parses the input WLN string and produces the corresponding content of molecules and associated shapes
  Options:
  none
  Callback Handling:
  An object with attributes of molecules (Array of Molecule) and shapes (Array of Shape) data structures generated from the input WLN string is sent as the first parameter to the callback function; the content may be empty.
• static Function resolveCIP(Molecule mol, Object options, Function callback, Function errorback): resolves atom and bond stereocenters using CIP rules for the input Molecule
  Options:
  none
  Callback Handling:
  The callback receives 2 parameters, which are both arrays. The first is the CIP configuration tags for atoms and the second is the CIP configuration tags for bonds. The ordering is identical to the atom and bond ordering of the input molecule. If an atom or bond is not a stereocenter, the corresponding result in the array will be an empty String.
• 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 2D 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 ¹³C 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 ¹H 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 stoichiometry(Object providedInformation, Object options, Function callback, Function errorback): this function handles the stoichometry table calculations and should not be called directly, as the Stoichiometry class provides a developer API; when initializing the table, the providedInformation object can be either a String or a drawn reaction, if the table is already initialized and requires updating, providedInformation is the current table structure
  Options:
  none
  Callback Handling:
  The callback function recieves an object with the current calculation values as a table data structure (this table should be updated and sent back to this function for further updates). There is a also a second parameter returned named message, with optional information about the stoichiometry table, which may be undefined.
• 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(Array molecules, Array shapes, Object options, Function callback, Function errorback): generates the SMILES string for the input molecules (of Molecule data structures) and shapes (of Shape data structures). A single reaction arrow is allowed to be sent in the shapes array, but an empty array should be sent if there is no reaction arrow.
  Options:
  • Boolean aromaticity: If true, SMILES output will have the SMILES aromaticity model enforced (lower case letters).
    Default Value: false
    Unit: true/false
  • Boolean include_all_explicit_hydrogens: If true, explicitly drawn hydrogen atoms will be output as explicit atoms in the SMILES string.
    Default Value: false
    Unit: true/false
  • Boolean stereochemistry: If true, stereochemistry will be output into the SMILES string.
    Default Value: true
    Unit: true/false
  • Boolean include_implied_double_bond_stereo: Some double bond stereo characters can be implied and are not necessary, shortening the SMILES string. If true, these implied characters will be included in the string.
    Default Value: false
    Unit: true/false
  
  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