weighted_list_rank 0.5.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e3b387809912d1000f8f8ee13704cec1b04d691b783d6bd19a9f9b6e6cf0d6d
-  data.tar.gz: caadd577bf061e63c1357943da439e06d6c1c5e441bb84ddbff250fb49a45020
+  metadata.gz: 0e8758848cc7ed9090ee9348afeb2efd6fe7d27506b00a2dd997ffce53959615
+  data.tar.gz: ff68f02846e841ac26fb3863d50b1309543c2d1e8368024ff01e7de44041cb23
 SHA512:
-  metadata.gz: eb8c04911951b50c39b7f45583b1932274377106357fae605185bad10f8e37fb4e5c86047698e5e1752778311a5ea3403ce82fe494d44035ac889625b0703056
-  data.tar.gz: 955ad9589e4418ca509065a7dc92b23af4c3c962ee8523ab89585bda58f04a9cedbedc11124523c69b385ba3f146d7db6856be6f86dc66143c251055b69bc545
+  metadata.gz: bf99a1e72f8dc738541b1002ef1ddb9d590a198ac957aa59e2ee570b4dcf82d9702f78291459ad2d9f98250482a7b421809e3a0aa557f445454b0545c914e43d
+  data.tar.gz: d9f13250eac45ebe3466c8020a16a5f290fa693174d574d64e35f17010cf0624993c0d575d53d319b7b21510a9a8e022af625b4bdedf39f9c7b64d4952c77e7c

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [0.7.0] - 2026-08-23
+### Performance
+- Ranking a list is now linear in the number of items instead of quadratic. `Exponential#calculate_score` recomputed the ranked-item count and the total exponential factor for every item, even though both are constant across a list. They are now computed once per list.
+- Measured on synthetic data shaped like a real catalogue: 700 lists / ~19k entries went from 226ms to 13ms (17x). The gain grows with the size of your longest list — a single 1,600-item list went from 217ms to 1.4ms (158x).
+- Ranking output is unchanged. Scores, `score_details`, and ordering are bit-for-bit identical to 0.6.0, verified across four data profiles and a 3,000-case edge-case matrix.
+
+### Added
+- `Strategy#calculate_scores(list)`, which returns an array of scores positionally matching `list.items`. This is now the entry point `RankingContext` uses. The default implementation delegates to `calculate_score` for each item, so existing custom strategies keep working unchanged. Strategies with per-list invariants should override it — see "Writing a Custom Strategy" in the README.
+- `warn_on_invalid_position` option on the `Exponential` strategy, defaulting to `false`.
+
+### Changed
+- Items whose position exceeds the number of items in their list are still clamped to the last position, but this is no longer reported by default. Previously every such item printed a warning to `stdout`, which was noisy inside an application. Enable `warn_on_invalid_position: true` to get a single `stderr` warning per affected list.
+- Updated all development dependencies to their latest versions.
+
+## [0.6.0] - 2025-06-29
+- Added `list_count_penalties` feature to `RankingContext` to allow penalizing items based on the number of lists they appear on. This is useful for de-emphasizing items that are not widely represented across your data.
+- The feature accepts a hash mapping list counts to penalty percentages (e.g., `{1 => 0.50, 2 => 0.25}` to penalize items on 1 list by 50% and items on 2 lists by 25%).
+- Penalties are applied to the total score after all list scores are aggregated but before sorting.
+- This feature is fully backwards compatible and stacks with individual item penalties.
+- Updated all dependencies to their latest versions.
+
 ## [0.5.3] - 2024-08-22
 - Fixed an issue in the `Exponential` strategy where items with positions higher than the total number of items in a list could cause errors. Now, such items are treated as if they were in the last position, and a warning is logged.
 - Added a new test case to verify the handling of items with positions exceeding the list size.

data/Gemfile.lock

@@ -1,62 +1,69 @@
 PATH
   remote: .
   specs:
