pdist 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d7ebb3f205b20de1c6d95cd2b23258859ce4f2a1
-  data.tar.gz: f58d113cdeecbc627cca8cdc91ce2714bc11d51e
+  metadata.gz: 8f6118cbd2a20a7657698ccb221e3eca96f0b06c
+  data.tar.gz: 595fa6bc50c46f3ea10c70236b3a6e3a47e39012
 SHA512:
-  metadata.gz: 55212a0b26ece1011645ae268e21ede6d83c66a6b6b6e14364cbed7d1129f81161fab03f21114ced284116d027926bb8e33696890f71466c33d95998702da7a1
-  data.tar.gz: af1e3ce555ee46312068c7ee0e3c9dfbe121260e75ecb5ef2ce4c72ddac5b04c113d9fc236773edc7dd476cab0bef10a464d1571e1d9928dc7702e8d2b249748
+  metadata.gz: d0f6b88bdd1b539087fa21eefffd16eb382e3b5879dbf3573fcfc08e07488a0296693824d8e3c6a6f9be14aedcbcf4879002c25ec4b9726f8173d1324e9b68c4
+  data.tar.gz: de356c84860ba351714b360bc88dc833632feb4802bf186b797b639971fbff39929b6bf3a8de5854328c18d98f2f66ff3f5eb0d71edc8e01608f2bef552c9f8c

data/lib/pdist.rb

@@ -3,38 +3,41 @@ class PDist
 
 	require 'diff/lcs'
 
+	# Returns array of values for each object's deviation in permutation, from original
 	def self.distances(original, permutation)
-		both, difference_abs = [], []
-		both << original.map{|x| permutation.index(x)} # works out the index of original values in permutation
-		both << Array(0..(original.length - 1)) # index values that original originally at
-		difference = both.transpose.map {|x| x.reduce(:-)} # taking away old position from new position, to find the distance that the frag has moved when re-ordered
-		difference.each {|i| difference_abs << i.abs }
-		return difference_abs
+		indices = []
+		indices << original.map{|x| permutation.index(x)} # indices of original values in permutation
+		indices << Array(0..(original.length - 1)) # indices of original values in original
+		difference = indices.transpose.map {|x| x.reduce(:-)} # subtracting each object's index in original, from it's index in permutation, to find deviation
+		return difference.map! {|i| i.abs } # the deviation's, as absolute values (direction does not matter)
 	end
 
+	# Returns float of the deviation distance between original and permutation, normalized between 0.0 and 1.0
 	def self.deviation(original, permutation)
-		s = distances(original, permutation).inject(:+)
+		s = distances(original, permutation).inject(:+) # sum of each object's deviation, is the deviation distance between original and permutation
 		n = permutation.length
-		if n % 2 == 0
-			score = (2.0 / (n ** 2).to_f) * s
+		if n % 2 == 0 
+			distance = (2.0 / (n ** 2).to_f) * s
 		else
-			score = (2.0 / ((n ** 2) - 1).to_f) * s
+			distance = (2.0 / ((n ** 2) - 1).to_f) * s
 		end
-		return score
+		return distance # if/else block normalizes the deviation distance
 	end
 
+	# Returns float of the squared deviation distance between original and permutation, normalized between 0.0 and 1.0
 	def self.square(original, permutation)
 		sq_dists = []
-		distances(original, permutation).each{|d| sq_dists << d**2}
-		s = sq_dists.inject(:+)
+		distances(original, permutation).each{|d| sq_dists << d**2} # each object's deviation is squared
+		s = sq_dists.inject(:+) # sum of each object's squared deviation, is the squared deviation distance between original and permutation
 		n = permutation.length
-		return (3.0 / (n**3 - n).to_f) * s
+		return (3.0 / (n**3 - n).to_f) * s # normalizes the squared deviation distance
 	end
 
-	def self.ham_dist(original, permutation)
+	# Returns float of the generalized hamming distance between original and permutation, normalized between 0.0 and 1.0 
+	def self.hamming(original, permutation)
 		x = 0
 		hds = [] # hamming distances
-		permutation.each do |frag_id|
+		permutation.each do |frag_id| # hamming distances are 0 when object's have same index in original and permutation, and 1 when not
 			if frag_id == original[x]
 				hds << 0
 			else
@@ -42,18 +45,16 @@ class PDist
 			end
 			x+=1
 		end
-		return hds.inject(:+)
+		total_hd = hds.inject(:+).to_f # total hamming distance is the sum of the hamming distances
+		return total_hd / permutation.length.to_f # normalizes by dividing the total hamming distance by the maximum possible total, which == number of objects
 	end
 
-	def self.hamming(original, permutation) # generalized hamming distance
-		ham_dist(original, permutation).to_f / permutation.length.to_f # normalize by dividing by the max score, which == number of objects
-	end
-
-	def self.rdist(original, permutation) # reverse R distance (since higher scores = bad)
+	# Returns float of the compliment R distance between original and permutation, normalized between 0.0 and 1.0
+	def self.rdist(original, permutation)
 		x = 0
-		r = []
+		r = [] # compliment of R distance == number of times two objects consecutive in original, are consectutive in permutation
 		n = permutation.length
-		(n - 1).times do
+		(n - 1).times do 
 			y = permutation.index(original[x])
 			if original[x+1] == permutation[y+1]
 				r << 0
@@ -62,14 +63,16 @@ class PDist
 			end
 			x+=1
 		end
-		return r.inject(:+).to_f / (n - 1).to_f
+		return r.inject(:+).to_f / (n - 1).to_f # normalized: dividing by maximum number of consecutive occurences
 	end
 
+	# Returns float of the longest common sub-sequence between original and permutation, normalized between 0.0 and 1.0
 	def self.lcs(original, permutation)
-		lcs = Diff::LCS.LCS(original, permutation)
-		return (permutation.length - lcs.length).to_f / (permutation.length - 1).to_f
+		lcs = Diff::LCS.LCS(original, permutation) # diff-lcs gem used to calculate longest common sub-sequence
+		return (permutation.length - lcs.length).to_f / (permutation.length - 1).to_f # normalized: dividing by longest possible common sub-sequence
 	end
 
+	# Returns float of the kendall's tau distance between original and permutation, normalized between 0.0 and 1.0
 	def self.kendalls_tau(original, permutation)
 		n = permutation.length
 		x = 0
@@ -86,7 +89,7 @@ class PDist
 			end
 			x+=1
 		end
-		s = kt.inject(:+)
-		return 2 * (s.to_f / (n**2 - n).to_f)
+		s = kt.inject(:+) # the number of pairwise adjacent permutations required to transform original into permutation
+		return 2 * (s.to_f / (n**2 - n).to_f) # normalized kendall's tau distance
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pdist
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Edward Chalstrey
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-16 00:00:00.000000000 Z
+date: 2014-04-28 00:00:00.000000000 Z
 dependencies: []
 description: 'Ruby gem to compare permutations using distance measures/metrics. github:
   https://github.com/edwardchalstrey1/pdist'