diff docs/modules/txt/TopologicalPharmacophoreAtomPairsFingerprints.txt @ 0:4816e4a8ae95 draft default tip

Uploaded

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/modules/txt/TopologicalPharmacophoreAtomPairsFingerprints.txt	Wed Jan 20 09:23:18 2016 -0500
@@ -0,0 +1,403 @@
+NAME
+    TopologicalPharmacophoreAtomPairsFingerprints
+
+SYNOPSIS
+    use Fingerprints::TopologicalPharmacophoreAtomPairsFingerprints;
+
+    use Fingerprints::TopologicalPharmacophoreAtomPairsFingerprints
+    qw(:all);
+
+DESCRIPTION
+    TopologicalPharmacophoreAtomPairsFingerprints [ Ref 60-62, Ref 65, Ref
+    68 ] class provides the following methods:
+
+    new, GenerateFingerprints, GetDescription, GetAtomPairIDs,
+    SetAtomTypesToUse, SetAtomTypesWeight, SetFuzzFactor,
+    SetFuzzificationMethodology, SetFuzzificationMode, SetMaxDistance,
+    SetMinDistance, SetNormalizationMethodology, SetValuesPrecision,
+    StringifyTopologicalPharmacophoreAtomPairsFingerprints
+
+    TopologicalPharmacophoreAtomPairsFingerprints is derived from
+    Fingerprints class which in turn is derived from ObjectProperty base
+    class that provides methods not explicitly defined in
+    TopologicalPharmacophoreAtomPairsFingerprints, Fingerprints or
+    ObjectProperty classes using Perl's AUTOLOAD functionality. These
+    methods are generated on-the-fly for a specified object property:
+
+        Set<PropertyName>(<PropertyValue>);
+        $PropertyValue = Get<PropertyName>();
+        Delete<PropertyName>();
+
+    Based on the values specified for AtomTypesToUse, pharmacophore atom
+    types are assigned to all non-hydrogen atoms in a molecule and a
+    distance matrix is generated. A pharmacophore atom pairs basis set is
+    initialized for all unique possible pairs within MinDistance and
+    MaxDistance range.
+
+        Let:
+
+        P = Valid pharmacophore atom type
+
+        Px = Pharmacophore atom type x
+        Py = Pharmacophore atom type y
+
+        Dmin = Minimum distance corresponding to number of bonds between two atoms
+        Dmax = Maximum distance corresponding to number of bonds between two atoms
+        D = Distance corresponding to number of bonds between two atoms
+
+        Px-Dn-Py = Pharmacophore atom pair ID for atom types Px and Py at distance Dn
+
+        P = Number of pharmacophore atom types to consider
+        PPDn = Number of possible unique pharmacophore atom pairs at a distance Dn
+
+        PPT = Total number of possible pharmacophore atom pairs at all distances between Dmin and Dmax
+
+        Then:
+
+        PPD =  (P * (P - 1))/2 + P
+
+        PPT = ((Dmax - Dmin) + 1) * ((P * (P - 1))/2 + P)
+            = ((Dmax - Dmin) + 1) * PPD
+
+        So for default values of Dmin = 1, Dmax = 10 and P = 5,
+
+        PPD =  (5 * (5 - 1))/2 + 5 = 15
+        PPT = ((10 - 1) + 1) * 15 = 150
+
+        The pharmacophore atom pairs bais set includes 150 values.
+
+        The atom pair IDs correspond to:
+
+        Px-Dn-Py = Pharmacophore atom pair ID for atom types Px and Py at distance Dn
+
+        For example: H-D1-H, H-D2-HBA, PI-D5-PI and so on
+
+    Using distance matrix and pharmacohore atom types, occurrence of unique
+    pharmacohore atom pairs is counted. The contribution of each atom type
+    to atom pair interaction is optionally weighted by specified
+    AtomTypesWeight before assigning its count to appropriate distance bin.
+    Based on NormalizationMethodology option, pharmacophore atom pairs count
+    is optionally normalized. Additionally, pharmacohore atom pairs count is
+    optionally fuzzified before or after the normalization controlled by
+    values of FuzzifyAtomPairsCount, FuzzificationMode,
+    FuzzificationMethodology and FuzzFactor.
+
+    The final pharmacophore atom pairs count along with atom pair
+    identifiers involving all non-hydrogen atoms, with optional
+    normalization and fuzzification, constitute pharmacophore topological
+    atom pairs fingerprints of the molecule.
+
+    For *ArbitrarySize* value of AtomPairsSetSizeToUse, the fingerprint
+    vector correspond to only those topological pharmacophore atom pairs
+    which are present and have non-zero count. However, for *FixedSize*
+    value of AtomPairsSetSizeToUse, the fingerprint vector contains all
+    possible valid topological pharmacophore atom pairs with both zero and
+    non-zero count values.
+
+    The current release of MayaChemTools generates the following types of
+    topological pharmacophore atom pairs fingerprints vector strings:
+
+        FingerprintsVector;TopologicalPharmacophoreAtomPairs:ArbitrarySize:Min
+        Distance1:MaxDistance10;54;NumericalValues;IDsAndValuesString;H-D1-H H
+        -D1-NI HBA-D1-NI HBD-D1-NI H-D2-H H-D2-HBA H-D2-HBD HBA-D2-HBA HBA-D2-
+        HBD H-D3-H H-D3-HBA H-D3-HBD H-D3-NI HBA-D3-NI HBD-D3-NI H-D4-H H-D4-H
+        BA H-D4-HBD HBA-D4-HBA HBA-D4-HBD HBD-D4-HBD H-D5-H H-D5-HBA H-D5-...;
+        18 1 2 1 22 12 8 1 2 18 6 3 1 1 1 22 13 6 5 7 2 28 9 5 1 1 1 36 16 10
+        3 4 1 37 10 8 1 35 10 9 3 3 1 28 7 7 4 18 16 12 5 1 2 1
+
+        FingerprintsVector;TopologicalPharmacophoreAtomPairs:FixedSize:MinDist
+        ance1:MaxDistance10;150;OrderedNumericalValues;ValuesString;18 0 0 1 0
+        0 0 2 0 0 1 0 0 0 0 22 12 8 0 0 1 2 0 0 0 0 0 0 0 0 18 6 3 1 0 0 0 1
+        0 0 1 0 0 0 0 22 13 6 0 0 5 7 0 0 2 0 0 0 0 0 28 9 5 1 0 0 0 1 0 0 1 0
+        0 0 0 36 16 10 0 0 3 4 0 0 1 0 0 0 0 0 37 10 8 0 0 0 0 1 0 0 0 0 0 0
+        0 35 10 9 0 0 3 3 0 0 1 0 0 0 0 0 28 7 7 4 0 0 0 0 0 0 0 0 0 0 0 18...
+
+        FingerprintsVector;TopologicalPharmacophoreAtomPairs:FixedSize:MinDist
+        ance1:MaxDistance10;150;OrderedNumericalValues;IDsAndValuesString;H-D1
+        -H H-D1-HBA H-D1-HBD H-D1-NI H-D1-PI HBA-D1-HBA HBA-D1-HBD HBA-D1-NI H
+        BA-D1-PI HBD-D1-HBD HBD-D1-NI HBD-D1-PI NI-D1-NI NI-D1-PI PI-D1-PI H-D
+        2-H H-D2-HBA H-D2-HBD H-D2-NI H-D2-PI HBA-D2-HBA HBA-D2-HBD HBA-D2...;
+        18 0 0 1 0 0 0 2 0 0 1 0 0 0 0 22 12 8 0 0 1 2 0 0 0 0 0 0 0 0 18 6 3
+        1 0 0 0 1 0 0 1 0 0 0 0 22 13 6 0 0 5 7 0 0 2 0 0 0 0 0 28 9 5 1 0 0 0
+        1 0 0 1 0 0 0 0 36 16 10 0 0 3 4 0 0 1 0 0 0 0
+
+  METHODS
+    new
+            $TPAPFP = new TopologicalPharmacophoreAtomPairsFingerprints(
+                                                           %NamesAndValues);
+
+        Using specified *TopologicalPharmacophoreAtomPairsFingerprints*
+        property names and values hash, new method creates a new object and
+        returns a reference to newly created
+        TopologicalPharmacophoreAtomPairsFingerprints object. By default,
+        the following properties are initialized:
+
+            Molecule = ''
+            Type = 'TopologicalPharmacophoreAtomPairs'
+            MinDistance = 1
+            MaxDistance = 10
+            NormalizationMethodology = 'None'
+            AtomTypesToUse = ['HBD', 'HBA', 'PI', 'NI', 'H']
+
+            FuzzifyAtomPairsCount = 0
+            FuzzificationMode = 'AfterNormalization'
+            FuzzificationMethodology =  'FuzzyBinning'
+            FuzzFactor = 0.15
+
+            ValuesPrecision = 2
+
+        Examples:
+
+            $TPAPFP = new TopologicalPharmacophoreAtomPairsFingerprints(
+                                      'Molecule' => $Molecule);
+
+            $TPAPFP = new TopologicalPharmacophoreAtomPairsFingerprints(
+                                      'Molecule' => $Molecule,
+                                      'AtomPairsSetSizeToUse' => 'ArbitrarySize',
+                                      'MinDistance' => 1,
+                                      'MaxDistance' => 10,
+                                      'NormalizationMethodology' => 'None',
+                                      'AtomTypesToUse' => ['HBD', 'HBA', 'PI', 'NI', 'H'],
+                                      'FuzzifyAtomPairsCount' => 0);
+
+            $TPAPFP = new TopologicalPharmacophoreAtomPairsFingerprints(
+                                      'Molecule' => $Molecule,
+                                      'AtomPairsSetSizeToUse' => 'FizedSize',
+                                      'MinDistance' => 1,
+                                      'MaxDistance' => 10,
+                                      'NormalizationMethodology' => 'None',
+                                      'AtomTypesToUse' => ['HBD', 'HBA', 'PI', 'NI', 'H'],
+                                      'FuzzifyAtomPairsCount' => 1,
+                                      'FuzzificationMethodology' => 'FuzzyBinning',
+                                      'FuzzFactor' => 0.15,
+                                      'ValuesPrecision' => 2);
+
+            $TPAPFP->GenerateFingerprints();
+            print "$TPAPFP\n";
+
+    GetDescription
+            $Description = $TopologicalPharmacophoreAtomPairsFP->GetDescription();
+
+        Returns a string containing description of topological pharmacophore
+        atom pairs fingerprints.
+
+    GenerateFingerprints
+            $TopologicalPharmacophoreAtomPairsFP->GenerateFingerprints();
+
+        Generates topological pharmacophore atom pairs fingerprints and
+        returns *TopologicalPharmacophoreAtomPairsFP*.
+
+    GetAtomPairIDs
+            $AtomPairIDsRef = $TopologicalPharmacophoreAtomPairsFP->GetAtomPairIDs();
+            @AtomPairIDs = $TopologicalPharmacophoreAtomPairsFP->GetAtomPairIDs();
+
+        Returns atom pair IDs corresponding to atom pairs count values in
+        topological pharmacophore atom pairs fingerprints vector as an array
+        or reference to an array.
+
+    SetAtomPairsSetSizeToUse
+            $TopologicalPharmacophoreAtomPairsFP->SetAtomPairsSetSizeToUse($Values);
+
+        Sets pharmacophore atom pairs set size to use for topological
+        pharmacophore fingerprints generation and returns
+        *TopologicalPharmacophoreAtomPairsFingerprints*.
+
+        Possible values for pharmacophore atom pairs set size are:
+        *ArbitrarySize, FizedSize*. Default value: *ArbitrarySize*.
+
+        For *ArbitrarySize* value of AtomPairsSetSizeToUse, the fingerprint
+        vector correspond to only those topological pharmacophore atom pairs
+        which are present and have non-zero count. However, for *FixedSize*
+        value of AtomPairsSetSizeToUse, the fingerprint vector contains all
+        possible valid topological pharmacophore atom pairs with both zero
+        and non-zero count values.
+
+    SetAtomTypesToUse
+            $TopologicalPharmacophoreAtomPairsFP->SetAtomTypesToUse($ValuesRef);
+            $TopologicalPharmacophoreAtomPairsFP->SetAtomTypesToUse(@Values);
+
+        Sets pharmacophore atom types to use for topological pharmacophore
+        fingerprints generation and returns
+        *TopologicalPharmacophoreAtomPairsFingerprints*.
+
+        Possible values for pharmacophore atom types are: *Ar, CA, H, HBA,
+        HBD, Hal, NI, PI, RA*. Default value [ Ref 60-62 ] :
+        *HBD,HBA,PI,NI,H*.
+
+        The pharmacophore atom types abbreviations correspond to:
+
+            HBD: HydrogenBondDonor
+            HBA: HydrogenBondAcceptor
+            PI :  PositivelyIonizable
+            NI : NegativelyIonizable
+            Ar : Aromatic
+            Hal : Halogen
+            H : Hydrophobic
+            RA : RingAtom
+            CA : ChainAtom
+
+        *AtomTypes::FunctionalClassAtomTypes* module is used to assign
+        pharmacophore atom types. It uses following definitions [ Ref 60-61,
+        Ref 65-66 ]:
+
+            HydrogenBondDonor: NH, NH2, OH
+            HydrogenBondAcceptor: N[!H], O
+            PositivelyIonizable: +, NH2
+            NegativelyIonizable: -, C(=O)OH, S(=O)OH, P(=O)OH
+
+    SetAtomTypesWeight
+            $TopologicalPharmacophoreAtomPairsFP->SetAtomTypesWeight(
+                %AtomTypesToWeight);
+
+        Sets weights of specified pharmacophore atom types to use during
+        calculation of their contribution to atom pair count and returns
+        *TopologicalPharmacophoreAtomPairsFP*. Default values: *1 for each
+        atom type*.
+
+        The weight values allow to increase the importance of specific
+        pharmacophore atom type in the generated fingerprints. A weight
+        value of 0 for an atom type eliminates its contribution to atom pair
+        count where as weight value of 2 doubles its contribution.
+
+    SetFuzzFactor
+            $TopologicalPharmacophoreAtomPairsFP->SetFuzzFactor($Value);
+
+        Sets fuzz factor value to use during fuzzification of atom pairs
+        count and returns *TopologicalPharmacophoreAtomPairsFP*. Default
+        value: *0.15*.
+
+        Valid values: For *FuzzyBinning* value of FuzzificationMethodology:
+        *between 0 and 1.0*; For *FuzzyBinSmoothing* value of
+        FuzzificationMethodology: *between 0 and 0.5*.
+
+    SetFuzzificationMethodology
+            $TopologicalPharmacophoreAtomPairsFP->SetFuzzificationMethodology($Value);
+
+        Sets fuzzification methodology to use for fuzzification of atom
+        pairs count and returns *TopologicalPharmacophoreAtomPairsFP*.
+        Default value: *FuzzyBinning*. Possible values: *FuzzyBinning |
+        FuzzyBinSmoothing*.
+
+        In conjunction with values for options FuzzifyAtomPairsCount,
+        FuzzificationMode and FuzzFactor, FuzzificationMethodology option is
+        used to fuzzify pharmacophore atom pairs count.
+
+        Let:
+
+            Px = Pharmacophore atom type x
+            Py = Pharmacophore atom type y
+            PPxy = Pharmacophore atom pair between atom type Px and Py
+
+            PPxyDn = Pharmacophore atom pairs count between atom type Px and Py
+                     at distance Dn
+            PPxyDn-1 = Pharmacophore atom pairs count between atom type Px and Py
+                       at distance Dn - 1
+            PPxyDn+1 = Pharmacophore atom pairs count between atom type Px and Py
+                       at distance Dn + 1
+
+            FF = FuzzFactor for FuzzyBinning and FuzzyBinSmoothing
+
+        Then:
+
+        For *FuzzyBinning*:
+
+            PPxyDn = PPxyDn (Unchanged)
+
+            PPxyDn-1 = PPxyDn-1 + PPxyDn * FF
+            PPxyDn+1 = PPxyDn+1 + PPxyDn * FF
+
+        For *FuzzyBinSmoothing*:
+
+            PPxyDn = PPxyDn - PPxyDn * 2FF for Dmin < Dn < Dmax
+            PPxyDn = PPxyDn - PPxyDn * FF for Dn = Dmin or Dmax
+
+            PPxyDn-1 = PPxyDn-1 + PPxyDn * FF
+            PPxyDn+1 = PPxyDn+1 + PPxyDn * FF
+
+        In both fuzzification schemes, a value of 0 for FF implies no
+        fuzzification of occurrence counts. A value of 1 during
+        *FuzzyBinning* corresponds to maximum fuzzification of occurrence
+        counts; however, a value of 1 during *FuzzyBinSmoothing* ends up
+        completely distributing the value over the previous and next
+        distance bins.
+
+        So for default value of FuzzFactor (FF) 0.15, the occurrence count
+        of pharmacohore atom pairs at distance Dn during FuzzyBinning is
+        left unchanged and the counts at distances Dn -1 and Dn + 1 are
+        incremented by PPxyDn * 0.15.
+
+        And during *FuzzyBinSmoothing* the occurrence counts at Distance Dn
+        is scaled back using multiplicative factor of (1 - 2*0.15) and the
+        occurrence counts at distances Dn -1 and Dn + 1 are incremented by
+        PPxyDn * 0.15. In other words, occurrence bin count is smoothed out
+        by distributing it over the previous and next distance value.
+
+    SetFuzzificationMode
+            $TopologicalPharmacophoreAtomPairsFP->SetFuzzificationMode($Value);
+
+        Sets fuzzification mode to use for fuzzification of atom pairs count
+        and returns *TopologicalPharmacophoreAtomPairsFP*. Default value:
+        *AfterNormalization*. Possible values: *BeforeNormalization |
+        AfterNormalization*.
+
+    SetMaxDistance
+            $TopologicalPharmacophoreAtomPairsFP->SetMaxDistance($Value);
+
+        Sets maximum bond distance between atom pairs for generating
+        topological pharmacophore atom pairs fingerprints and returns
+        *TopologicalPharmacophoreAtomPairsFP*.
+
+    SetMinDistance
+            $TopologicalPharmacophoreAtomPairsFP->SetMinDistance($Value);
+
+        Sets minimum bond distance between atom pairs for generating
+        topological pharmacophore atom pairs fingerprints and returns
+        *TopologicalPharmacophoreAtomPairsFP*.
+
+    SetNormalizationMethodology
+            $TopologicalPharmacophoreAtomPairsFP->SetNormalizationMethodology($Value);
+
+        Sets normalization methodology to use for scaling the occurrence
+        count of pharmacophore atom pairs within specified distance range
+        and returns *TopologicalPharmacophoreAtomPairsFP*. Default value:
+        *None*. Possible values: *None, ByHeavyAtomsCount or
+        ByAtomTypesCount*.
+
+    SetValuesPrecision
+            $TopologicalPharmacophoreAtomPairsFP->SetValuesPrecision($Value);
+
+        Sets precision of atom pairs count real values which might be
+        generated after normalization or fuzzification and returns
+        *TopologicalPharmacophoreAtomPairsFP*. Default: up to *2* decimal
+        places.
+
+    StringifyTopologicalPharmacophoreAtomPairsFingerprints
+            $String = $TopologicalPharmacophoreAtomPairsFP->
+                          StringifyTopologicalPharmacophoreAtomPairsFingerprints();
+
+        Returns a string containing information about
+        *TopologicalPharmacophoreAtomPairsFingerprints* object.
+
+AUTHOR
+    Manish Sud <[e-mail]>
+
+SEE ALSO
+    Fingerprints.pm, FingerprintsStringUtil.pm,
+    AtomNeighborhoodsFingerprints.pm, AtomTypesFingerprints.pm,
+    EStateIndiciesFingerprints.pm, ExtendedConnectivityFingerprints.pm,
+    MACCSKeys.pm, PathLengthFingerprints.pm,
+    TopologicalAtomPairsFingerprints.pm,
+    TopologicalAtomTripletsFingerprints.pm,
+    TopologicalAtomTorsionsFingerprints.pm,
+    TopologicalPharmacophoreAtomTripletsFingerprints.pm
+
+COPYRIGHT
+    Copyright (C) 2015 Manish Sud. All rights reserved.
+
+    This file is part of MayaChemTools.
+
+    MayaChemTools is free software; you can redistribute it and/or modify it
+    under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation; either version 3 of the License, or (at
+    your option) any later version.
+