Package chemaxon.marvin.calculations

Class pKaPlugin

  • All Implemented Interfaces:
    chemaxon.license.Licensable
    @PublicAPI
public class pKaPlugin
extends CalculatorPlugin
    Plugin class for macro/micro pKa calculation.

    API usage example: 

            // instantiate plugin
        pKaPlugin plugin = new pKaPlugin();

        // set parameters
        plugin.setMaxIons(6);
      plugin.setBasicpKaLowerLimit(-5.0);
      plugin.setAcidicpKaUpperLimit(25.0);
      plugin.setpHLower(3.0); // for ms distr
      plugin.setpHUpper(6.0); // for ms distr
      plugin.setpHStep(1.0);  // for ms distr

        MolImporter importer = new MolImporter("mols.sdf");
        Molecule mol = null;
        while ((mol = importer.read()) != null) {
            // set molecule and run calculation
            plugin.setMolecule(mol);
            plugin.run();
            
            // get the 3 strongest ACIDIC pKa values
            double[] acidicpKa = new double[3];
            int[] acidicIndexes = new int[3];
            plugin.getMacropKaValues(pKaPlugin.ACIDIC, acidicpKa, acidicIndexes);

            // get the 3 strongest BASIC pKa values
            double[] basicpKa = new double[3];
            int[] basicIndexes = new int[3];
            plugin.getMacropKaValues(pKaPlugin.BASIC, basicpKa, basicIndexes);

            // get pKa values for each atom
            int count = mol.getAtomCount();
            for (int i=0; i < count; ++i) {

                // get ACIDIC and BASIC pKa values
                double apka = plugin.getpKa(i, pKaPlugin.ACIDIC);
                double bpka = plugin.getpKa(i, pKaPlugin.BASIC);
          }

          // get microspecies distributions
            double[] pHs = plugin.getpHs(); // pH values
            int mscount = plugin.getMsCount();
            for (int i=0; i < mscount; ++i) {
                Molecule ms = plugin.getMsMolecule(i);
                double[] distr = plugin.getMsDistribution(i); // distr values for pHs
            }
      }
      importer.close();

    Another example showing microspecies distributions at a single pH value: 

            // instantiate plugin
        pKaPlugin plugin = new pKaPlugin();

        // set pH
        plugin.setpH(3.0);

        MolImporter importer = new MolImporter("mols.sdf");
        Molecule mol = null;
        while ((mol = importer.read()) != null) {
            // set molecule and run calculation
            plugin.setMolecule(mol);
            plugin.run();

          // get microspecies data (molecule and distribution)
            int count = plugin.getMsCount();
            for (int i=0; i < count; ++i) {
                Molecule ms = plugin.getMsMolecule(i);
                double distr = plugin.getSingleMsDistribution(i);
            }
      }
      importer.close();

    Another example showing macro pKa calculation: 

            // instantiate plugin
        pKaPlugin plugin = new pKaPlugin();

        MolImporter importer = new MolImporter("mols.sdf");
        Molecule mol = null;
        while ((mol = importer.read()) != null) {
            // set molecule and run calculation
            plugin.setMolecule(mol);
            plugin.run();

          // get the acidic and basic macro pKa values
          double[] acidicpKaValues = plugin.getMacropKaValues(pKaPlugin.ACIDIC); 
          double[] basicpKaValues = plugin.getMacropKaValues(pKaPlugin.BASIC); 
      }
      importer.close();

    For concurrent plugin example applications using ChemAxon's concurrent framework, refer to the Concurrent plugin examples.

    Since:
    Marvin 3.0

    • Field Detail

      • STATICpKaPREFIX

        public static final int STATICpKaPREFIX
        pKa's prefix (acidic/basic) does not depend on the submitted micro state (default)
        See Also:
        Constant Field Values

      • DYNAMICpKaPREFIX

        public static final int DYNAMICpKaPREFIX
        pKa's prefix (acidic/basic) does depend on the submitted micro state
        See Also:
        Constant Field Values

      • DEF_MAXIONS

        public static final int DEF_MAXIONS
        The default value of the number of ionizable atoms to consider.
        See Also:
        Constant Field Values

      • DEF_TEMPERATURE

        public static final double DEF_TEMPERATURE
        The default temperature in Kelvins.
        See Also:
        Constant Field Values

      • MODEL_SMALL

        public static final int MODEL_SMALL
        Calculation model: small (precise up to the specified number of ionizable atoms).
        See Also:
        Constant Field Values

      • MODEL_LARGE

        public static final int MODEL_LARGE
        Calculation model: large (always precise, can take more time).
        See Also:
        Constant Field Values

      • DEF_IONICSTRENGTH

        public static final double DEF_IONICSTRENGTH
        The default ionic strength
        See Also:
        Constant Field Values

    • Constructor Detail

      • pKaPlugin

        public pKaPlugin()
        Constructor. Creates the macro pKa calculator object.

    • Method Detail

      • setProgressMonitor

        public void setProgressMonitor​(MProgressMonitor pmon)
        Sets a progress observer to be used in run() to display progress status. Short calculations may ignore the observer object. The default implementation does nothing.
        Overrides:
        setProgressMonitor in class CalculatorPlugin
        Parameters:
        pmon - is the progress monitor, may be null

      • setParameters

        public void setParameters​(Properties params)
                   throws PluginException
        Sets the input parameters for the plugin. pKa parameters and value ranges:
        • type: pKa,acidic,basic (pKa is either the basic or the acidic pKa)
        • precision: 0-8 or inf (default: 2) (number of displayed fractional digits, inf for unrounded value)
        • mode: macro or micro (default: macro)
        • prefix: static or dynamic acid/base prefix (default: static)
        • min: the minimal basic micro pKa threshold
        • max: the maximal acidic micro pKa threshold
        • temperature: temperature (in Kelvin, default: 298)
        • ions: maximum number of ionizable atoms (default: 8)
        • calcAlways: true if calculation to be performed even if the maximum number of ionizable atoms is exceeded (deprecated, see 'model' below)
        • model: "small" or "large" (replaces 'calcAlways')
          • small: precise up to the number of ionizable atoms given in 'ions' (8 by default), equivalent to calcAlways=false (cxcalc and API default)
          • large: always precise but can take more time, equivalent to calcAlways=true (GUI default)
        If mode is "macro" then we have additional parameters for microspecies distribution:
        • mscalc: true if microspecies distribution to be shown, false otherwise (default: false)
        • lower: pH lower limit (default: 0.0)
        • upper: pH upper limit (default: 14.0)
        • step: pH step to be taken between lower and upper limits (default: 0.2)
        • majortautomer: true or false (take major tautomeric form)
        Overrides:
        setParameters in class CalculatorPlugin
        Parameters:
        params - is the parameter table
        Throws:
        PluginException - on error

      • useCorrectionLibrary

        @Deprecated
