weighted_list_rank 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 801eb04183d7dec5f99bfbcb76a902a920dcfee105f83f0c0c9a98667b73e6e4
-  data.tar.gz: c5c5665b7205bc0fd52c4c7d23f34103ba2dfd764579e0a575897f8ce36e95af
+  metadata.gz: 02c97cc567dfd099a6f65066c534b3780d1a8ca7f8b6a2148d6410c348ed6db9
+  data.tar.gz: 235f31a73f88b44485d5c5a0fae360d6f4fe2a417e380ddaccadfa214af4d5d6
 SHA512:
-  metadata.gz: 210d7a10b0978195b26a0fd3cbdfd068b93e09066ac332984e165d011170abb544837fc4aafd6cb410055bd7b412199733ca2d37e1190630aa5bd650f8f5df9a
-  data.tar.gz: 65adb83584d5b1ec5d2282a0f8411edb147eb700f3030e9ab4c80def5ca8d2d7963166091cda87e8ea8a603a1c7f7168d28b661c2cbf0a4c6807b3617c47551c
+  metadata.gz: e908050bff4073ce084cc6b20a30992a52a08d93dc2732ae4e891605d2dc3c761166a79e90093ddb5b345ebe9da344c4ebe430fd9d9e1b780bccced0d4ee97fb
+  data.tar.gz: 67fa8168ec949cbdcb3c1dc728d8461ae0a4bf51234cef9d251eaf10b63eb8ca617d55945a719ea297cfe24c42a1ab89c871f8f090af601c97ec21f22b0c2b6f

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [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

data/lib/weighted_list_rank/strategies/exponential.rb

@@ -1,28 +1,52 @@
 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. 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. 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.
+      #
+      # @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.
-      # The bonus pool is set to 50% of the list's weight.
+      # 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)
         # 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 * 0.5  # Bonus pool is 50% of the list's weight
+        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

data/lib/weighted_list_rank/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WeightedListRank
-  VERSION = "0.2.0"
+  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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Shane Sherman