weighted_list_rank 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5d85e4ccc5456ad1bce7763d39d34d4dc14f831806b9c9bcee94f0c4d926898
-  data.tar.gz: dcf0013d694ce996c21335ed6d56d29f7dad96c03376e9a49ede00ae634c980b
+  metadata.gz: 3c2d9ea8239b54fa7d9423a36ae922c9de54a4bee54d8df0fdc17847b98eb60d
+  data.tar.gz: '03808fac0b2fd206b726734eeca8f3a62ad9b3aeab51f58237f22561775d4dbf'
 SHA512:
-  metadata.gz: 6983978ad5b4b876e6e47100ec1134aa937606d5ba0a7bafcfd235c7a737b1f84063f7ee3b8bb19f1b56521cd7e6d53196fd15ef64c2f040b90ac8facf50354e
-  data.tar.gz: bc4fe3145c9f563c69fc13a718c65ba0696473a134b23fa46b960ffd0952c9a1ad775502e402f798661f758d9b63a745a3fa3dd953402e34e7ae854782da6d64
+  metadata.gz: 590693e2ea27c84cf861ba36dacfc50f97374f5b12c47b1b6f72693f6652a92d875c5d9a56090809ffeefc2b91e17e76e2288586d3bbd01baa408c3cbbcb91a4
+  data.tar.gz: 462ed842d02c3a5aa70103b2e9d7dfa40e496eb7f3bc2cd9946a518319e3b72610bfed43007d4b80a71c4927d5d39867e638e4325dace2c6e9bf5f6d680bb2d9

data/CHANGELOG.md

@@ -1,39 +1,39 @@
 ## [Unreleased]
 
+## [0.5.0] - 2024-07-23
+- Added `average_list_length` feature to the `Exponential` strategy to adjust the bonus pool based on the average number of items across all lists. This helps prevent smaller lists from receiving disproportionately large bonuses.
+- Introduced a new configuration option `include_unranked_items` in the `Exponential` strategy. When enabled, unranked items will receive an equal share of the bonus pool, while ranked items will receive an exponential bonus.
+- Updated RDoc documentation to explain the new `average_list_length` and `include_unranked_items` options.
+- Fixed test cases to correctly calculate expected values when using `average_list_length`.
+- Updated all dependencies to their latest versions.
+
 ## [0.4.2] - 2024-07-01
-- fixed bug where a score could be set to 0. the lowest a score can be now is 1
+- Fixed bug where a score could be set to 0. The lowest a score can be now is 1.
 
 ## [0.4.1] - 2024-06-30
-- add score_penalty to the list details hash
+- Added `score_penalty` to the list details hash.
 
 ## [0.4.0] - 2024-06-26
-- Added score_penalty feature to allow percentage-based penalties on item scores.
+- Added `score_penalty` feature to allow percentage-based penalties on item scores.
 - Updated all dependencies to their latest versions.
 
-## [0.3.1] - 2024-05-026
-
-- Fixed issue with lists with only a single item getting bonus points
+## [0.3.1] - 2024-05-26
+- Fixed issue with lists with only a single item getting bonus points.
 
 ## [0.3.0] - 2024-02-03
-
-- added bonus_pool_percentage feature to exponential
+- Added `bonus_pool_percentage` feature to `Exponential` strategy.
 
 ## [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
+- 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
-
-- sort the score_details by the highest score from each list first
+- Sorted the score details by the highest score from each list first.
 
 ## [0.1.2] - 2024-02-03
+- Added list weight to rank result.
 
-- Added list weight to rank result
-- 
 ## [0.1.1] - 2024-02-03
-
-- Fixed Exponential strategy to just return the list weight if the item has a nil position
+- Fixed `Exponential` strategy to just return the list weight if the item has a nil position.
 
 ## [0.1.0] - 2024-02-01
-
-- Initial release
+- Initial release.

data/Gemfile.lock

@@ -10,31 +10,31 @@ GEM
     json (2.7.2)
     language_server-protocol (3.17.0.3)
     lint_roller (1.1.0)
-    minitest (5.24.0)
-    parallel (1.25.1)
-    parser (3.3.3.0)
+    minitest (5.25.1)
+    parallel (1.26.3)
+    parser (3.3.4.2)
       ast (~> 2.4.1)
       racc
-    racc (1.8.0)
+    racc (1.8.1)
     rainbow (3.1.1)
     rake (13.2.1)
     regexp_parser (2.9.2)
-    rexml (3.3.1)
+    rexml (3.3.5)
       strscan
-    rubocop (1.64.1)
+    rubocop (1.65.1)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
+      regexp_parser (>= 2.4, < 3.0)
       rexml (>= 3.2.5, < 4.0)
       rubocop-ast (>= 1.31.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.31.3)
+    rubocop-ast (1.32.1)
       parser (>= 3.3.1.0)
