DescriptorEngine (cdk 2.2 API)

java.lang.Object
- org.openscience.cdk.qsar.DescriptorEngine

```
public class DescriptorEngine
extends Object
```
A class that provides access to automatic descriptor calculation and more.
The aim of this class is to provide an easy to use interface to automatically evaluate all the CDK descriptors for a given molecule. Note that at a given time this class will evaluate all atomic or molecular descriptors but not both.
The available descriptors are determined by scanning all the jar files in the users CLASSPATH and selecting classes that belong to the CDK QSAR atomic or molecular descriptors package.
An example of its usage would be
```
 Molecule someMolecule;
 ...
 DescriptorEngine descriptoEngine = new DescriptorEngine(DescriptorEngine.MOLECULAR, null);
 descriptorEngine.process(someMolecule);
 
```
The class allows the user to obtain a List of all the available descriptors in terms of their Java class names as well as instances of each descriptor class. For each descriptor, it is possible to obtain its classification as described in the CDK descriptor-algorithms OWL dictionary.
See Also:

DescriptorSpecification, Dictionary, OWLFile

Source code:
master

Belongs to CDK module:
qsarmolecular

Created on:

2004-12-02

Constructor Summary

Constructors
Constructor and Description
`DescriptorEngine(Class<? extends IDescriptor> c, IChemObjectBuilder builder)` Create a descriptor engine for all descriptor types.
`DescriptorEngine(List<String> classNames, IChemObjectBuilder builder)` Instantiates the DescriptorEngine.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`String[]`	`getAvailableDictionaryClasses()` Get the all the unique dictionary classes that the descriptors belong to.
`static List<String>`	`getDescriptorClassNameByInterface(String interfaceName, String[] jarFileNames)` Returns a list containing the classes that implement a specific interface.
`static List<String>`	`getDescriptorClassNameByPackage(String packageName, String[] jarFileNames)` Returns a list containing the classes found in the specified descriptor package.
`List<String>`	`getDescriptorClassNames()` Returns a list containing the names of the classes implementing the descriptors.
`List<IDescriptor>`	`getDescriptorInstances()` Returns a List containing the instantiated descriptor classes.
`List<IImplementationSpecification>`	`getDescriptorSpecifications()` Returns the DescriptorSpecification objects for all available descriptors.
`String[]`	`getDictionaryClass(IImplementationSpecification descriptorSpecification)` Returns the class(es) of the descriptor as defined in the descriptor dictionary.
`String[]`	`getDictionaryClass(String identifier)` Returns the class(es) of the decsriptor as defined in the descriptor dictionary.
`String`	`getDictionaryDefinition(DescriptorSpecification descriptorSpecification)` Gets the definition of the descriptor.
`String`	`getDictionaryDefinition(String identifier)` Gets the definition of the descriptor.
`String`	`getDictionaryTitle(DescriptorSpecification descriptorSpecification)` Gets the label (title) of the descriptor.
`String`	`getDictionaryTitle(String identifier)` Gets the label (title) of the descriptor.
`String`	`getDictionaryType(IImplementationSpecification descriptorSpecification)` Returns the type of the descriptor as defined in the descriptor dictionary.
`String`	`getDictionaryType(String identifier)` Returns the type of the descriptor as defined in the descriptor dictionary.
`List<IImplementationSpecification>`	`initializeSpecifications(List<IDescriptor> descriptors)`
`List<IDescriptor>`	`instantiateDescriptors(List<String> descriptorClassNames)`
`void`	`process(IAtomContainer molecule)` Calculates all available (or only those specified) descriptors for a molecule.
`void`	`setDescriptorInstances(List<IDescriptor> descriptors)` Set the list of `Descriptor` objects.
`void`	`setDescriptorSpecifications(List<IImplementationSpecification> specs)` Set the list of `DescriptorSpecification` objects.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - DescriptorEngine
```
public DescriptorEngine(List<String> classNames,
                        IChemObjectBuilder builder)
```
    Instantiates the DescriptorEngine. This constructor instantiates the engine but does not perform any initialization. As a result calling the process() method will fail. To use the engine via this constructor you should use the following code
