weighted_list_rank 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a649927ba7b5ed331d9721b6a9ba7aa044017956b0aec6484649ee7c9d8d55e1
-  data.tar.gz: '01833e4d548f1df8c2428dcce387bf57652c91ea1bf53044420d8720e2137d10'
+  metadata.gz: 02c97cc567dfd099a6f65066c534b3780d1a8ca7f8b6a2148d6410c348ed6db9
+  data.tar.gz: 235f31a73f88b44485d5c5a0fae360d6f4fe2a417e380ddaccadfa214af4d5d6
 SHA512:
-  metadata.gz: 4fec2c7d118e678ee0284e9db56e99125681f5d67268250a3e0db142ea76edf1e9dd58f9b0c53fdfdb3f560feb25e5a731fb33ad71164f0ab45e9ca601ec9be4
-  data.tar.gz: d24a0349aeec1813215a3b842a22729de2f90c144a75944872bf000e46008567fee30d8fccfb1b209051cf34d54a616c1faa5411ac2f135d9cfc2bc5eef7371e
+  metadata.gz: e908050bff4073ce084cc6b20a30992a52a08d93dc2732ae4e891605d2dc3c761166a79e90093ddb5b345ebe9da344c4ebe430fd9d9e1b780bccced0d4ee97fb
+  data.tar.gz: 67fa8168ec949cbdcb3c1dc728d8461ae0a4bf51234cef9d251eaf10b63eb8ca617d55945a719ea297cfe24c42a1ab89c871f8f090af601c97ec21f22b0c2b6f

data/CHANGELOG.md

@@ -1,8 +1,16 @@
 ## [Unreleased]
 
+## [0.3.0] - 2024-02-03
+
+- added bonus_pool_percentage feature to expoential
+
+## [0.2.0] - 2024-02-03
+
+- refactored the exponential algorithm to only add bonus points out of a pool of 50% of a list's weight
+
 ## [0.1.3] - 2024-02-03
 
-- sprt the score_details by the highest score from each list first
+- sort the score_details by the highest score from each list first
 
 ## [0.1.2] - 2024-02-03
 

data/lib/weighted_list_rank/strategies/exponential.rb

@@ -2,10 +2,13 @@ module WeightedListRank
   module Strategies
     # The Exponential strategy calculates the score of an item within a list using an exponential formula.
     # This strategy emphasizes the significance of an item's rank within the list, where items with higher
-    # ranks (closer to 1) are exponentially more valuable than those with lower ranks.
+    # ranks (closer to 1) are exponentially more valuable than those with lower ranks. The magnitude of the bonus
+    # applied to each item's score is determined by the bonus pool percentage of the list's total weight.
     #
     # The exponential nature of the calculation is controlled by the +exponent+ attribute, allowing for
-    # flexible adjustment of how steeply the score decreases as rank increases.
+    # flexible adjustment of how steeply the score decreases as rank increases. The +bonus_pool_percentage+
+    # attribute determines the size of the bonus pool as a percentage of the list's total weight, allowing
+    # customization of the bonus impact on the final scores.
     class Exponential < WeightedListRank::Strategy
       # The exponent used in the score calculation formula. Higher values increase the rate at which
       # scores decrease as item rank increases.
@@ -13,32 +16,47 @@ module WeightedListRank
       # @return [Float] the exponent value
       attr_reader :exponent
 
-      # Initializes a new instance of the Exponential strategy with an optional exponent.
+      # The percentage of the list's total weight that constitutes the bonus pool. This value determines
+      # how the total bonus pool is calculated as a percentage of the list's weight.
       #
+      # @return [Float] the bonus pool percentage, defaulting to 1.0 (100% of the list's weight).
+      attr_reader :bonus_pool_percentage
+
+      # Initializes a new instance of the Exponential strategy with optional parameters for exponent and
+      # bonus pool percentage.
       # @param exponent [Float] the exponent to use in the score calculation formula, defaults to 1.5.
-      def initialize(exponent: 1.5)
+      # @param bonus_pool_percentage [Float] the percentage of the list's weight to be used as the bonus pool,
+      # defaults to 1.0 (100%).
+      def initialize(exponent: 1.5, bonus_pool_percentage: 1.0)
         @exponent = exponent
+        @bonus_pool_percentage = bonus_pool_percentage
       end
 
       # Calculates the score of an item within a list based on its rank position, the total number of items,
-      # and the list's weight, using an exponential formula.
+      # and the list's weight, using an exponential formula. The bonus pool for score adjustments is determined
+      # by the specified bonus pool percentage of the list's total weight.
       #
       # @param list [WeightedListRank::List] the list containing the item being scored.
       # @param item [WeightedListRank::Item] the item for which to calculate the score.
       #
-      # @return [Float] the calculated score for the item, adjusted by the list's weight and the specified exponent.
+      # @return [Float] the calculated score for the item, adjusted by the list's weight, the specified exponent,
+      # and the bonus pool percentage.
       def calculate_score(list, item)
-        rank_position = item.position
-
-        # if there are no positions, then just return the list weight
-        return list.weight if rank_position.nil?
+        # Return the list weight if there are no positions
+        return list.weight if item.position.nil?
 
         num_items = list.items.count
+        total_bonus_pool = list.weight * bonus_pool_percentage
+
+        # Calculate the exponential factor for the item's rank position
+        exponential_factor = (num_items + 1 - item.position)**exponent
+        total_exponential_factor = (1..num_items).sum { |pos| (num_items + 1 - pos)**exponent }
+
+        # Allocate a portion of the total bonus pool based on the item's exponential factor
+        item_bonus = (exponential_factor / total_exponential_factor) * total_bonus_pool
 
-        contribution = ((num_items + 1 - rank_position)**exponent) / num_items.to_f
-        scaled_contribution = contribution / num_items
-        bonus = scaled_contribution * list.weight
-        list.weight + bonus
+        # The final score is the list's weight plus the item's allocated bonus
+        list.weight + item_bonus
       end
     end
   end

data/lib/weighted_list_rank/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WeightedListRank
-  VERSION = "0.1.3"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: weighted_list_rank
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Shane Sherman