weighted_list_rank 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c194a4b55fa9efecf1ad39fd54b8d22c2a9fd6766cb562c265c1f881deb08c4
-  data.tar.gz: 50dba99dde929b5bd3feed2709877c48d87bc45f6f9fcd745fd96d1b14749d7d
+  metadata.gz: 34f4b87da4046f63fd0771a985c63fab24e30dc51445ce9ceabcce4bde5b3f45
+  data.tar.gz: d857a6cb9a7e9114d2157a05a373876f08c52661130cf50126fa6258b4beaa5b
 SHA512:
-  metadata.gz: fafab0c49212017e8730cec2b78101e6adea7a85eedc938a0250d76643af7e4dea7fb6d1c49c8ed035675774bc4bf18f2e94eca46546ff8627a02b10d43fb1a7
-  data.tar.gz: 15e032d6eb71f6b65a825847e6850a8d4e7b248853d4a4480ab8f4ef7c276998dfd1ac0a3edea8f0a0fd19f788c571d84acac1e3d4fa1e8a1089aadd2e9cbab1
+  metadata.gz: ea9c40e27791fafe638694e34a440c4df6e8e8c20770b2f9b1da6ca8e8d37d755ae5eaaeeb89fe2ca43b569805b9fde43c1b2616eb0a135bbdea37b02ae5bf4a
+  data.tar.gz: 7ad51b9288339b0728841a30d91ee9b0b5824f101801a090e7533a93f090a40b8ef0ea8143fea32c533fc333e0a96037ee3cba684efa9eaa8dfc9388edc20889

data/CHANGELOG.md

@@ -1,4 +1,14 @@
-## [Unreleased]
+## [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.
+- Updated all dependencies to their latest versions.
 
 ## [0.5.2] - 2024-08-21
 - Fixed an issue in the `Exponential` strategy where `score_penalty` was not being applied to unranked items. Now, `score_penalty` is correctly applied to both ranked and unranked items, ensuring consistent scoring behavior.

data/Gemfile.lock

@@ -1,64 +1,69 @@
 PATH
   remote: .
   specs:
-    weighted_list_rank (0.4.2)
+    weighted_list_rank (0.5.3)
 
 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.5)
     lint_roller (1.1.0)
-    minitest (5.25.1)
-    parallel (1.26.3)
-    parser (3.3.4.2)
+    minitest (5.25.5)
+    parallel (1.27.0)
+    parser (3.3.8.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.5)
-      strscan
-    rubocop (1.65.1)
+    rake (13.3.0)
+    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.1)
-      parser (>= 3.3.1.0)
-    rubocop-minitest (0.35.1)
-      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.38.1)
+      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.0)
+    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)
-    strscan (3.1.0)
-    unicode-display_width (2.5.0)
+      rubocop-performance (~> 1.25.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
 
 PLATFORMS
+  arm64-darwin-24
   x86_64-linux
 
 DEPENDENCIES
@@ -67,7 +72,7 @@ DEPENDENCIES
   rubocop (~> 1.21)
   rubocop-minitest (~> 0.3)
   rubocop-rake (~> 0.6)
-  standard (~> 1.0)
+  standard (>= 1.35.1)
   weighted_list_rank!
 
 BUNDLED WITH

data/README.md

@@ -204,6 +204,31 @@ 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).
+
 ## 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.
@@ -30,8 +33,8 @@ module WeightedListRank
         end
       end
 
-      # Convert hash to a sorted array
-      sorted_items = items.map do |id, details|
+      # Convert hash to a formatted array
+      formatted_items = items.map do |id, details|
         {
           id: id,
           # Sort the score_details array by score in descending order before including it
@@ -40,8 +43,18 @@ module WeightedListRank
         }
       end
 
+      # Apply list count penalties if configured
+      if !list_count_penalties.empty?
+        formatted_items.each do |item|
+          list_count = item[:score_details].length
+          if (penalty = list_count_penalties[list_count])
+            item[:total_score] *= (1 - penalty)
+          end
+        end
+      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

@@ -64,8 +64,16 @@ module WeightedListRank
               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
+
             # Ranked items receive a bonus calculated using the exponential formula
-            exponential_factor = (total_items + 1 - item.position)**exponent
+            exponential_factor = (total_items + 1 - item_position)**exponent
             total_exponential_factor = (1..total_items).sum { |pos| (total_items + 1 - pos)**exponent }
 
             # Allocate a portion of the adjusted bonus pool based on the item's exponential factor

data/lib/weighted_list_rank/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: weighted_list_rank
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Shane Sherman
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-08-21 00:00:00.000000000 Z
+date: 2025-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -28,16 +27,16 @@ dependencies:
   name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 1.35.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 1.35.1
 - !ruby/object:Gem::Dependency
   name: rubocop-minitest
   requirement: !ruby/object:Gem::Requirement
@@ -89,7 +88,6 @@ files:
 - lib/weighted_list_rank/strategy.rb
 - lib/weighted_list_rank/version.rb
 - sig/weighted_list_rank.rbs
-- weighted_list_rank.gemspec
 homepage: https://github.com/ssherman/weighted_list_rank
 licenses:
 - MIT
@@ -97,7 +95,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 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: generate ranks of items from weighted lists
 test_files: []

data/weighted_list_rank.gemspec

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/weighted_list_rank/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "weighted_list_rank"
-  spec.version = WeightedListRank::VERSION
-  spec.authors = ["Shane Sherman"]
-  spec.email = ["shane.sherman@gmail.com"]
-
-  spec.summary = "generate ranks of items from weighted lists"
-  spec.description = "generate ranks of items from weighted lists"
-  spec.homepage = "https://github.com/ssherman/weighted_list_rank"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 2.6.0"
-
-  # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/ssherman/weighted_list_rank"
-  spec.metadata["changelog_uri"] = "https://github.com/ssherman/weighted_list_rank/CHANGELOG.md"
-
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
-  spec.add_development_dependency "rubocop", "~> 1.0"
-  spec.add_development_dependency "standard", "~> 1.0"
-  spec.add_development_dependency "rubocop-minitest", "~> 0.3"
-  spec.add_development_dependency "rubocop-rake", "~> 0.6"
-  # For more information and examples about making a new gem, check out our
-  # guide at: https://bundler.io/guides/creating_gem.html
-end