public void useCorrectionLibrary​(boolean use)
        Deprecated.
        Use setCorrectionLibrary(String)
        Sets the usage of the correction library. (default: false)
        Parameters:
        use - if true, then the calculation will use the correction library
        Since:
        Marvin 5.2

      • setCorrectionLibrary

        public void setCorrectionLibrary​(String correctionLibraryId)
        Sets the correction library.
        Parameters:
        correctionLibraryId - is the correction library identifier
        Since:
        Marvin 5.4

      • setCorrectionData

        public void setCorrectionData​(chemaxon.calculations.pka.PKaTrainingResult trainingResult)
        Sets correction data for calculation
        Parameters:
        trainingResult - correction data

      • setCorrectionLibraryPath

        public void setCorrectionLibraryPath​(String correctionLibraryPath)
        Sets the correction library file directly.
        Parameters:
        correctionLibraryPath -
        Since:
        Marvin 6.0

      • getCorrectionLibraryIds

        public static String[] getCorrectionLibraryIds()
        Returns the id's of available pKa correction libraries.
        Returns:
        the id's of available pKa correction libraries
        Since:
        Marvin 5.4

      • setMicropKaCalc

        public void setMicropKaCalc​(boolean micro)
        Sets micro pKa calculation. Default: false (macro pKa calculation).
        Parameters:
        micro - is true if micro pKa calculation is required.
        Since:
        Marvin 4.1

      • setCalcAlways

        @Deprecated
