weighted_list_rank 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02c97cc567dfd099a6f65066c534b3780d1a8ca7f8b6a2148d6410c348ed6db9
-  data.tar.gz: 235f31a73f88b44485d5c5a0fae360d6f4fe2a417e380ddaccadfa214af4d5d6
+  metadata.gz: f9afa895dc286e9cc5dd2370376b965eda825669debad06e21c232b996e2cab6
+  data.tar.gz: 6116b3e97dc978a0ca8021f683ff7d5b31b1ebd1e0e3f07fc10c7a266b34659e
 SHA512:
-  metadata.gz: e908050bff4073ce084cc6b20a30992a52a08d93dc2732ae4e891605d2dc3c761166a79e90093ddb5b345ebe9da344c4ebe430fd9d9e1b780bccced0d4ee97fb
-  data.tar.gz: 67fa8168ec949cbdcb3c1dc728d8461ae0a4bf51234cef9d251eaf10b63eb8ca617d55945a719ea297cfe24c42a1ab89c871f8f090af601c97ec21f22b0c2b6f
+  metadata.gz: 71656bad8660b6ae1455afc06a406dddf69f688feb22b690b6dcef57b39aa2ba60df1fe14be91aa22af957b71960b7fe856a980b1769090ea039149fcb005abe
+  data.tar.gz: cb30e3d19ed531e74ff7d665c92029a105c83a6d18e3ce98671c3471218c1c5fa6fc39672394161444b38cc2a97d0dfc2aeab60cfaedefde2664f246cd9ac5c6

data/CHANGELOG.md

@@ -1,8 +1,16 @@
 ## [Unreleased]
 
+## [0.4.0] - 2024-06-26
+- 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.0] - 2024-02-03
 
-- added bonus_pool_percentage feature to expoential
+- added bonus_pool_percentage feature to exponential
 
 ## [0.2.0] - 2024-02-03
 

data/Gemfile.lock

@@ -1,59 +1,61 @@
 PATH
   remote: .
   specs:
-    weighted_list_rank (0.1.1)
+    weighted_list_rank (0.4.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
-    json (2.7.1)
+    json (2.7.2)
     language_server-protocol (3.17.0.3)
     lint_roller (1.1.0)
-    minitest (5.21.2)
-    parallel (1.24.0)
-    parser (3.3.0.5)
+    minitest (5.24.0)
+    parallel (1.25.1)
+    parser (3.3.3.0)
       ast (~> 2.4.1)
       racc
-    racc (1.7.3)
+    racc (1.8.0)
     rainbow (3.1.1)
-    rake (13.1.0)
-    regexp_parser (2.9.0)
-    rexml (3.2.6)
-    rubocop (1.59.0)
+    rake (13.2.1)
+    regexp_parser (2.9.2)
+    rexml (3.3.1)
+      strscan
+    rubocop (1.64.1)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.2.2.4)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.30.0)
-      parser (>= 3.2.1.0)
-    rubocop-minitest (0.34.5)
-      rubocop (>= 1.39, < 2.0)
-      rubocop-ast (>= 1.30.0, < 2.0)
-    rubocop-performance (1.20.2)
+    rubocop-ast (1.31.3)
+      parser (>= 3.3.1.0)
+    rubocop-minitest (0.35.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.30.0, < 2.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
     ruby-progressbar (1.13.0)
-    standard (1.33.0)
+    standard (1.39.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.59.0)
+      rubocop (~> 1.64.0)
       standard-custom (~> 1.0.0)
-      standard-performance (~> 1.3)
+      standard-performance (~> 1.4)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.3.1)
+    standard-performance (1.4.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.20.2)
+      rubocop-performance (~> 1.21.0)
+    strscan (3.1.0)
     unicode-display_width (2.5.0)
 
 PLATFORMS

data/README.md

@@ -92,6 +92,78 @@ custom_ranked_items.each do |item|
 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.