```
 List classNames = DescriptorEngine.getDescriptorClassNameByPackage("org.openscience.cdk.qsar.descriptors.molecular",
                                                          null);
 DescriptorEngine engine = DescriptorEngine(classNames);
 
 List instances =  engine.instantiateDescriptors(classNames);
 List specs = engine.initializeSpecifications(instances)
 engine.setDescriptorInstances(instances);
 engine.setDescriptorSpecifications(specs);
 
 engine.process(someAtomContainer);
 
```
    This approach allows one to use find classes using the interface based approach (getDescriptorClassNameByInterface(String, String[]). If you use this method it is preferable to specify the jar files to examine
  - DescriptorEngine
```
public DescriptorEngine(Class<? extends IDescriptor> c,
                        IChemObjectBuilder builder)
```
    Create a descriptor engine for all descriptor types. Descriptors are loaded using the service provider mechanism. To include custom descriptors one should declare in META-INF/services a file named as the interface you are providing (e.g. org.openscience.cdk.qsar.IMolecularDescriptor). This file declares the implementations provided by the jar as class names.
    
    Parameters:
    
    c - class of the descriptor to use (e.g. IMolecularDescriptor.class)
    
    See Also:
    
    Service Provider Interface (SPI) Introduction
- Method Detail
  - process
```
public void process(IAtomContainer molecule)
             throws CDKException
```
    Calculates all available (or only those specified) descriptors for a molecule. The results for a given descriptor as well as associated parameters and specifications are used to create a DescriptorValue object which is then added to the molecule as a property keyed on the DescriptorSpecification object for that descriptor
    
    Parameters:
    
    molecule - The molecule for which we want to calculate descriptors
    
    Throws:
    
    CDKException - if an error occurred during descriptor calculation or the descriptors and/or specifications have not been initialized
  - getDictionaryType
```
public String getDictionaryType(String identifier)
```
    Returns the type of the descriptor as defined in the descriptor dictionary. The method will look for the identifier specified by the user in the QSAR descriptor dictionary. If a corresponding entry is found, first child element that is called "isClassifiedAs" is returned. Note that the OWL descriptor spec allows both the class of descriptor (electronic, topological etc) as well as the type of descriptor (molecular, atomic) to be specified in an "isClassifiedAs" element. Thus we ignore any such element that indicates the descriptors class. The method assumes that any descriptor entry will have only one "isClassifiedAs" entry describing the descriptors type. The descriptor can be identified either by the name of the class implementing the descriptor or else the specification reference value of the descriptor which can be obtained from an instance of the descriptor class.
    
    Parameters:
    
    identifier - A String containing either the descriptors fully qualified class name or else the descriptors specification reference
    
    Returns:
    
    The type of the descriptor as stored in the dictionary, null if no entry is found matching the supplied identifier
  - getDictionaryType
```
public String getDictionaryType(IImplementationSpecification descriptorSpecification)
```
    Returns the type of the descriptor as defined in the descriptor dictionary. The method will look for the identifier specified by the user in the QSAR descriptor dictionary. If a corresponding entry is found, first child element that is called "isClassifiedAs" is returned. Note that the OWL descriptor spec allows both the class of descriptor (electronic, topological etc) as well as the type of descriptor (molecular, atomic) to be specified in an "isClassifiedAs" element. Thus we ignore any such element that indicates the descriptors class. The method assumes that any descriptor entry will have only one "isClassifiedAs" entry describing the descriptors type. The descriptor can be identified it DescriptorSpecification object
    
    Parameters:
    
    descriptorSpecification - A DescriptorSpecification object
    
    Returns:
    
    he type of the descriptor as stored in the dictionary, null if no entry is found matching the supplied identifier
  - getDictionaryClass
```
public String[] getDictionaryClass(String identifier)
```
    Returns the class(es) of the decsriptor as defined in the descriptor dictionary. The method will look for the identifier specified by the user in the QSAR descriptor dictionary. If a corresponding entry is found, the meta-data list is examined to look for a dictRef attribute that contains a descriptorClass value. if such an attribute is found, the value of the contents attribute add to a list. Since a descriptor may be classed in multiple ways (geometric and electronic for example), in general, a given descriptor will have multiple classes associated with it. The descriptor can be identified either by the name of the class implementing the descriptor or else the specification reference value of the descriptor which can be obtained from an instance of the descriptor class.
    
    Parameters:
    
    identifier - A String containing either the descriptors fully qualified class name or else the descriptors specification reference
    
    Returns:
    
    A List containing the names of the QSAR descriptor classes that this descriptor was declared to belong to. If an entry for the specified identifier was not found, null is returned.
  - getDictionaryClass
```
public String[] getDictionaryClass(IImplementationSpecification descriptorSpecification)
```
    Returns the class(es) of the descriptor as defined in the descriptor dictionary. The method will look for the identifier specified by the user in the QSAR descriptor dictionary. If a corresponding entry is found, the meta-data list is examined to look for a dictRef attribute that contains a descriptorClass value. if such an attribute is found, the value of the contents attribute add to a list. Since a descriptor may be classed in multiple ways (geometric and electronic for example), in general, a given descriptor will have multiple classes associated with it. The descriptor can be identified by its DescriptorSpecification object.
    
    Parameters:
    
    descriptorSpecification - A DescriptorSpecification object
    
    Returns:
    
    A List containing the names of the QSAR descriptor classes that this descriptor was declared to belong to. If an entry for the specified identifier was not found, null is returned.
  - getDictionaryDefinition
```
public String getDictionaryDefinition(String identifier)
```
    Gets the definition of the descriptor. All descriptors in the descriptor dictioanry will have a definition element. This function returns the value of that element. Many descriptors also have a description element which is more detailed. However the value of these elements can contain arbitrary mark up (such as MathML) and I'm not sure what I should return it as
    
    Parameters:
    
    identifier - A String containing either the descriptors fully qualified class name or else the descriptors specification reference
    
    Returns:
    
    The definition
  - getDictionaryDefinition
```
public String getDictionaryDefinition(DescriptorSpecification descriptorSpecification)
```
    Gets the definition of the descriptor. All descriptors in the descriptor dictioanry will have a definition element. This function returns the value of that element. Many descriptors also have a description element which is more detailed. However the value of these elements can contain arbitrary mark up (such as MathML) and I'm not sure what I should return it as
    
    Parameters:
    
    descriptorSpecification - A DescriptorSpecification object
    
    Returns:
    
    The definition
  - getDictionaryTitle
```
public String getDictionaryTitle(String identifier)
```
    Gets the label (title) of the descriptor.
    
    Parameters:
    
    identifier - A String containing either the descriptors fully qualified class name or else the descriptors specification reference
    
    Returns:
    
    The title
  - getDictionaryTitle
```
public String getDictionaryTitle(DescriptorSpecification descriptorSpecification)
```
    Gets the label (title) of the descriptor.
    
    Parameters:
    
    descriptorSpecification - The specification object
    
    Returns:
    
    The title
  - getDescriptorSpecifications
```
public List<IImplementationSpecification> getDescriptorSpecifications()
```
    Returns the DescriptorSpecification objects for all available descriptors.
    
    Returns:
    
    An array of DescriptorSpecification objects. These are the keys with which the DescriptorValue objects can be obtained from a molecules property list
  - setDescriptorSpecifications
```
public void setDescriptorSpecifications(List<IImplementationSpecification> specs)
```
    Set the list of DescriptorSpecification objects.
    
    Parameters:
    
    specs - A list of specification objects
    
    See Also:
    
    getDescriptorSpecifications()
  - getDescriptorClassNames
```
public List<String> getDescriptorClassNames()
```
    Returns a list containing the names of the classes implementing the descriptors.
    
    Returns:
    
    A list of class names.
  - getDescriptorInstances
```
public List<IDescriptor> getDescriptorInstances()
```
    Returns a List containing the instantiated descriptor classes.
    
    Returns:
    
    A List containing descriptor classes
  - setDescriptorInstances
```
public void setDescriptorInstances(List<IDescriptor> descriptors)
```
    Set the list of Descriptor objects.
    
    Parameters:
    
    descriptors - A List of descriptor objects
    
    See Also:
    
    getDescriptorInstances()
  - getAvailableDictionaryClasses
```
public String[] getAvailableDictionaryClasses()
```
    Get the all the unique dictionary classes that the descriptors belong to.
    
    Returns:
    
    An array containing the unique dictionary classes.
  - getDescriptorClassNameByInterface
```
public static List<String> getDescriptorClassNameByInterface(String interfaceName,
                                                             String[] jarFileNames)
```
    Returns a list containing the classes that implement a specific interface. The interface name specified can be null or an empty string. In this case the interface name is automatcally set to IDescriptor. Specifying IDescriptor will return all available descriptor classes. Valid interface names are
    - IMolecularDescriptor
    - IAtomicDescripto
    - IBondDescriptor
    - IDescriptor
    Parameters:
    
    interfaceName - The name of the interface that classes should implement
    
    jarFileNames - A String[] containing the fully qualified names of the jar files to examine for descriptor classes. In general this can be set to NULL, in which case the system classpath is examined for available jar files. This parameter can be set for situations where the system classpath is not available or is modified such as in an application container.
    
    Returns:
    
    A list containing the classes implementing the specified interface, null if an invalid interface is specified
  - getDescriptorClassNameByPackage
```
public static List<String> getDescriptorClassNameByPackage(String packageName,
                                                           String[] jarFileNames)
```
    Returns a list containing the classes found in the specified descriptor package. The package name specified can be null or an empty string. In this case the package name is automatcally set to "org.openscience.cdk.qsar.descriptors" and as a result will return classes corresponding to both atomic and molecular descriptors.
    
    Parameters:
    
    packageName - The name of the package containing the required descriptor
    
    jarFileNames - A String[] containing the fully qualified names of the jar files to examine for descriptor classes. In general this can be set to NULL, in which case the system classpath is examined for available jar files. This parameter can be set for situations where the system classpath is not available or is modified such as in an application container.
    
    Returns:
    
    A list containing the classes in the specified package
  - instantiateDescriptors
```
public List<IDescriptor> instantiateDescriptors(List<String> descriptorClassNames)
```
  - initializeSpecifications
```
public List<IImplementationSpecification> initializeSpecifications(List<IDescriptor> descriptors)
```

Class DescriptorEngine

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DescriptorEngine

DescriptorEngine

Method Detail

process

getDictionaryType

getDictionaryType

getDictionaryClass

getDictionaryClass

getDictionaryDefinition

getDictionaryDefinition

getDictionaryTitle

getDictionaryTitle

getDescriptorSpecifications

setDescriptorSpecifications

getDescriptorClassNames

getDescriptorInstances

setDescriptorInstances

getAvailableDictionaryClasses

getDescriptorClassNameByInterface

getDescriptorClassNameByPackage

instantiateDescriptors

initializeSpecifications