public void setCalcAlways​(boolean calcAlways)
        Deprecated.
        replaced by setModel(int)
        Sets whether to perform calculation if the maximum number of ionizable atoms is exceeded. If set to true, pKa values are calculated with a different, more time-consuming method in this case. Note, that microspecies are not determined in this case. Default: false.
        Parameters:
        calcAlways - is true if calculation should be performed if the maximum number of ionizable atoms is exceeded
        See Also:
        setMaxIons(int), setModel(int)

      • setModel

        public void setModel​(int model)
        Sets the calculation model.
        Parameters:
        model - is the calculation model:
        • MODEL_SMALL: optimized for a small number of ionizable atoms (default)
        • MODEL_LARGE: optimized for a large number of ionizable atoms
        Since:
        Marvin 4.0
        See Also:
        setMaxIons(int)

      • setMaxIons

        public void setMaxIons​(int n)
        In case of MODEL_SMALL model, it sets the maximum number of ionizable atoms to be considered and uses simple calculation method to compute pKa values. In case of MODEL_LARGE model, it switches the simple calculation method to a more complicated one when the number of ionizable atoms exceeds this limit. The default value is 8.
        Parameters:
        n - is the maximum number of ionizable atoms to be considered
        See Also:
        setModel(int)

      • setBasicpKaLowerLimit

        public void setBasicpKaLowerLimit​(double minB)
        Sets the minimum basic pKa (default: -10).
        Parameters:
        minB - is the minimum basic pKa

      • setAcidicpKaUpperLimit

        public void setAcidicpKaUpperLimit​(double maxA)
        Sets the maximum acidic pKa (default: 20).
        Parameters:
        maxA - is the maximum acidic pKa

      • setTemperature

        public void setTemperature​(double temperature)
        Sets the temperature (default: 298 Kelvin).
        Parameters:
        temperature - is the temperature (Kelvin)
        Since:
        Marvin 3.5.1

      • setpHLower

        public void setpHLower​(double lower)
        Sets pH lower limit for the calculation of microspecies distributions. Also activates the calculation of microspecies distributions. The default value is 0.0.
        Parameters:
        lower - is the pH lower limit

      • setpHUpper

        public void setpHUpper​(double upper)
        Sets pH upper limit for the calculation of microspecies distributions. Also activates the calculation of microspecies distributions. The default value is 14.0.
        Parameters:
        upper - is the pH upper limit

      • setpHStep

        public void setpHStep​(double step)
        Sets pH step for the calculation of microspecies distributions. Also activates the calculation of microspecies distributions. The default value is 1.0.
        Parameters:
        step - is the pH step

      • setpH

        public void setpH​(double pH)
        Sets the pH value for the calculation of microspecies distributions. This method activates the calculation of microspecies distributions at a single pH value.
        Parameters:
        pH - is the pH value

      • isMsCalc

        public boolean isMsCalc()
        Returns true if microspecies calculation.
        Overrides:
        isMsCalc in class CalculatorPlugin
        Returns:
        true if microspecies calculation

      • setpKaPrefixType

        public void setpKaPrefixType​(int pKaPtype)
        Sets pKa prefix type (default: STATICpKaPREFIX)
        • STATIC pKa prefix: pKa's prefix does not depend on the submitted micro state
        • DYNAMIC pKa prefix: pKa's prefix does depend on the submitted micro state
        Parameters:
        pKaPtype - may have two values: STATICpKaPREFIX or DYNAMICpKaPREFIX
        Since:
        Marvin 4.1.3

      • getpKaPrefixType

        public int getpKaPrefixType()
        Returns the pKa prefix type.
        Returns:
        the pKa prefix type
        Since:
        Marvin 4.1.3

      • setConsiderTautomerization

        public void setConsiderTautomerization​(boolean considerTautomerization)
        Sets to consider tautomerization. Default: false.
        Parameters:
        considerTautomerization - the calculation will consider tautomerization and resonance if set (true)
        Since:
        Marvin 5.4

      • setTakeFullTautomerizationSpectrum

        public void setTakeFullTautomerizationSpectrum​(boolean takeFullTauSpectrum)
        Sets to consider the full tautomer distribution upon the macro pka calculation. Default: false.
        Parameters:
        takeFullTauSpectrum - the calculation will consider all meaningful tautomer structure if set (true)
        Since:
        Marvin 22.22

      • setTakeMajorTatomericForm

        @Deprecated
