Package chemaxon.standardizer
Class Standardizer
- java.lang.Object
-
- chemaxon.standardizer.Standardizer
-
@PublicAPI public class Standardizer extends Object
Performs the standardization determined by the XML configuration file, or simple action string configuration.
See the documentation for details:API usage examples:
- A simple example:
Standardizer standardizer = new Standardizer(new File("standardize.xml")); standardizer.standardize(molecule);
- A more complex example with importing molecules, standardization with a
final clean action to arrange changed atoms, storing standardization
information in molecule properties and finally exporting the molecules in SDF
format:
// create Standardizer based on a XML configuration file Standardizer standardizer = new Standardizer(new File("config.xml")); try { Molecule molecule = null; MolExporter exporter = new MolExporter(System.out, "sdf"); MolImporter importer = new MolImporter("mols.sdf"); while ((molecule = importer.read()) != null) { // standardize molecule standardizer.standardize(molecule); // get applied task indexes int[] appliedTaskIndexes = standardizer.getAppliedTaskIndexes(); // get applied task IDs String[] appliedTaskIdentifiers = standardizer.getAppliedTaskIDs(); // store applied task indexes and IDs in molecule properties StringBuilder indexPropertyValue = new StringBuilder(); for (int i = 0; i < appliedTaskIndexes.length; ++i) { indexPropertyValue.append(appliedTaskIndexes[i]); indexPropertyValue.append(" "); } StringBuilder identifierPropertyValue = new StringBuilder(); for (int i = 0; i < appliedTaskIdentifiers.length; ++i) { identifierPropertyValue.append(appliedTaskIdentifiers[i]); identifierPropertyValue.append(" "); } molecule.setProperty("TASK_INDEXES", indexPropertyValue.toString()); molecule.setProperty("TASK_IDS", identifierPropertyValue.toString()); // write output exporter.write(molecule); } importer.close(); exporter.close(); } catch (LicenseException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); }
Defines a sequence of standardizer actions, that should be executed, seeStandardizerConfiguration
Configuration error
If the provided configuration contains errors, thestandardize(Molecule)
method throwsIllegalArgumentException
by default. When the methodsetIgnoreConfigurationErrors(boolean)
is called with true value beforehand, faulty actions are not executed, error message or exception should not occur!
If errors of configuration needs to be checked, use thegetConfiguration()
method to get the configuration, and check the validity of the configuration by using the functionStandardizerConfiguration.isValid()
.
Standardizer actions
All built-in standardizer actions can be used with theStandardizer
. To use external standardizer actions, the XML factory-configuration file userdefinedstandardizers.xml should be placed at the $HOME/chemaxon folder containing the list of user-defined checkers. For more information seeStandardizerActionFactory
Built-in standardizer actions
Built in standardizer actions are located in the packages chemaxon.standardizer.actions and chemaxon.standardizer.advancedactions
Concurrent usage
Standardizer works on a single thread. If there are more target molecules, we advise to create more Standardizer instances (by cloning an existing one), and processing the molecules concurrently. For more information seeConcurrentStandardizerProcessor
Logging
Logs are generated to aLogger
, that can be collected by usingStandardizerLogger.getLogger()
method. As for now, onlyLevel.WARNING
andLevel.SEVERE
logs are generated.- Since:
- 5.11
- See Also:
ConcurrentStandardizerProcessor
- A simple example:
-
-
Field Summary
Fields Modifier and Type Field Description static String
FINAL_CLEAN_ID
Deprecated.
-
Constructor Summary
Constructors Constructor Description Standardizer(StandardizerConfiguration configuration)
Initializes a new standardizer with XML configurationStandardizer(Standardizer standardizer)
Initializes a new standardizer based on an existing standardizerStandardizer(File file)
Initializes a new standardizer with XML configurationStandardizer(InputStream stream)
Initializes a new standardizer with XML configurationStandardizer(String configuration)
Initializes a new standardizer with auto-recognized XML or action string configurationStandardizer(String configuration, String path)
Initializes a new standardizer with auto-recognized XML or action string configuration
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description String[]
getActiveGroups()
Deprecated.useConfigurationUtility.filterGroups(StandardizerConfiguration, String[])
on the configuration returned by the methodgetConfiguration()
String[]
getAppliedTaskIDs()
Returns the IDs of tasks applied to the last input molecule.int[]
getAppliedTaskIndexes()
Returns the indexes of tasks applied to the last input molecule.StandardizerConfiguration
getConfiguration()
Gets the configuration of the standardizer.String
getLicenseEnvironment()
Gets the license environment of the standardizerint[]
getNewToOld()
Returns the new -> old atom index mapping.int[]
getOldToNew()
Returns the old -> new atom index mapping.boolean
isLicensed()
Gets whether the standardizer is licensedboolean
isStereoFix()
Gets whether last stereo fix should be appliedvoid
setActiveGroups(String[] groups)
Deprecated.useConfigurationUtility.filterGroups(StandardizerConfiguration, String[])
on the configuration returned by the methodgetConfiguration()
void
setFinalClean()
Deprecated.useConfigurationUtility.setFinalClean(StandardizerConfiguration)
on the configuration returned by the methodgetConfiguration()
void
setFinalClean(int dim)
Deprecated.useConfigurationUtility.setFinalClean(StandardizerConfiguration, int)
on the configuration returned by the methodgetConfiguration()
void
setFinalClean(int dim, boolean partial)
Deprecated.useConfigurationUtility.setFinalClean(StandardizerConfiguration, int, boolean)
on the configuration returned by the methodgetConfiguration()
void
setFinalStereoFix(boolean clean)
Sets to perform final stereo fixes.void
setIgnoreConfigurationErrors(boolean ignore)
Sets whether the configuration errors should be ignored by the standardization process.
When configuration errors are ignored, invalid standardizer actions in the configuration are not executed, however all valid actions are to be executed.
When configuration errors are not ignored,IllegalArgumentException
thrown whenstandardize(Molecule)
method is called on an invalid configuration.void
setLicenseEnvironment(String env)
Sets the license environment.List<Changes>
standardize(Molecule mol)
Standardization for one input molecule: performs the standardization actions according to the XML configuration.
-
-
-
Field Detail
-
FINAL_CLEAN_ID
@Deprecated public static final String FINAL_CLEAN_ID
Deprecated.Final clean task ID.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Standardizer
public Standardizer(String configuration) throws IllegalArgumentException
Initializes a new standardizer with auto-recognized XML or action string configurationConfigurations containing references to molecule files does not work this way! If you have configurations containing references to external files, use the constructors that provide information on the path ( e.g.
Standardizer(File)
orStandardizer(String, String)
- Parameters:
configuration
- the configuration defined by action string or XML- Throws:
IllegalArgumentException
- on invalid configuration
-
Standardizer
public Standardizer(String configuration, String path) throws IllegalArgumentException
Initializes a new standardizer with auto-recognized XML or action string configuration- Parameters:
configuration
- the configuration defined by action string or XMLpath
- the root path of referenced contents in the configuration- Throws:
IllegalArgumentException
- on invalid configuration
-
Standardizer
public Standardizer(File file) throws IllegalArgumentException
Initializes a new standardizer with XML configuration- Parameters:
file
- the configuration XML input file- Throws:
IllegalArgumentException
- on invalid configuration
-
Standardizer
public Standardizer(InputStream stream) throws IllegalArgumentException
Initializes a new standardizer with XML configurationConfigurations containing references to molecule files does not work this way! If you may have configurations containing references, use the constructors that provide information on the path ( e.g.
Standardizer(File)
orStandardizer(String, String)
- Parameters:
stream
- the configuration XML input stream- Throws:
IllegalArgumentException
- on invalid configuration
-
Standardizer
public Standardizer(StandardizerConfiguration configuration) throws IllegalArgumentException
Initializes a new standardizer with XML configuration- Parameters:
configuration
- the configuration of the standardizer- Throws:
IllegalArgumentException
- on invalid configuration
-
Standardizer
public Standardizer(Standardizer standardizer)
Initializes a new standardizer based on an existing standardizer- Parameters:
standardizer
- an initialized standardizer instance as a base- Throws:
IllegalArgumentException
- on invalid configuration
-
-
Method Detail
-
isLicensed
public boolean isLicensed()
Gets whether the standardizer is licensed- Returns:
- whether the standardizer is licensed
-
setLicenseEnvironment
public void setLicenseEnvironment(String env)
Sets the license environment. For internal usage only.- Parameters:
env
- the license environment
-
getOldToNew
public int[] getOldToNew()
Returns the old -> new atom index mapping.
oldToNew[i]==j means that the i-th atom of the old molecule corresponds to the j-th atom of the new molecule.- Returns:
- the old -> new atom index mapping
-
getNewToOld
public int[] getNewToOld()
Returns the new -> old atom index mapping.
newToOld[i]==j means that the i-th atom of the new molecule corresponds to the j-th atom of the old molecule.- Returns:
- the new -> old atom index mapping
-
setFinalClean
@Deprecated public void setFinalClean() throws IllegalArgumentException
Deprecated.useConfigurationUtility.setFinalClean(StandardizerConfiguration)
on the configuration returned by the methodgetConfiguration()
Sets final clean task: original molecule dimension, partial, optional.- Throws:
IllegalArgumentException
-
setFinalClean
@Deprecated public void setFinalClean(int dim) throws IllegalArgumentException
Deprecated.useConfigurationUtility.setFinalClean(StandardizerConfiguration, int)
on the configuration returned by the methodgetConfiguration()
Sets final clean task: partial, target-only.- Parameters:
dim
- is the clean dimension, set-1
for the original molecule dimension- Throws:
IllegalArgumentException
-
setFinalClean
@Deprecated public void setFinalClean(int dim, boolean partial) throws IllegalArgumentException
Deprecated.useConfigurationUtility.setFinalClean(StandardizerConfiguration, int, boolean)
on the configuration returned by the methodgetConfiguration()
Sets final clean task: target-only.- Parameters:
dim
- is the clean dimension, currently partial clean only works in 2D - if set to3
then full clean is performedpartial
- istrue
if only the changing atoms should be cleaned,false
if full clean is needed - if the clean dimension is different from the molecule dimension then always full clean is performed- Throws:
IllegalArgumentException
-
standardize
public List<Changes> standardize(Molecule mol) throws chemaxon.license.LicenseException, IllegalArgumentException
Standardization for one input molecule: performs the standardization actions according to the XML configuration. The input molecule is transformed and returned, no new molecule object is created. If the input molecule is a reaction then each reactant/product is standardized.- Parameters:
mol
- is the input molecule to be standardized- Returns:
- the list of changes applied by the standardizer (each entry of the list is a change set of a standardizer action execution)
- Throws:
chemaxon.license.LicenseException
- if there is no valid licenseIllegalArgumentException
- if the parameter molecule, or the set configuration is not valid
-
getAppliedTaskIndexes
public int[] getAppliedTaskIndexes()
Returns the indexes of tasks applied to the last input molecule. Indexing is 0-based, with the largest index which equals to the number of tasks meaning the final clean action.- Returns:
- the indexes of tasks applied to the last input molecule
-
getAppliedTaskIDs
public String[] getAppliedTaskIDs()
Returns the IDs of tasks applied to the last input molecule. The IDFINAL_CLEAN_ID
corresponds to the final clean action.- Returns:
- the IDs of tasks applied to the last input molecule
-
setFinalStereoFix
public void setFinalStereoFix(boolean clean)
Sets to perform final stereo fixes.- Parameters:
clean
- iftrue
then final stereo fix is performed
-
setActiveGroups
@Deprecated public void setActiveGroups(String[] groups)
Deprecated.useConfigurationUtility.filterGroups(StandardizerConfiguration, String[])
on the configuration returned by the methodgetConfiguration()
Sets the active groups of the runners- Parameters:
groups
- the list of names of active groups
-
getActiveGroups
@Deprecated public String[] getActiveGroups()
Deprecated.useConfigurationUtility.filterGroups(StandardizerConfiguration, String[])
on the configuration returned by the methodgetConfiguration()
Gets the active groups of the runners- Returns:
- the list of names of active groups
-
getConfiguration
public StandardizerConfiguration getConfiguration()
Gets the configuration of the standardizer. Note that modifications on the configuration is not applied to the standardizer.- Returns:
- the configuration of the standardizer
-
getLicenseEnvironment
public String getLicenseEnvironment()
Gets the license environment of the standardizer- Returns:
- the license environment of the standardizer
-
isStereoFix
public boolean isStereoFix()
Gets whether last stereo fix should be applied- Returns:
- whether last stereo fix should be applied
-
setIgnoreConfigurationErrors
public void setIgnoreConfigurationErrors(boolean ignore)
Sets whether the configuration errors should be ignored by the standardization process.
When configuration errors are ignored, invalid standardizer actions in the configuration are not executed, however all valid actions are to be executed.
When configuration errors are not ignored,IllegalArgumentException
thrown whenstandardize(Molecule)
method is called on an invalid configuration.- Parameters:
ignore
- true if configuration errors should be ignored
-
-