Class DescriptorEngine
- 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:
- main
- Belongs to CDK module:
- qsarmolecular
- Created on:
- 2004-12-02
-
-
Constructor Summary
Constructors Constructor 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 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(String identifier)
Returns the class(es) of the decsriptor as defined in the descriptor dictionary.String[]
getDictionaryClass(IImplementationSpecification descriptorSpecification)
Returns the class(es) of the descriptor as defined in the descriptor dictionary.String
getDictionaryDefinition(String identifier)
Gets the definition of the descriptor.String
getDictionaryDefinition(DescriptorSpecification descriptorSpecification)
Gets the definition of the descriptor.String
getDictionaryTitle(String identifier)
Gets the label (title) of the descriptor.String
getDictionaryTitle(DescriptorSpecification descriptorSpecification)
Gets the label (title) of the descriptor.String
getDictionaryType(String identifier)
Returns the type of the descriptor as defined in the descriptor dictionary.String
getDictionaryType(IImplementationSpecification descriptorSpecification)
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 ofDescriptor
objects.void
setDescriptorSpecifications(List<IImplementationSpecification> specs)
Set the list ofDescriptorSpecification
objects.
-
-
-
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 theprocess()
method will fail. To use the engine via this constructor you should use the following codeList 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 inMETA-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 aDescriptorValue
object which is then added to the molecule as a property keyed on theDescriptorSpecification
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 theDescriptorValue
objects can be obtained from a molecules property list
-
setDescriptorSpecifications
public void setDescriptorSpecifications(List<IImplementationSpecification> specs)
Set the list ofDescriptorSpecification
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 ofDescriptor
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 implementjarFileNames
- 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 descriptorjarFileNames
- 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)
-
-