Class PFParameters


  • @PublicAPI
    public class PFParameters
    extends MDParameters
    Manages 2D pharmacophore fingerprint parameters. This class has multiple roles: 1. reads, stores and provides parameters for PharmacophoreFingerprint ; and 2. acts as a shared memory area of all PharmacophoreFingerprint instances. This latter serves pure running-time and storage efficiency needs by removing redundant data from PharmacophoreFingerprint objects and easing the communication (that is passing data) between parts of the program. Example for these include the following data members: compressedData, xyz, asymmetricXYZSum. Most of these members have public access for the sake of ease. (The use of private access members and the introduction of corresponding setter/getter methods would not increase the safety (or any other quality) quality of the code at all (as they would not add any further functionality, than the mere change or retrieval of the value, which can now be done directly).)
    Since:
    JChem 2.2
    • Field Detail

      • DEFAULT_RESOLUTION

        public static final int DEFAULT_RESOLUTION
        default values
        See Also:
        Constant Field Values
      • DEFAULT_FUZZINESS_FACTOR

        public static final float DEFAULT_FUZZINESS_FACTOR
        See Also:
        Constant Field Values
      • DEFAULT_FUZZY_LOWER_BOUND

        public static final int DEFAULT_FUZZY_LOWER_BOUND
        See Also:
        Constant Field Values
      • fuzzinessFactors

        protected ArrayList fuzzinessFactors
        fuzziness factors of parametrized metrics
      • fuzzyExp

        protected float[][] fuzzyExp
        fuzzi exponent for the FBPA metric, calculated from the fuzziness factor
      • colDec

        protected chemaxon.pharmacophore.ColorDecoder colDec
        atom set colors
      • pptNames

        protected String[] pptNames
        Pharmacophore point type names. These are similar to the above coloring scheme, though instead of colors, this array contains the IDs of pharmacophore point types as defined in the XML configuration. Tha names of combined types (e.g. d - (Donor Minus) are obtained by concatenating the corresponding IDs.
      • gFuzzyIncrements

        protected float[][] gFuzzyIncrements
        Fuzzy smoothing values for gaussian smoothing. The first index is the number of rotatable bonds while the second is the distance value. For the sake of efficiency, distances from 0 to maxDist() are stored.
      • svFuzzyIncrements

        protected float[][][] svFuzzyIncrements
        Fuzzy smoothing values for smoothing with user defined smoothing vector. The first and the second indexes are the pharmacophore point type indexes the third is the distance value.
      • compressedData

        protected byte[][] compressedData
        Buffer for compressed data, used in MolecularDescriptor.toData( final int[] ). Element 'i' is either null or is an array of 'i' bytes.
      • xyz

        public float[] xyz
        The calculateXYZ() methods (in PharmacophoreFingerprint sub-classes) calculate three numbers (denoted by x,y and z), but methods in java cannot have output parameters. We could (1) pass an array of three elements, but in that case the array was either a data member of PharmacophoreFingerprint, which has to be avoided in order to keep the size of a descriptor as small as possible; or alternatively (2) the array could be allocated in the caller of calculateXYZ() each time, which clearly had time and storage overhead. Keeping a preallocated instance in parameters is efficient though apparently not nice in terms of object oriented principles.
      • asymmetricXYZSum

        public float asymmetricXYZSum
        Stores last calculatred asymmetric Tanimoto sum.
    • Constructor Detail

      • PFParameters

        public PFParameters()
        Creates an empty object. Use setConfig( String paramString ) to initialize it properly.
      • PFParameters

        public PFParameters​(File configFile)
                     throws MDParametersException
        Creates a new object based on a given configuration file.
        Parameters:
        configFile - XML configuration file
        Throws:
        MDParametersException - missing or bad XML configuration
      • PFParameters

        public PFParameters​(String XMLconfig)
                     throws MDParametersException
        Creates a new object based on a given configuration string.
        Parameters:
        XMLconfig - XML configuration string
        Throws:
        MDParametersException - missing or bad XML configuration
    • Method Detail

      • fromString

        public void fromString​(String parameterString)
                        throws MDParametersException
        Sets parameters from a string representation. This method processes an XML format, but derived classes may overload this and define their own format.
        Overrides:
        fromString in class MDParameters
        Parameters:
        parameterString - parameters in string
        Throws:
        MDParametersException - when the parameter string is not well-formed
      • fromFile

        public void fromFile​(File parameterFile)
                      throws MDParametersException
        Sets parameters from an XML file. Derived classes may overload this and define their own format (even other than XML).
        Overrides:
        fromFile in class MDParameters
        Parameters:
        parameterFile - initialized configuration file
        Throws:
        MDParametersException - failed to process parameter file
      • toString

        public String toString()
        Returns the XML configuration in a string.
        Overrides:
        toString in class MDParameters
        Returns:
        configuration string in XML format
      • setParameters

        public void setParameters​(String parametersString)
                           throws MDParametersException
        Sets parameters from an XML string representation overwriting all previous parameters settings with the new ones.
        Overrides:
        setParameters in class MDParameters
        Parameters:
        parametersString - parameters in string
        Throws:
        MDParametersException - when the parameter string is not well-formed
      • setParameters

        public void setParameters​(File parametersFile)
                           throws MDParametersException
        Sets parameters from an XML file representation overwriting all previous settings with the new ones.
        Overrides:
        setParameters in class MDParameters
        Parameters:
        parametersFile - parameter configuration file
        Throws:
        MDParametersException - when the parameter string is not well-formed
      • init

        protected void init()
        Initializes the object. Only those fundamental data members are set that do not depend on the XML configuration.
      • initGenerator

        protected void initGenerator()
                              throws MDParametersException
        Creates and initializes a PFGenerator instance. The generator is stored in the MDParameters in order to spare memory space: the PFParameter object is shared among multiple instances of PharmacophoreFingerprint, thus they refer to the same generator object too via the parameters field.
        Throws:
        MDParametersException
      • initParameters

        protected void initParameters()
        Initializes those data members that depend on the XML configuration but are not directly taken from it.
        Overrides:
        initParameters in class MDParameters
      • generate

        protected String[] generate​(Molecule m,
                                    MolecularDescriptor cd)
                             throws MDGeneratorException
        Calls the corresponding MolecularDescriptorGenerator and generates the descriptor for the given molecule. Note, that it is the responsibility of subclasses to initialize the generator upfront any call to this function.
        Parameters:
        m - a molecular structure
        cd - the chemical descriptor generated for the given molecule, an output parameter
        Returns:
        names of Molecule Property-s (SDfile tags) set by the generator
        Throws:
        MDGeneratorException - when failed to generate descriptor
      • setCurrentParametrizedMetric

        public void setCurrentParametrizedMetric​(int metricIndex)
        Selects a metric to be used. When a metric is selected all properties and related parameters can be retrieved with the getter methods of this class.
        Overrides:
        setCurrentParametrizedMetric in class MDParameters
        Parameters:
        metricIndex - index of a parametrized metric to be used
      • setFuzzySmoothingFactor

        public void setFuzzySmoothingFactor​(float fsf)
        Sets the value of the fuzzy smoothing factor used in the generation of fuzzy fingerprints. The smoothing process fits a Guassian curve to all values to be put into histogram bins, and this value is the standard deviation of the corresponding normal distribution.
        Parameters:
        fsf - the fuzzy smoothing factor
      • setFuzzyCutOff

        public void setFuzzyCutOff​(float fco)
      • setFuzzyLowerBound

        public void setFuzzyLowerBound​(int flb)
      • setSymmetricalFuzzy

        public void setSymmetricalFuzzy​(boolean sf)
      • setIgnoreRotatableBonds

        public void setIgnoreRotatableBonds​(boolean irb)
      • setFuzzinessFactor

        public void setFuzzinessFactor​(float alpha)
        Sets the value of the fuzziness factor, used in fuzzy bipolar pharmacophore autocorrelogram (FBPA) based convolution product in non-parametrized (generic) FBPA metric.
        Parameters:
        alpha - fuzziness factor used in the convolution product
      • setUsePMAP

        public void setUsePMAP​(String pmapTagName)
        Pharmacophore map data in imported Molecule-s should be used. The generator will not generate PMAP data, but will use the exsiting one.
        Parameters:
        pmapTagName - name of the SDfile tag storing the PMAP data
      • setPMAPTagName

        public void setPMAPTagName​(String tagName)
        Sets the name of the pharmacophore map tag to be considered in the input SDfile.
        Parameters:
        tagName - name of the SDfile tag that stores pharmacophore map
      • setWeights

        public void setWeights​(float[] featureWeights,
                               float[] distanceWeights)
        Sets the cell-wise weight factors for the current parametrized metric.
        Parameters:
        featureWeights - weights for each pharmacophore type
        distanceWeights - weights for each point pair distance
      • getNumberOfFeatures

        public int getNumberOfFeatures()
        The number of pharmacophore features (aka types, properties) used in the fingerprints.
        Returns:
        number of pharmacophore features
      • getPSymbols

        public PSymbols getPSymbols()
        Gets the pharmacophore type symbols used in the current configuration.
        Returns:
        pharmacophore symbols
      • getSymbol

        public String getSymbol​(int i)
        Gets the symbol associated with the specified Pharmacophore.
        Parameters:
        i - index of the pharmacophore property (feature)
        Returns:
        the symbol string of the feature
      • getSymbolIndex

        public int getSymbolIndex​(String symbol)
                           throws IllegalArgumentException
        Gets the index associated with the specified Pharmacophore symbol.
        Parameters:
        symbol - pharmacophore property (feature) symbol
        Returns:
        the index of the feature, -1 if not found
        Throws:
        IllegalArgumentException
      • getMinDist

        public int getMinDist()
        Gets the minimum distance of pharmacophore points that is considered.
        Returns:
        value of minimal distance
      • getMaxDist

        public int getMaxDist()
        Gets the miximum distance of pharmacophore points that is considered.
        Returns:
        value of miximal distance
      • getResolution

        public int getResolution()
        Gets the resolution of histograms. THe resolution is the width of a histogram bin, that is the distance values considered to be indistinguishable.
        Returns:
        value of the current resolution
      • getNDists

        public int getNDists()
        Gets the number of histograms bars, that is that number of distance values disguished.
        Returns:
        hte number of ditance values in one histogram
      • getNumberOfWeights

        protected int getNumberOfWeights​(int parametrizedMetricIndex)
                                  throws IllegalArgumentException
        Gets the number of weight factors used by the specified metric. This method can be applied to the dissimilarity metrics provided by the MolecularDescriptor class or its derived classes, but not to parametrized metric.
        Overrides:
        getNumberOfWeights in class MDParameters
        Parameters:
        parametrizedMetricIndex - parametrized metric index
        Returns:
        number of weights the metric uses
        Throws:
        IllegalArgumentException - if the given parameter is not a valid metric index
      • isFuzzyFingerprint

        public boolean isFuzzyFingerprint()
        Gets whether the fuzzy fingerprints are used or not.
        Returns:
        fuzzy flag
      • isGaussianSmoothing

        public boolean isGaussianSmoothing()
        Gets if fuzzy smmoothing is based on normal distribution.
        Returns:
        true if smoothing has gaussian
      • getFuzzySmoothingFactor

        public float getFuzzySmoothingFactor()
        Gets the fuzzy smoothing factor used in the construction of fuzzy fingerprints.
        Returns:
        the fuzzy smoothing factor
      • isSymmetricalFuzzy

        public boolean isSymmetricalFuzzy()
      • getIgnoreRotatableBonds

        public boolean getIgnoreRotatableBonds()
      • getFuzzyLowerBound

        public float getFuzzyLowerBound()
      • getDefaultStandardizerConfiguration

        public static String getDefaultStandardizerConfiguration()
        Gets the default configuration of the standardizer. This method is called if no standardizer configuration is set in the parameters configuration. The default standardization for PharmacophoreFingerprint includes aromatization and the removal of small disjoint fragments (largest component is kept only).
        Returns:
        standardizer confiuration XML string
        Since:
        JChem 2.3
      • getDefaultDocumentFrame

        public String getDefaultDocumentFrame()
        Gets the default XML configuration string. This is needed when the PharmacophoreFingerprint XML configuration is not specified.
        Overrides:
        getDefaultDocumentFrame in class MDParameters
        Returns:
        default XML configuration string of the PFParameters class
        Since:
        JChem 2.3
      • getGaussianFuzzyIncrements

        public float[][] getGaussianFuzzyIncrements()
        Gets fuzzy increments for the fuzzy smoothing with a normal distribution. The first index of the raturned array is the number of rotatable bonds, while the second is the distance of the two pharmacophoric points considered. These values represent a normal distribution with a standard deviation equal to the product of the number of rotatable bonds plus one and the fuzzy smoothing factor. Therefore, the more rotatable bonds are found between the two pharmacophoric point, the larger the deviation of the normal distribution is (the wider and flatter the Gaussian curve is). Note, that the normal distribution is standard (its peek is in zero), and that only the right hand side of the curve is returned (the left is a mirror image).
        Returns:
        fuzzy increments
      • getCustomFuzzyIncrements

        public float[] getCustomFuzzyIncrements​(int fa,
                                                int fb)
        Gets fuzzy increments for the fuzzy smoothing with a user-defined custom distribution (fuzzy smoothing vector).
        Parameters:
        fa - pharmacophore point type of the first component of the pair
        fb - pharmacophore point type of the second component of the pair
        Returns:
        fuzzy increments
      • getFuzzyExponents

        public float[][] getFuzzyExponents()
        Gets the precalculated fuzzy exponent used in the Fuzzy Bipolar Autocorrelogram (FBPA) metric.
        Returns:
        fuzzy exponents
      • getAtomSetColors

        public Color[] getAtomSetColors()
        Gets the coloring of atoms as defined in the XML configuration file.
        Returns:
        array of colors of different pharmacophore point types
      • getAtomSetNames

        public String[] getAtomSetNames()
        Gets the name of atom sets (pharmacophore point type set), as defined in the configuration file/string.
        Returns:
        names of pharmacophore point types
      • getAtomSetIndexes

        public int[] getAtomSetIndexes​(Molecule m,
                                       PharmacophoreFingerprint pfp)
        Gets the individual atom colors by pharmcophore point type. This method is implemented in this class because it calls the pharmacophore fingerprint generator.
        Parameters:
        m - a molecule to assign pharmacophore point colors to
        Returns:
        array of color indexes indexed by atom indexes
      • processDocument

        protected void processDocument​(boolean all)
                                throws MDParametersException
        Description copied from class: MDParameters
        Searches the DOM tree for relevant nodes and sets internal variables to some these nodes for the sake of easier information processing.
        Overrides:
        processDocument in class MDParameters
        Parameters:
        all - process the complete document or only the ScreeningConfiguration tag
        Throws:
        MDParametersException
      • readValues

        protected void readValues​(boolean all)
                           throws MDParametersException
        Description copied from class: MDParameters
        Picks attribute values from the document tree that are relevant to the actual MDParameters sub-class.
        Overrides:
        readValues in class MDParameters
        Parameters:
        all - process the complete document or only the ScreeningConfiguration tag
        Throws:
        MDParametersException
      • readMetricParameters

        protected void readMetricParameters()
                                     throws MDParametersException
        Description copied from class: MDParameters
        Processes all ParametrizedMetric nodes in the DOM tree. Reads parameterized metric names and associated parameter setting and stores them in data member for faster and easier access in getter methods.
        Overrides:
        readMetricParameters in class MDParameters
        Throws:
        MDParametersException - if one of the nodes is not well-formed
      • appendParametrizedMetric

        protected int appendParametrizedMetric​(String name,
                                               String metric)
        Description copied from class: MDParameters
        Extends internal data with a new parametrized metric. Neither the DOM tree nor the XML document is modified.
        Overrides:
        appendParametrizedMetric in class MDParameters
        Parameters:
        name - name of the parametrized metric
        metric - dissimilarity metric name (as defined in its implementor class
      • importNodes

        protected boolean importNodes​(org.dom4j.Document doc,
                                      boolean merge)
        Description copied from class: MDParameters
        Imports nodes from the specified Document into the current (main) Document. New nodes can either merged into the existing ones without removing them, or new nodes may overwrite exisiting nodes.
        Overrides:
        importNodes in class MDParameters
        Parameters:
        doc - import nodes from this document
        merge - merge (add new) or overwrite (replace with new) existing nodes
      • tripletIndex

        public int tripletIndex​(int f1,
                                int f2,
                                int d)
        Calculates the index of a feature pair and distance triplet in the linearised representation of histograms. Features are ordered as described above.
        Parameters:
        f1 - index of the first feature
        f2 - index of the other feature
        d - distance value
        Returns:
        the index of the triplet