public void setTakeMajorTatomericForm​(boolean takeMajorTautomericForm)
        Deprecated.
        Use setConsiderTautomerization(boolean)
        Sets to use major tautomeric form in calculation. Default: false.
        Parameters:
        takeMajorTautomericForm - the calculation will be performed on the major tutomeric form of the input molecule if set (true)
        Since:
        Marvin 5.0

      • checkMolecule

        public void checkMolecule​(Molecule mol)
                   throws PluginException
        Checks the input molecule. Throws exception if the molecule molecule contains R-groups.
        Overrides:
        checkMolecule in class CalculatorPlugin
        Parameters:
        mol - is the input molecule
        Throws:
        PluginException - with error message for the user if the molecule is refused

      • getMsCount

        public int getMsCount()
        Returns the number of microspecies and/or distributions. Calculated only if macro pKa is computed and the "mscalc" parameter is set to "true".
        NOTE that no microspecies are calculated when MODEL_LARGE is used. Use isOverflowCalculation() to check the used model.
        Returns:
        the number of microspecies and/or distributions.

      • getMsMolecule

        public Molecule getMsMolecule​(int msIndex)
        Returns the microspecies molecule. Calculated only if macro pKa is computed and the "mscalc" parameter is set to "true".
        Microspecies are calculated only when MODEL_SMALL is used. Use isOverflowCalculation() to check the used model.
        Parameters:
        msIndex - is the microspecies index
        Returns:
        the microspecies molecule

      • getSingleMsDistribution

        public double getSingleMsDistribution​(int msIndex)
        Returns the microspecies distribution at the specified pH value set in setpH(double).
        Parameters:
        msIndex - is the microspecies index
        Returns:
        the microspecies distribution at the previously given pH

      • getpHs

        public double[] getpHs()
        Returns the pH array.
        Returns:
        the pH array

      • getMsDistribution

        public double[] getMsDistribution​(int msIndex)
        Returns the microspecies distribution array.
        Parameters:
        msIndex - is the microspecies index
        Returns:
        the microspecies distribution array

      • getMsDistributions

        public double[][] getMsDistributions()
        Returns the microspecies distribution arrays for all microspecies: the i-th element is the disrtibution array of the i-th microspecies.
        Returns:
        the microspecies distribution arrays

      • getpKa

        public double getpKa​(int index)
        Returns the most significant pKa value for the given atom index. Use this to get the pKa if STATICpKaPREFIX prefix type is set. The pKa calculation has to be run beforehand by calling run().
        Parameters:
        index - is the atom index
        Returns:
        the pKa value, or Double.NaN if there is no pKa value for the given atom index and pKa type
        Since:
        Marvin 3.6
        See Also:
        setpKaPrefixType(int), getpKaValues(int, int)

      • getpKaMixed

        public double getpKaMixed​(int index)
        Returns the so called mixed ionization constant
        Parameters:
        index - is the atom index
        Returns:
        the pKa,mix. value, or Double.NaN if there is no pKa value for the given atom index and pKa type

      • getpKaConc

        public double getpKaConc​(int index)
        Returns the so called concentration ionization constant.
        Parameters:
        index - is the atom index
        Returns:
        the pKa,mix. value, or Double.NaN if there is no pKa value for the given atom index and pKa type

      • getpKaValues

        public double[] getpKaValues​(int index,
                             int type)
        Returns the pKa values for the given atom index and pKa type. The pKa calculation has to be run beforehand by calling run().
        Parameters:
        index - is the atom index
        type - is the pka type: ACIDIC or BASIC
        Returns:
        the pKa values, or null if there is no pKa value for the given atom index and pKa type
        Since:
        Marvin 4.1.3
        See Also:
        setpKaPrefixType(int)

      • getpKaType

        public int getpKaType​(int index)
        Returns the pKa type: ACIDIC, BASIC or 0 if there is no pKa value for the given atom.
        Parameters:
        index - is the atom index
        Returns:
        the pKa type: ACIDIC, BASIC or 0.
        Since:
        Marvin 3.6

      • getMacroSpeciesCharge

        public int getMacroSpeciesCharge​(int msIndex)
        Returns the formal charges of a given macrospecies. Valid only in case of overflow calculation.
        Parameters:
        msIndex - is the macrospecies index
        Returns:
        the formal charges of a given macrospecies
        See Also:
        isOverflowCalculation()

      • isOverflowCalculation

        public boolean isOverflowCalculation()
        Returns true if overflow calculation: maximum number of ionizable atoms exceeded and protein ionization invoked.
        Returns:
        true if overflow calculation

      • getErrorMessage

        public String getErrorMessage()
        Returns the calculation error information message if run() returned false (calculation error): the number of ionizable atoms exceeds the specified limit (given in the "ions" parameter) or hydrogen valence error.
        Overrides:
        getErrorMessage in class CalculatorPlugin
        Returns:
        the calculation error information message

      • getWarningMessage

        public String getWarningMessage()
        Returns the calculation warning information message.
        Overrides:
        getWarningMessage in class CalculatorPlugin
        Returns:
        the calculation warning information message

      • getResultTypes

        public Object[] getResultTypes()
        Returns the result types (possible types: pKa, acidic, basic, msdistr).
        Overrides:
        getResultTypes in class CalculatorPlugin
        Returns:
        the result types

      • getResultCount

        public int getResultCount​(Object type)
        Returns the number of result items for the given result key. pKa returns the atom count.
        Overrides:
        getResultCount in class CalculatorPlugin
        Parameters:
        type - is the result type
        Returns:
        the number of result items
        See Also:
        getResultTypes()

      • getResult

        public Object getResult​(Object type,
                        int index)
                 throws PluginException
        Returns the result item for the specified key and index. If the type is "msdistr" then returns the pH - distribution table as a double[][] with the 0-th element the pH array and the 1-st element the distribution array corresponding to the microspecies with the specified index (result index). Otherwise pKa returns the required pKa value as a Double object for the given atom index (result index). Returns Double.NaN if the atom with the given index does not have a valid macro pKa value for the specified result type.
        Overrides:
        getResult in class CalculatorPlugin
        Parameters:
        type - is the result type
        index - is the result index
        Returns:
        the result item for the specified key and index
        Throws:
        PluginException - if the result cannot be returned
        See Also:
        getResultTypes()

      • getResult

        public Object getResult​(Object type,
                        String arg)
                 throws PluginException
        Returns the result item for the specified type ("acidic" or "basic") and the specified strength index ("1" means the strongest value, "2" means the second strongest value, etc.) given in the argument string. Returns Double.NaN for non-existent values (e.g. when the type is "acidic" and the arg string is "2" but there is only one acidic pKa value for the input molecule).
        Overrides:
        getResult in class CalculatorPlugin
        Parameters:
        type - is the result type ("acidic" or "basic")
        arg - is the strength order index
        Returns:
        the result item for the specified type and strength index
        Throws:
        PluginException - if the result cannot be returned
        See Also:
        CalculatorPlugin.getResultTypes()

      • getSortedValues

        @Deprecated
