diff lib/Fingerprints/Fingerprints.pm @ 0:4816e4a8ae95 draft default tip

Uploaded

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/Fingerprints/Fingerprints.pm	Wed Jan 20 09:23:18 2016 -0500
@@ -0,0 +1,602 @@
+package Fingerprints::Fingerprints;
+#
+# $RCSfile: Fingerprints.pm,v $
+# $Date: 2015/02/28 20:48:54 $
+# $Revision: 1.33 $
+#
+# Author: Manish Sud <[e-mail]>
+#
+# 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.
+#
+# MayaChemTools is distributed in the hope that it will be useful, but without
+# any warranty; without even the implied warranty of merchantability of fitness
+# for a particular purpose.  See the GNU Lesser General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with MayaChemTools; if not, see <http://www.gnu.org/licenses/> or
+# write to the Free Software Foundation Inc., 59 Temple Place, Suite 330,
+# Boston, MA, 02111-1307, USA.
+#
+
+use strict;
+use Carp;
+use Exporter;
+use Scalar::Util ();
+use ObjectProperty;
+use MathUtil ();
+use TextUtil ();
+use Fingerprints::FingerprintsBitVector;
+use Fingerprints::FingerprintsVector;
+
+use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
+
+@ISA = qw(ObjectProperty Exporter);
+@EXPORT = qw();
+@EXPORT_OK = qw();
+
+%EXPORT_TAGS = (all  => [@EXPORT, @EXPORT_OK]);
+
+# Setup class variables...
+my($ClassName);
+_InitializeClass();
+
+# Class constructor...
+sub new {
+  my($Class, %NamesAndValues) = @_;
+
+  # Initialize object...
+  my $This = {};
+  bless $This, ref($Class) || $Class;
+  $This->_InitializeFingerprints();
+
+  $This->_InitializeFingerprintsProperties(%NamesAndValues);
+
+  return $This;
+}
+
+# Initialize object data...
+#
+sub _InitializeFingerprints {
+  my($This) = @_;
+
+  # Molecule object...
+  $This->{Molecule} = '';
+
+  # Type of fingerprints...
+  $This->{Type} = '';
+
+  # Type of fingerprints vector: FingerprintsBitVector or FingerprintsVector...
+  $This->{VectorType} = '';
+
+  # Marks successful generation of fingerprints...
+  $This->{FingerprintsGenerated} = 0;
+
+  # Initialize values for FingerprintsBitVector...
+  _InitializeClassValuesForFingerprintsBitVector();
+
+  # Initialize values for FingerprintsVector...
+  _InitializeClassValuesForFingerprintsVector();
+}
+
+# Initialize class ...
+sub _InitializeClass {
+  #Class name...
+  $ClassName = __PACKAGE__;
+}
+
+# Initialize class values specific to FingerprintsBitVector...
+#
+sub _InitializeClassValuesForFingerprintsBitVector {
+  my($This) = @_;
+
+  # Size of FingerprintsBitVector...
+  $This->{Size} = '';
+
+  # Min/Max sizes used for folding FingerprintsBitVector...
+  $This->{MinSize} = '';
+  $This->{MaxSize} = '';
+
+  # FingerprintsBitVector...
+  $This->{FingerprintsBitVector} = '';
+}
+
+# Initialize class values specific to FingerprintsVector...
+#
+sub _InitializeClassValuesForFingerprintsVector {
+  my($This) = @_;
+
+  # Types of FingerprintsVector values: OrderedNumericalValues, NumericalValues or AlphaNumericalValues.
+  $This->{FingerprintsVectorType} = '';
+
+  # Fingerprints vector...
+  $This->{FingerprintsVector} = '';
+}
+
+# Initialize object properties....
+sub _InitializeFingerprintsProperties {
+  my($This, %NamesAndValues) = @_;
+
+  my($Name, $Value, $MethodName);
+  while (($Name, $Value) = each  %NamesAndValues) {
+    $MethodName = "Set${Name}";
+    $This->$MethodName($Value);
+  }
+
+  return $This;
+}
+
+# Set molecule object and make sure it's not already set...
+#
+sub SetMolecule {
+  my($This, $Molecule) = @_;
+
+  if ($This->{Molecule}) {
+    croak "Error: ${ClassName}->SetMolecule: Can't change molecule object:  It's already set...";
+  }
+  $This->{Molecule} = $Molecule;
+
+  # Weaken the reference to disable increment of reference count...
+  Scalar::Util::weaken($This->{Molecule});
+
+  return $This;
+}
+
+# Set type and make sure it's not already set...
+#
+sub SetType {
+  my($This, $Type) = @_;
+
+  if ($This->{Type}) {
+    croak "Error: ${ClassName}->SetType: Can't change fingerprint type:  It's already set...";
+  }
+  $This->{Type} = $Type;
+
+  return $This;
+}
+
+# Is fingerprints generation successful?
+#
+# Notes:
+#   . The specific fingerprints generation class sets the value of FingerprinsGenerated
+#     to 1 after the successful generation of fingerprints; otherwise, it's set to 0.
+#
+sub IsFingerprintsGenerationSuccessful {
+  my($This) = @_;
+
+  return $This->{FingerprintsGenerated} ? 1 : 0;
+}
+
+# Set vector type and make sure it's not already set...
+#
+sub SetVectorType {
+  my($This, $VectorType) = @_;
+
+  if ($This->{VectorType}) {
+    croak "Error: ${ClassName}->SetVectorType: Can't change fingerprint vector type:  It's already set...";
+  }
+  if ($VectorType !~ /^(FingerprintsBitVector|FingerprintsVector)$/i) {
+    croak "Error: ${ClassName}->SetVectorType: Specified value, $VectorType, for Type is not vaild. Supported types in current release of MayaChemTools: FingerprintsBitVector and FingerprintsVector...";
+  }
+  $This->{VectorType} = $VectorType;
+
+  return $This;
+}
+
+#
+# Methods/functions for FingerprintsBitVector...
+#
+
+# Initialize fingerprint bit vector...
+sub _InitializeFingerprintsBitVector {
+  my($This) = @_;
+
+  if ($This->{VectorType} !~ /^FingerprintsBitVector$/i) {
+    croak "Error: ${ClassName}->_InitializeFingerprintsBitVector: Can't initialize fingerprints bit vector: VectorType must be FingerprintsBitVector...";
+  }
+
+  if ($This->{Size}) {
+    $This->{FingerprintsBitVector} = new Fingerprints::FingerprintsBitVector($This->{Size});
+  }
+  return $This;
+}
+
+# Set size...
+#
+sub SetSize {
+  my($This, $Size) = @_;
+
+  if ($This->{MinSize} && $Size < $This->{MinSize}) {
+    croak "Error: ${ClassName}->SetSize: Fingerprint size value, $Size, is not valid :  It must be >= $This->{MinSize}...";
+  }
+  if ($This->{MaxSize} && $Size > $This->{MaxSize}) {
+    croak "Error: ${ClassName}->SetSize: Fingerprint size value, $Size, is not valid:  It must be <= $This->{MaxSize}...";
+  }
+
+  $This->{Size} = $Size;
+
+  return $This;
+}
+
+# Set FingerprintsBitVector object and make sure it's not already set...
+#
+sub SetFingerprintsBitVector {
+  my($This, $FingerprintsBitVector) = @_;
+
+  if ($This->{FingerprintsBitVector}) {
+    croak "Error: ${ClassName}->SetFingerprintsBitVector: Can't change FingerprintsBitVector object:  It's already set...";
+  }
+  $This->{FingerprintsBitVector} = $FingerprintsBitVector;
+
+  return $This;
+}
+
+# Fold fingerprints by recursively reducing its size by half untill bit density is greater than or equal to
+# specified bit density...
+#
+sub FoldFingerprintsByBitDensity {
+  my($This, $BitDensity) = @_;
+
+  if (!($BitDensity >= 0 && $BitDensity <= 1)) {
+    croak "Error: ${ClassName}->FoldFingerprintsByBitDensity: Specified bit density, $BitDensity, is not valid:  It must be > 0 && <= 1 ...";
+  }
+
+  return $This->_FoldFingerprintsBitVector('ByDensity', $BitDensity);
+}
+
+# Fold fingerprints by recursively reducing its size by half untill size is less than or equal to
+# specified size...
+#
+sub FoldFingerprintsBySize {
+  my($This, $Size, $CheckSizeValue) = @_;
+
+  if (!defined $CheckSizeValue) {
+    $CheckSizeValue = 1;
+  }
+
+  if ($CheckSizeValue) {
+    if (!TextUtil::IsPositiveInteger($Size)) {
+      croak "Error: ${ClassName}->FoldFingerprintsBySize: Specified size, $Size, is not valid:  It must be a positive integer";
+    }
+    if (!($Size >= $This->{MinSize} && $Size < $This->{Size})) {
+      croak "Error: ${ClassName}->FoldFingerprintsBySize: Specified size, $Size, is not valid:  It must be greater than or equal to minimum size of $This->{MinSize} and less than current size of $This->{Size}...";
+    }
+    if (!TextUtil::IsNumberPowerOfNumber($Size, 2)) {
+      croak "Error: ${ClassName}->FoldFingerprintsBySize: Specified size value, $Size, must be power of 2...";
+    }
+  }
+
+  return $This->_FoldFingerprintsBitVector('BySize', $Size);
+}
+
+# Fold fingerprints bit vector using specified size of bit density...
+#
+sub _FoldFingerprintsBitVector {
+  my($This, $Mode, $Value) = @_;
+
+  if (!$This->{FingerprintsBitVector}) {
+    return $This;
+  }
+  my($FingerprintsBitVector, $FoldedFingerprintsBitVector);
+
+  $FoldedFingerprintsBitVector = '';
+  $FingerprintsBitVector = $This->{FingerprintsBitVector};
+  MODE: {
+    if ($Mode =~ /^BySize$/i) { $FoldedFingerprintsBitVector = $FingerprintsBitVector->FoldFingerprintsBitVectorBySize($Value); last MODE; }
+    if ($Mode =~ /^ByDensity$/i) { $FoldedFingerprintsBitVector = $FingerprintsBitVector->FoldFingerprintsBitVectorByDensity($Value); last MODE; }
+    $FoldedFingerprintsBitVector = '';
+  }
+  if ($FoldedFingerprintsBitVector) {
+    $This->{FingerprintsBitVector} = $FoldedFingerprintsBitVector;
+    $This->{Size} = $FoldedFingerprintsBitVector->GetSize();
+  }
+  return $This;
+}
+
+# Get fingerprints as a binary ascii string containing 0s and 1s...
+#
+sub GetFingerprintBitsAsBinaryString {
+  my($This, $BitOrder) = @_;
+
+  return $This->_GetFingerprintBitsAsString('Binary', $BitOrder);
+}
+
+# Get fingerprints as a hexadecimal string...
+#
+sub GetFingerprintBitsAsHexadecimalString {
+  my($This, $BitOrder) = @_;
+
+  return $This->_GetFingerprintBitsAsString('Hexadecimal', $BitOrder);
+}
+
+# Get fingerprints as a raw binary string containing packed bit values for each
+# byte...
+#
+sub GetFingerprintBitsAsRawBinaryString {
+  my($This, $BitOrder) = @_;
+
+  return $This->_GetFingerprintBitsAsString('RawBinary', $BitOrder);
+}
+
+# Get fingerprint bits as a string...
+#
+sub _GetFingerprintBitsAsString {
+  my($This, $Format) = @_;
+
+  if (!$This->{FingerprintsBitVector}) {
+    return undef;
+  }
+  FORMAT : {
+    if ($Format =~ /^(Binary|Bin|BinaryString)$/i) { return $This->{FingerprintsBitVector}->GetBitsAsBinaryString(); last FORMAT; }
+    if ($Format =~ /^(Hexadecimal|Hex|HexadecimalString)$/i) { return $This->{FingerprintsBitVector}->GetBitsAsHexadecimalString(); last FORMAT; }
+    if ($Format =~ /^(RawBinary|RawBin|RawBinaryString)$/i) { return $This->{FingerprintsBitVector}->GetBitsAsRawBinaryString(); last FORMAT; }
+    croak "Error: ${ClassName}->_GetFingerprintBitsAsString: Specified bit vector string format, $Format, is not supported. Value values: Binary, Bin, BinaryString, Hexdecimal, Hex, HexadecimalString, RawBinary, RawBin, RawBinaryString...";
+  }
+  return undef;
+}
+
+#
+# Methods/functions for FingerprintsVector...
+#
+
+# Initialize fingerprint vector...
+sub _InitializeFingerprintsVector {
+  my($This) = @_;
+
+  if ($This->{VectorType} !~ /^FingerprintsVector$/i) {
+    croak "Error: ${ClassName}->_InitializeFingerprintsVector: Can't initialize fingerprints vector: VectorType must be FingerprintsVector...";
+  }
+
+  if ($This->{FingerprintsVectorType}) {
+    $This->{FingerprintsVector} = new Fingerprints::FingerprintsVector('Type' => $This->{FingerprintsVectorType});
+  }
+  return $This;
+}
+
+# Set FingerprintsVector object and make sure it's not already set...
+#
+sub SetFingerprintsVector {
+  my($This, $FingerprintsVector) = @_;
+
+  if ($This->{FingerprintsVector}) {
+    croak "Error: ${ClassName}->SetFingerprintsVector: Can't change FingerprintsVector object:  It's already set...";
+  }
+  $This->{FingerprintsVector} = $FingerprintsVector;
+
+  return $This;
+}
+
+# Types of FingerprintsVector values: OrderedNumericalValues, NumericalValues or AlphaNumericalValues.
+#
+sub SetFingerprintsVectorType {
+  my($This, $FingerprintsVectorType) = @_;
+
+  if ($This->{FingerprintsVectorType}) {
+    croak "Error: ${ClassName}->SetFingerprintsVector: Can't change FingerprintsVectorType:  It's already set...";
+  }
+  if ($FingerprintsVectorType !~ /^(OrderedNumericalValues|NumericalValues|AlphaNumericalValues)$/i) {
+    croak "Error: ${ClassName}->SetFingerprintsVectorType: Specified value, $FingerprintsVectorType, for Type is not vaild. Supported types in current release of MayaChemTools: OrderedNumericalValues, NumericalValues or AlphaNumericalValues";
+  }
+  $This->{FingerprintsVectorType} = $FingerprintsVectorType;
+
+  return $This;
+}
+
+# Get fingerprints vector values as an array or reference to an array...
+#
+sub GetFingerprintsVectorValues {
+  my($This) = @_;
+
+  if (!$This->{FingerprintsVector}) {
+    return undef;
+  }
+  return $This->{FingerprintsVector}->GetValues();
+}
+
+# Get fingerprints vector value IDs as an array or reference to an array...
+#
+sub GetFingerprintsVectorValueIDs {
+  my($This) = @_;
+
+  if (!$This->{FingerprintsVector}) {
+    return undef;
+  }
+  return $This->{FingerprintsVector}->GetValueIDs();
+}
+
+1;
+
+__END__
+
+=head1 NAME
+
+Fingerprints - Fingerprints class
+
+=head1 SYNOPSIS
+
+use Fingerprints::Fingerprints;
+
+use Fingerprints::Fingerprints qw(:all);
+
+=head1 DESCRIPTION
+
+B<Fingerprints> class provides the following methods:
+
+new, FoldFingerprintsByBitDensity, FoldFingerprintsBySize,
+GetFingerprintBitsAsBinaryString, GetFingerprintBitsAsHexadecimalString,
+GetFingerprintBitsAsRawBinaryString, GetFingerprintsVectorValueIDs,
+GetFingerprintsVectorValues, IsFingerprintsGenerationSuccessful,
+SetFingerprintsBitVector, SetFingerprintsVector, SetFingerprintsVectorType,
+SetMolecule, SetSize, SetType, SetVectorType
+
+B<Fingerprints> class is used as a base class for various specific fingerprint classes such as
+B<AtomNeighborhoodsFingerprints>, B<AtomTypesFingerprints>, B<EStateIndiciesFingerprints>,
+B<PathLengthFingerprints>, B<ExtendedConnectivityFingerprints>, B<MACCSKeys> and so on.
+It implements functionality common to fingerprint classes.
+
+B<Fingerprints> class is  derived from B<ObjectProperty> base class which provides methods not
+explicitly defined in B<Fingerprints> or B<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>();
+
+B<Fingerprints> class uses B<FingerprintsBitVector> class to provide bits manipulation functionality.
+
+=head2 METHODS
+
+=over 4
+
+=item B<new>
+
+    $NewFingerprints = new Fingerprints(%NamesAndValues);
+
+Using specified I<Fingerprints> property names and values hash, B<new> method creates a new object
+and returns a reference to newly created B<Fingerprints> object. By default, following properties are
+initialized:
+
+    Molecule = '';
+    Type = '';
+    VectorType = '';
+    Size = '';
+    MinSize = '';
+    MaxSize = '';
+    FingerprintsBitVector = '';
+    FingerprintsVectorType = '';
+    FingerprintsVector = '';
+
+=item B<FoldFingerprintsByBitDensity>
+
+    $Fingerprints->FoldFingerprintsByBitDensity($BitDensity);
+
+Folds fingerprints by recursively reducing its size by half until bit density is greater than or equal to
+specified I<BitDensity> and returns I<Fingerprints>.
+
+=item B<FoldFingerprintsBySize>
+
+    $Fingerprints->FoldFingerprintsBySize($Size, [$CheckSizeValue]);
+
+Fold fingerprints by recursively reducing its size by half until size is less than or equal to specified
+I<Size> and returns I<Fingerprints>. By default, value I<Size> is checked to make sure it's:
+
+    >= MinSize and < Size and IsPowerOfTwo
+
+=item B<GetFingerprintBitsAsBinaryString>
+
+    $BinaryASCIIString =
+       $Fingerprints->GetFingerprintBitsAsBinaryString();
+
+Returns fingerprints as a binary ASCII string containing 0s and 1s.
+
+=item B<GetFingerprintBitsAsHexadecimalString>
+
+    $HexadecimalString =
+       $Fingerprints->GetFingerprintBitsAsHexadecimalString();
+
+Returns fingerprints as a hexadecimal string
+
+=item B<GetFingerprintBitsAsRawBinaryString>
+
+    $RawBinaryString =
+       $Fingerprints->GetFingerprintBitsAsRawBinaryString();
+
+Returns fingerprints as a raw binary string containing packed bit values for each byte.
+
+=item B<GetFingerprintsVectorValueIDs>
+
+    $ValueIDsRef = $Fingerprints->GetFingerprintsVectorValueIDs();
+    @ValueIDs = $Fingerprints->GetFingerprintsVectorValueIDs();
+
+Returns fingerprints vector value IDs as an array or reference to an array.
+
+=item B<GetFingerprintsVectorValues>
+
+    $ValuesRef = $Fingerprints->GetFingerprintsVectorValues();
+    @Values = $Fingerprints->GetFingerprintsVectorValues();
+
+Returns fingerprints vector values as an array or reference to an array.
+
+=item B<IsFingerprintsGenerationSuccessful>
+
+    $Return = $Fingerprints->IsFingerprintsGenerationSuccessful();
+
+Returns 1 or 0 based on whether fingerprints were successfully generated.
+
+=item B<SetFingerprintsBitVector>
+
+    $Fingerprints->SetFingerprintsBitVector($FingerprintsBitVector);
+
+Sets I<FingerprintsBitVector> object for I<Fingerprints> and returns I<Fingerprints>.
+
+=item B<SetFingerprintsVector>
+
+    $Fingerprints->SetFingerprintsVector();
+
+Sets I<FingerprintsVector> object for I<Fingerprints> and returns I<Fingerprints>.
+
+=item B<SetFingerprintsVectorType>
+
+    $Fingerprints->SetFingerprintsVectorType($VectorType);
+
+Sets I<FingerprintsVector> type for I<Fingerprints> and returns I<Fingerprints>. Possible
+I<VectorType> values: I<OrderedNumericalValues, NumericalValues or AlphaNumericalValues>.
+
+=item B<SetMolecule>
+
+    $Fingerprints->SetMolecule($Molecule);
+
+Sets I<Molecule> object for I<Fingerprints> and returns I<Fingerprints>.
+
+=item B<SetSize>
+
+    $Fingerprints->SetSize($Size);
+
+Sets I<Size> of fingerprints and returns I<Fingerprints>.
+
+=item B<SetType>
+
+    $Fingerprints->SetType($Type);
+
+Sets I<Type> of fingerprints and returns I<Fingerprints>.
+
+=item B<SetVectorType>
+
+    $Fingerprints->SetVectorType($Type);
+
+Sets I<Type> of fingerprints vector and returns I<Fingerprints>. Possible I<Type> values:
+I<FingerprintsBitVector or FingerprintsVector>.
+
+=back
+
+=head1 AUTHOR
+
+Manish Sud <[e-mail]>
+
+=head1 SEE ALSO
+
+FingerprintsStringUtil.pm, AtomNeighborhoodsFingerprints.pm, AtomTypesFingerprints.pm,
+EStateIndiciesFingerprints.pm, ExtendedConnectivityFingerprints.pm, MACCSKeys.pm,
+PathLengthFingerprints.pm, TopologicalAtomPairsFingerprints.pm, TopologicalAtomTripletsFingerprints.pm,
+TopologicalAtomTorsionsFingerprints.pm, TopologicalPharmacophoreAtomPairsFingerprints.pm,
+TopologicalPharmacophoreAtomTripletsFingerprints.pm
+
+=head1 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.
+
+=cut