-    weighted_list_rank (0.5.3)
+    weighted_list_rank (0.7.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
-    json (2.7.2)
-    language_server-protocol (3.17.0.3)
+    ast (2.4.3)
+    json (2.12.2)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
-    minitest (5.25.1)
-    parallel (1.26.3)
-    parser (3.3.5.0)
+    minitest (5.27.0)
+    parallel (1.27.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
+    prism (1.4.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    regexp_parser (2.9.2)
-    rexml (3.3.8)
-    rubocop (1.65.1)
+    rake (13.4.2)
+    regexp_parser (2.10.0)
+    rubocop (1.75.8)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.4, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.32.3)
-      parser (>= 3.3.1.0)
-    rubocop-minitest (0.36.0)
-      rubocop (>= 1.61, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
-    rubocop-performance (1.21.1)
-      rubocop (>= 1.48.1, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
-    rubocop-rake (0.6.0)
-      rubocop (~> 1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.45.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-minitest (0.40.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
     ruby-progressbar (1.13.0)
-    standard (1.40.1)
+    standard (1.50.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.65.0)
+      rubocop (~> 1.75.5)
       standard-custom (~> 1.0.0)
-      standard-performance (~> 1.4)
+      standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.4.0)
+    standard-performance (1.8.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.21.0)
-    unicode-display_width (2.6.0)
+      rubocop-performance (~> 1.25.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
+  arm64-darwin-24
   x86_64-linux
 
 DEPENDENCIES

data/README.md

@@ -204,6 +204,80 @@ ranked_items.each do |item|
 end
 ```
 
+### Penalizing Items by Number of Lists
+You can optionally penalize items that appear on only a small number of lists. This is useful for de-emphasizing items that are not widely represented across your data. To use this feature, pass a `list_count_penalties` hash to the `RankingContext` constructor, where the keys are the number of lists and the values are the penalty percentages (as a float between 0 and 1).
+
+For example, to penalize items that appear on only 1 list by 50%, and items on 2 lists by 25%:
+
+```ruby
+list_count_penalties = {1 => 0.50, 2 => 0.25}
+ranking_context = WeightedListRank::RankingContext.new(
+  WeightedListRank::Strategies::Exponential.new,
+  list_count_penalties: list_count_penalties
+)
+
+ranked_items = ranking_context.rank([list1, list2, list3])
+```
+
+- Items that appear on only 1 list will have their total score multiplied by 0.5 (50% penalty).
+- Items that appear on only 2 lists will have their total score multiplied by 0.75 (25% penalty).
+- Items that appear on more lists will not be penalized unless specified in the hash.
+
+#### How it works
+- The penalty is applied to the total score of each item after all list scores are aggregated, but before sorting.
+- If an item appears on a number of lists not present in the hash, no penalty is applied.
+- This feature is fully backwards compatible: if you do not provide `list_count_penalties`, no penalties are applied.
+- This penalty stacks with individual item penalties (e.g., `score_penalty` on an item).
+
+### Handling Invalid Positions
+If a list contains an item whose `position` is greater than the number of items in that list, the position is clamped to the last position. This is silent by default, so the gem stays quiet inside an application.
+
+While investigating your data you can opt into a warning. It is written to `stderr`, and at most one is emitted per affected list no matter how many items are involved:
+
+```ruby
+strategy = WeightedListRank::Strategies::Exponential.new(warn_on_invalid_position: true)
+```
+
+```
+WeightedListRank: list 42 has 3 item(s) with a position greater than the number of items in the list (25); clamping to 25.
+```
+
+### Writing a Custom Strategy
+A strategy needs to implement `calculate_score(list, item)`:
+
+```ruby
+class MyStrategy < WeightedListRank::Strategy
+  def calculate_score(list, item)
+    list.weight * (1.0 / item.position)
+  end
+end
+```
+
+`RankingContext` scores a list through `calculate_scores(list)`, which returns an array of scores positionally matching `list.items`. The default implementation calls `calculate_score` once per item, so implementing only the single-item method is enough to get a working strategy.
+
+If your scoring depends on values that are constant across the list — a total, a count, a normalizing factor — override `calculate_scores` and compute them once. Recomputing per-list values inside `calculate_score` makes ranking quadratic in list length, which is what the built-in `Exponential` strategy used to do:
+
+```ruby
+class MyStrategy < WeightedListRank::Strategy
+  def calculate_scores(list)
+    items = list.items
+    total = items.sum { |i| i.position || 0 } # computed once for the whole list
+
+    items.map { |item| score_for(list, item, total) }
+  end
+
+  def calculate_score(list, item)
+    score_for(list, item, list.items.sum { |i| i.position || 0 })
+  end
+
+  private
+
+  def score_for(list, item, total)
+    list.weight * (item.position.to_f / total)
+  end
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/weighted_list_rank/context.rb

@@ -3,12 +3,15 @@ module WeightedListRank
   # It aggregates scores for each item across all lists, based on the provided strategy.
   class RankingContext
     # @strategy: The strategy used for calculating scores.
-    attr_reader :strategy
+    # @list_count_penalties: Hash mapping list counts to penalty percentages (e.g., {1 => 0.50, 2 => 0.25})
+    attr_reader :strategy, :list_count_penalties
 
-    # Initializes a new RankingContext with an optional ranking strategy.
+    # Initializes a new RankingContext with an optional ranking strategy and list count penalties.
     # @param strategy [Strategy] the strategy to use for ranking items, defaults to Strategies::Exponential.
-    def initialize(strategy = Strategies::Exponential.new)
+    # @param list_count_penalties [Hash] hash mapping list counts to penalty percentages, defaults to empty hash.
+    def initialize(strategy = Strategies::Exponential.new, list_count_penalties: {})
       @strategy = strategy
+      @list_count_penalties = list_count_penalties
     end
 
     # Ranks items across multiple lists according to the strategy's score calculation.
@@ -16,32 +19,52 @@ module WeightedListRank
     # @return [Array<Hash>] a sorted array of item scores, with each item's details including ID, score details, and total score.
     def rank(lists)
       items = {}
+
+      # Strategies subclassing Strategy always have this; the fallback covers
+      # duck-typed strategies that only define #calculate_score.
+      batch_capable = strategy.respond_to?(:calculate_scores)
+
       lists.each do |list|
-        list.items.each do |item|
-          score = strategy.calculate_score(list, item)
-          items[item.id] ||= {}
-          # Ensure the list_details array exists, then append the new score detail
-          items[item.id][:list_details] ||= []
-          items[item.id][:list_details] << {list_id: list.id, score: score, weight: list.weight, score_penalty: item.score_penalty}
-
-          # Ensure the total_score is initialized, then add the score
-          items[item.id][:total_score] ||= 0
-          items[item.id][:total_score] += score
+        list_items = list.items
+        scores = if batch_capable
+          strategy.calculate_scores(list)
+        else
+          list_items.map { |item| strategy.calculate_score(list, item) }
+        end
+
+        list_id = list.id
+        weight = list.weight
+
+        list_items.each_with_index do |item, index|
+          score = scores[index]
+          details = (items[item.id] ||= {list_details: [], total_score: 0})
+          details[:list_details] << {list_id: list_id, score: score, weight: weight, score_penalty: item.score_penalty}
+          details[:total_score] += score
         end
       end
 
-      # Convert hash to a sorted array
-      sorted_items = items.map do |id, details|
+      apply_penalties = !list_count_penalties.empty?
+
+      # Convert hash to a formatted array
+      formatted_items = items.map do |id, details|
+        list_details = details[:list_details]
+        total_score = details[:total_score]
+
+        # Apply list count penalties if configured
+        if apply_penalties && (penalty = list_count_penalties[list_details.length])
+          total_score *= (1 - penalty)
+        end
+
         {
           id: id,
           # Sort the score_details array by score in descending order before including it
-          score_details: details[:list_details].sort_by { |detail| -detail[:score] },
-          total_score: details[:total_score]
+          score_details: list_details.sort_by { |detail| -detail[:score] },
+          total_score: total_score
         }
       end
 
       # Sort the array by total_score in descending order
-      sorted_items.sort_by { |item| -item[:total_score] }
+      formatted_items.sort_by { |item| -item[:total_score] }
     end
   end
 end

data/lib/weighted_list_rank/strategies/exponential.rb

@@ -1,7 +1,8 @@
 module WeightedListRank
   module Strategies
     class Exponential < WeightedListRank::Strategy
-      attr_reader :exponent, :bonus_pool_percentage, :average_list_length, :include_unranked_items
+      attr_reader :exponent, :bonus_pool_percentage, :average_list_length, :include_unranked_items,
+        :warn_on_invalid_position
 
       # 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.
@@ -13,87 +14,144 @@ module WeightedListRank
       # 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)
+      # @param warn_on_invalid_position [Boolean] whether to emit a warning when a list contains items whose
+      # position exceeds the number of items in the list. Such positions are always clamped to the last position;
+      # this only controls whether that is reported. Defaults to false, so scoring is silent.
+      def initialize(exponent: 1.5, bonus_pool_percentage: 1.0, average_list_length: nil,
+        include_unranked_items: false, warn_on_invalid_position: false)
         @exponent = exponent
         @bonus_pool_percentage = bonus_pool_percentage
         @average_list_length = average_list_length
         @include_unranked_items = include_unranked_items
+        @warn_on_invalid_position = warn_on_invalid_position
       end
 
-      # Calculates the score of an item within a list based on its rank position, the total number of items,
+      # Calculates the scores for every item in a list in one pass.
+      #
+      # The number of ranked items, the adjusted bonus pool, and the total
+      # exponential factor are all constant across the list, so they are
+      # computed once here instead of once per item. Scoring a list is
+      # therefore linear in the number of items.
+      #
+      # @param list [WeightedListRank::List] the list whose items should be scored.
+      # @return [Array<Float>] scores positionally matching +list.items+.
+      def calculate_scores(list)
+        items = list.items
+        total_items = items.count
+        return [] if total_items.zero?
+
+        num_ranked_items = count_ranked(items)
+        adjusted_bonus_pool = adjusted_bonus_pool_for(list, total_items)
+
+        # Only lists containing ranked items need this, and it is the most
+        # expensive value to produce, so it is computed on first use.
+        total_exponential_factor = nil
+        invalid_positions = 0
+
+        scores = items.map do |item|
+          position = item.position
+
+          if position.nil?
+            score = list.weight
+            if num_ranked_items.zero? && include_unranked_items
+              score += adjusted_bonus_pool / total_items
+            end
+          else
+            if position > total_items
+              invalid_positions += 1
+              position = total_items
+            end
+            total_exponential_factor ||= exponential_factor_sum(total_items)
+            exponential_factor = (total_items + 1 - position)**exponent
+            score = list.weight + (exponential_factor / total_exponential_factor) * adjusted_bonus_pool
+          end
+
+          floor(apply_penalty(score, item.score_penalty))
+        end
+
+        report_invalid_positions(list, invalid_positions, total_items)
+        scores
+      end
+
+      # Calculates the score of a single 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, 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.
       #
+      # Scoring a whole list is cheaper through {#calculate_scores}, which shares the per-list work across items.
+      #
       # @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, the specified exponent,
       # and the bonus pool percentage.
       def calculate_score(list, item)
-        # Default score to the list's weight
-        score = list.weight
-
-        # Total number of items in the list
-        total_items = list.items.count
-
-        # Separate ranked and unranked items
-        ranked_items = list.items.select { |i| i.position }
-        num_ranked_items = ranked_items.count
+        items = list.items
+        total_items = items.count
+        num_ranked_items = count_ranked(items)
+        position = item.position
 
-        if num_ranked_items > 0 && item.position.nil?
-          # If there are ranked items, unranked items get no bonus, only the list's weight
+        if position.nil?
           score = list.weight
+          if num_ranked_items.zero? && include_unranked_items
+            score += adjusted_bonus_pool_for(list, total_items) / total_items
+          end
         else
-          # Calculate the total bonus pool
-          total_bonus_pool = list.weight * bonus_pool_percentage
-
-          # Adjust the bonus pool based on the average list length
-          adjusted_bonus_pool = if average_list_length && average_list_length > 0
-            total_bonus_pool * (total_items / average_list_length.to_f)
-          else
-            total_bonus_pool
+          if position > total_items
+            report_invalid_positions(list, 1, total_items)
+            position = total_items
           end
+          exponential_factor = (total_items + 1 - position)**exponent
+          score = list.weight +
+            (exponential_factor / exponential_factor_sum(total_items)) * adjusted_bonus_pool_for(list, total_items)
+        end
 
-          if item.position.nil?
-            # Unranked items get no bonus if there are ranked items
-            if include_unranked_items && num_ranked_items == 0
-              unranked_bonus = adjusted_bonus_pool / total_items
-              score += unranked_bonus
-            end
-          else
-            # Check if the item's position is higher than the total number of items
-            if item.position > total_items
-              puts "Warning: Item position (#{item.position}) is higher than the total number of items (#{total_items}) in the list. Using total items as position."
-              item_position = total_items
-            else
-              item_position = item.position
-            end
+        floor(apply_penalty(score, item.score_penalty))
+      end
 
-            # Ranked items receive a bonus calculated using the exponential formula
-            exponential_factor = (total_items + 1 - item_position)**exponent
-            total_exponential_factor = (1..total_items).sum { |pos| (total_items + 1 - pos)**exponent }
+      private
 
-            # 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
-        end
+      def count_ranked(items)
+        count = 0
+        items.each { |item| count += 1 if item.position }
+        count
+      end
 
-        # Apply score penalty if it exists, for both ranked and unranked items
-        score = apply_penalty(score, item.score_penalty)
+      def adjusted_bonus_pool_for(list, total_items)
+        total_bonus_pool = list.weight * bonus_pool_percentage
 
-        # Ensure the score is not less than 1
-        [score, 1].max
+        if average_list_length && average_list_length > 0
+          total_bonus_pool * (total_items / average_list_length.to_f)
+        else
+          total_bonus_pool
+        end
       end
 
-      private
+      # The sum of every item's exponential factor, used to normalize each
+      # item's share of the bonus pool. Constant for a given list length.
+      def exponential_factor_sum(total_items)
+        (1..total_items).sum { |pos| (total_items + 1 - pos)**exponent }
+      end
 
       def apply_penalty(score, penalty)
         penalty ? score * (1 - penalty) : score
       end
+
+      # Ensure the score is not less than 1.
+      def floor(score)
+        (score < 1) ? 1 : score
+      end
+
+      # Emits at most one warning per list, and only when explicitly enabled.
+      def report_invalid_positions(list, count, total_items)
+        return unless warn_on_invalid_position
+        return if count.zero?
+
+        warn "WeightedListRank: list #{list.id} has #{count} item(s) with a position greater than the " \
+             "number of items in the list (#{total_items}); clamping to #{total_items}."
+      end
     end
   end
 end

data/lib/weighted_list_rank/strategy.rb

@@ -7,5 +7,22 @@ module WeightedListRank
     def calculate_score(list, item)
       raise NotImplementedError
     end
+
+    # Calculates the scores for every item in a list, returned in the same order
+    # as +list.items+.
+    #
+    # This is the entry point {RankingContext} uses. The default implementation
+    # simply delegates to {#calculate_score} for each item, so strategies that
+    # implement only the single-item API continue to work unchanged.
+    #
+    # Strategies whose scoring depends on values that are constant across the
+    # list (a total, a count, a normalizing factor) should override this and
+    # compute those values once, rather than recomputing them for every item.
+    #
+    # @param list [List] the list whose items should be scored.
+    # @return [Array<Numeric>] scores positionally matching +list.items+.
+    def calculate_scores(list)
+      list.items.map { |item| calculate_score(list, item) }
+    end
   end
 end

data/lib/weighted_list_rank/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: weighted_list_rank
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Shane Sherman
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-10-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -97,7 +96,6 @@ metadata:
   homepage_uri: https://github.com/ssherman/weighted_list_rank
   source_code_uri: https://github.com/ssherman/weighted_list_rank
   changelog_uri: https://github.com/ssherman/weighted_list_rank/CHANGELOG.md
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -112,8 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key: 
+rubygems_version: 4.0.16
 specification_version: 4
 summary: generate ranks of items from weighted lists
 test_files: []