public void getSortedValues​(int pkatype,
                            double[] values,
                            int[] indexes)
                     throws PluginException
        Deprecated.
        Use getMacropKaValues(int,double[],int[]) instead
        Calculates the least acidic pKa values in ascending order or the biggest basic pKa values in descending order. The pKa calculation has to be run beforehand by calling run(). The length of the result value array determines the number of pKa values to be computed. If the index array is non-null then it is assumed to have the same length as the value array and will be filled with the corresponding atom indices (0-based).
        Parameters:
        pkatype - is the pKa type (ACIDIC or BASIC)
        values - is the pKa value array to be filled with pKa values in descending strength order (increasing for acidic pKa, descending for basic pKa values), the last entries are set to Double.NaN if there are less pKa values than the array length
        indexes - is the corresponding atom index array to be filled (may be null), the index is set to -1 for non-existent values (Double.NaN)
        Throws:
        PluginException - if an error occurs during the calculation

      • getMacropKaValues

        public void getMacropKaValues​(int pkatype,
                              double[] values,
                              int[] indexes)
                       throws PluginException
        Calculates the least acidic pKa values in ascending order or the biggest basic pKa values in descending order. The pKa calculation has to be run beforehand by calling run(). The length of the result value array determines the number of pKa values to be computed. If the index array is non-null then it is assumed to have the same length as the value array and will be filled with the corresponding atom indices (0-based).
        Parameters:
        pkatype - is the pKa type (ACIDIC or BASIC)
        values - is the pKa value array to be filled with pKa values in descending strength order (increasing for acidic pKa, descending for basic pKa values), the last entries are set to Double.NaN if there are less pKa values than the array length
        indexes - is the corresponding atom index array to be filled (may be null), the index is set to -1 for non-existent values (Double.NaN)
        Throws:
        PluginException - if an error occurs during the calculation
        Since:
        Marvin 5.0.7

      • getMacropKaValues

        public double[] getMacropKaValues​(int pkatype)
                           throws PluginException
        Calculates the acidic pKa values in ascending order or the basic pKa values in descending order. The pKa calculation has to be run beforehand by calling run().
        Parameters:
        pkatype - is the pKa type (ACIDIC or BASIC)
        Returns:
        the pKa value array with pKa values in descending strength order (increasing for acidic pKa, descending for basic pKa values) or null if there are no ionizable atoms in the molecule
        Throws:
        PluginException - if an error occurs during the calculation
        Since:
        Marvin 5.0.7

      • getResultAsString

        public String getResultAsString​(Object type,
                                int index,
                                Object result)
                         throws PluginException
        Returns the specified result in String format. If the type is "msdistr" then returns the pH - distribution table as a 2-column tab-separated table with the 0-th element the pH array and the 1-st element the distribution array corresponding to the microspecies with the specified index (result index). Otherwise pKa returns the rounded pKa value in string format: the value is rounded using the 'precision' input parameter that determines the number of fractional digits displayed. If the result is Double.NaN then returns the empty string.
        Overrides:
        getResultAsString in class CalculatorPlugin
        Parameters:
        type - is the result type
        index - is the result index
        result - is the result item
        Returns:
        the specified result in String format
        Throws:
        PluginException - if an invalid result item is given

      • getResultsAsString

        public String getResultsAsString​(Object type,
                                 int index,
                                 Object result)
                          throws PluginException
        Returns the specified result with possible subresults (both pKa values instead of the most significant pKa) in String format.
        Overrides:
        getResultsAsString in class CalculatorPlugin
        Parameters:
        type - is the result type
        index - is the result index
        result - is the result item
        Returns:
        the specified result in String format
        Throws:
        PluginException - if an invalid result item is given

      • getResultAsRGB

        public int getResultAsRGB​(Object type,
                          int index,
                          Object result)
                   throws PluginException
        Returns the specified result color as int format (alpha<<24 + red<<16 + green<<8 + blue): RED for acidic pKa, BLUE for basic pKa.
        Overrides:
        getResultAsRGB in class CalculatorPlugin
        Parameters:
        type - is the result type
        index - is the result index
        result - is the result item
        Returns:
        the specified result in color as int format
        Throws:
        PluginException - if an invalid result item is given

      • getResultsAsRGB

        public long getResultsAsRGB​(Object type,
                            int index,
                            Object result)
                     throws PluginException
        Returns the specified result color(s) as int format (alpha<<24 + red<<16 + green<<8 + blue). (e.g. both pKa colors instead of the most significant pKa color) as long (lower and upper bits).
        Overrides:
        getResultsAsRGB in class CalculatorPlugin
        Parameters:
        type - is the result type
        index - is the result index
        result - is the result item
        Returns:
        the specified result in color as int
        Throws:
        PluginException - if an invalid result item is given

      • isNegligible

        public boolean isNegligible​(double[] distr)

      • standardize

        public void standardize​(Molecule mol)
        Standardizes the molecule. This is done by performing the transformations necessary to run the plugin (e.g. aromatize, dehydrogenize, bring nitro groups to common form). Apart from the default standardization (aromatize and nitro) removes explicit hydrogens and stores the index-map between atom indices in the original and the new molecule. This map is used when the macropKa values and types are queried and the new atom indices should be mapped to the original ones. TODO: replace by call to chemaxon.standardizer.Standardizer
        Overrides:
        standardize in class CalculatorPlugin
        Parameters:
        mol - is the molecule to be standardized

      • setKeepExplicitHydrogens

        public void setKeepExplicitHydrogens​(boolean keepExplicitHydrogens)
        Sets if result molecule keeps explicit hydrogens or not
        Parameters:
        keepExplicitHydrogens - if the result should keep explicit hydrogens or not

      • getShowLogPercentage

        public boolean getShowLogPercentage()

      • getLogPercentageLimit

        public double getLogPercentageLimit()