+
+To use the penalty feature, include the score_penalty attribute when defining your items:
+
+```ruby
+class MyItem
+  include WeightedListRank::Item
+  attr_reader :id, :position, :score_penalty
+
+  def initialize(id, position, score_penalty = nil)
+    @id = id
+    @position = position
+    @score_penalty = score_penalty
+  end
+end
+```
+
+You can then apply the penalties when calculating the scores:
+
+```ruby
+require 'weighted_list_rank'
+
+# Initialize items and list with text identifiers and penalties
+items = [
+  MyItem.new("Item 1", 1, 0.20), # 20% penalty
+  MyItem.new("Item 2", 2, 0.10), # 10% penalty
+  MyItem.new("Item 3", 3, nil)   # No penalty
+]
+list = MyList.new("List 1", 10, items)
+
+# Initialize the Exponential strategy with an optional exponent
+exponential_strategy = WeightedListRank::Strategies::Exponential.new(exponent: 1.5)
+
+# Create a RankingContext using the Exponential strategy
+ranking_context = WeightedListRank::RankingContext.new(exponential_strategy)
+
+# Rank the items
+ranked_items = ranking_context.rank([list])
+
+# Display the ranked items
+ranked_items.each do |item|
+  puts "Item: #{item[:id]}, Total Score: #{item[:total_score]}"
+end
+```
+
+### Customizing Penalties Example
+You can customize the penalty values to see how they affect the final scores of the items.
+
+```ruby
+# Customizing penalties for different items
+items = [
+  MyItem.new("Item 1", 1, 0.30), # 30% penalty
+  MyItem.new("Item 2", 2, 0.15), # 15% penalty
+  MyItem.new("Item 3", 3, nil)   # No penalty
+]
+list = MyList.new("List 1", 10, items)
+
+# Initialize the Exponential strategy with an optional exponent
+exponential_strategy = WeightedListRank::Strategies::Exponential.new(exponent: 2.0)
+
+# Create a RankingContext using the Exponential strategy
+ranking_context = WeightedListRank::RankingContext.new(exponential_strategy)
+
+# Rank the items
+ranked_items = ranking_context.rank([list])
+
+# Output the results
+ranked_items.each do |item|
+  puts "Item: #{item[:id]}, Total Score: #{item[:total_score]}"
+end
+```
 
 ## Development
 

data/Rakefile

@@ -2,6 +2,7 @@
 
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "standard/rake"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"

data/lib/weighted_list_rank/item.rb

@@ -11,5 +11,11 @@ module WeightedListRank
     def id
       raise NotImplementedError, "Implement this method to return the item's unique identifier"
     end
+
+    # Returns the score penalty of the item. Can be overridden by the including class.
+    # @return [Float, NilClass] the score penalty of the item as a percentage (e.g., 0.20 for 20%) or nil if no penalty
+    def score_penalty
+      nil
+    end
   end
 end

data/lib/weighted_list_rank/strategies/exponential.rb

@@ -42,21 +42,38 @@ module WeightedListRank
       # @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?
+        # Default score to the list's weight
+        score = list.weight
 
-        num_items = list.items.count
-        total_bonus_pool = list.weight * bonus_pool_percentage
+        unless item.position.nil? || list.items.count == 1
+          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 }
+          # 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
+          # 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
 
-        # The final score is the list's weight plus the item's allocated bonus
-        list.weight + item_bonus
+          # Add the item's allocated bonus to the default score
+          score += item_bonus
+        end
+
+        # Apply score penalty if it exists
+        apply_penalty(score, item.score_penalty)
+      end
+
+      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
     end
   end

data/lib/weighted_list_rank/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: weighted_list_rank
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Shane Sherman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-02-04 00:00:00.000000000 Z
+date: 2024-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -112,7 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.11
 signing_key: 
 specification_version: 4
 summary: generate ranks of items from weighted lists