-    rubocop-minitest (0.35.0)
+    rubocop-minitest (0.35.1)
       rubocop (>= 1.61, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-performance (1.21.1)
@@ -43,10 +43,10 @@ GEM
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
     ruby-progressbar (1.13.0)
-    standard (1.39.0)
+    standard (1.40.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.64.0)
+      rubocop (~> 1.65.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.4)
     standard-custom (1.0.2)

data/README.md

@@ -92,6 +92,45 @@ custom_ranked_items.each do |item|
 end
 ```
 
+### New Features: average_list_length and include_unranked_items
+#### average_list_length
+The average_list_length setting adjusts the bonus pool based on the typical size of lists across your system. This value can be calculated as the mean or median number of items across all lists. It helps prevent smaller lists from receiving disproportionately large bonuses.
+
+```ruby
+# Customizing with average_list_length
+strategy_with_avg_length = WeightedListRank::Strategies::Exponential.new(
+  exponent: 1.5,
+  average_list_length: 50  # Use mean or median list length
+)
+
+ranking_context_with_avg = WeightedListRank::RankingContext.new(strategy_with_avg_length)
+ranked_items = ranking_context_with_avg.rank([list])
+
+# Output the results
+ranked_items.each do |item|
+  puts "Item: #{item[:id]}, Total Score: #{item[:total_score]}"
+end
+```
+
+#### include_unranked_items
+The include_unranked_items setting allows you to distribute a portion of the bonus pool to unranked items. Ranked items receive an exponential bonus, while unranked items split the remaining bonus pool evenly. This feature ensures that unranked lists are still valuable and fairly scored.
+
+```ruby
+# Including unranked items in the bonus pool
+strategy_with_unranked = WeightedListRank::Strategies::Exponential.new(
+  exponent: 1.5,
+  include_unranked_items: true
+)
+
+ranking_context_with_unranked = WeightedListRank::RankingContext.new(strategy_with_unranked)
+ranked_items = ranking_context_with_unranked.rank([list])
+
+# Output the results
+ranked_items.each do |item|
+  puts "Item: #{item[:id]}, Total Score: #{item[:total_score]}"
+end
+```
+
 ### Using Item Penalties
 The WeightedListRank system also supports applying penalties to individual items. A penalty is defined as a percentage reduction in the item's score. This feature can be used to de-emphasize certain items based on specific criteria.
 

data/lib/weighted_list_rank/strategies/exponential.rb

@@ -1,40 +1,31 @@
 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
+      attr_reader :exponent, :bonus_pool_percentage, :average_list_length, :include_unranked_items
 
-      # 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.
+      # Initializes the Exponential strategy with optional parameters for exponent,
+      # bonus pool percentage, average list length, and whether to include unranked items in the bonus pool.
       #
-      # @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.
       # @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)
+      # @param average_list_length [Float, NilClass] the average length of lists in the system, either as a mean or median,
+      # defaults to nil.
+      # @param include_unranked_items [Boolean] whether to include unranked items in the bonus pool calculation,
+      # defaults to false for backward compatibility.
+      def initialize(exponent: 1.5, bonus_pool_percentage: 1.0, average_list_length: nil, include_unranked_items: false)
         @exponent = exponent
         @bonus_pool_percentage = bonus_pool_percentage
+        @average_list_length = average_list_length
+        @include_unranked_items = include_unranked_items
       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 for score adjustments is determined
-      # by the specified bonus pool percentage of the list's total weight.
+      # by the specified bonus pool percentage of the list's total weight, adjusted by the average list length.
+      #
+      # If +include_unranked_items+ is true, unranked items will also receive a portion of the bonus pool.
+      # Ranked items will receive an exponential bonus, while unranked items will split the remaining bonus pool evenly.
       #
       # @param list [WeightedListRank::List] the list containing the item being scored.
       # @param item [WeightedListRank::Item] the item for which to calculate the score.
@@ -45,18 +36,35 @@ module WeightedListRank
         # Default score to the list's weight
         score = list.weight
 
-        unless item.position.nil? || list.items.count == 1
-          num_items = list.items.count
-          total_bonus_pool = list.weight * bonus_pool_percentage
+        # Determine the number of ranked and unranked items
+        ranked_items = list.items.select { |i| i.position }
+        unranked_items = list.items.reject { |i| i.position }
+        num_ranked_items = ranked_items.count
+        num_unranked_items = unranked_items.count
 
-          # 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 }
+        # Calculate the total bonus pool
+        total_bonus_pool = list.weight * bonus_pool_percentage
 
-          # 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
+        # Adjust the bonus pool based on the average list length
+        adjusted_bonus_pool = if average_list_length && average_list_length > 0
+          total_bonus_pool * (list.items.count / average_list_length.to_f)
+        else
+          total_bonus_pool
+        end
 
-          # Add the item's allocated bonus to the default score
+        if item.position.nil?
+          # If the item is unranked, give it an equal share of the remaining bonus pool
+          if include_unranked_items && num_unranked_items > 0
+            unranked_bonus = adjusted_bonus_pool / list.items.count
+            score += unranked_bonus
+          end
+        else
+          # If the item is ranked, calculate its bonus using the exponential formula
+          exponential_factor = (num_ranked_items + 1 - item.position)**exponent
+          total_exponential_factor = (1..num_ranked_items).sum { |pos| (num_ranked_items + 1 - pos)**exponent }
+
+          # Allocate a portion of the adjusted bonus pool based on the item's exponential factor
+          item_bonus = (exponential_factor / total_exponential_factor) * adjusted_bonus_pool
           score += item_bonus
         end
 
@@ -69,12 +77,6 @@ module WeightedListRank
 
       private
 
-      # Applies the score penalty if it exists
-      #
-      # @param score [Float] the original score of the item
-      # @param penalty [Float, NilClass] the score penalty of the item as a percentage (e.g., 0.20 for 20%) or nil if no penalty
-      #
-      # @return [Float] the score after applying the penalty
       def apply_penalty(score, penalty)
         penalty ? score * (1 - penalty) : score
       end

data/lib/weighted_list_rank/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: weighted_list_rank
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Shane Sherman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-07-02 00:00:00.000000000 Z
+date: 2024-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop