weighted_list_rank 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf34a6c62fda7d3038b31da0d7c8d9ec0b9a86a1b0204308e44d950e599f95b7
-  data.tar.gz: 3ed6316fa225185f79afa58899f2b0d29c0abb072c7835492be8dc14b1151b39
+  metadata.gz: f9afa895dc286e9cc5dd2370376b965eda825669debad06e21c232b996e2cab6
+  data.tar.gz: 6116b3e97dc978a0ca8021f683ff7d5b31b1ebd1e0e3f07fc10c7a266b34659e
 SHA512:
-  metadata.gz: ff08f7f218c00bd592e6c54a8862df527fb8c75cbfdf28ec4ccad44221c73b3fb699f590b0e8cb82c7b9e023e42f0fd285dab907a766864b88360cfb622dcdc2
-  data.tar.gz: 760b3d89d47fce1c4fa48899bdd9f58ee925bbe90937988028b1162f19b6afb4f157b37a7ff68b4964d6581f288834e9a065c372f68ca22bf0d31f572cda9806
+  metadata.gz: 71656bad8660b6ae1455afc06a406dddf69f688feb22b690b6dcef57b39aa2ba60df1fe14be91aa22af957b71960b7fe856a980b1769090ea039149fcb005abe
+  data.tar.gz: cb30e3d19ed531e74ff7d665c92029a105c83a6d18e3ce98671c3471218c1c5fa6fc39672394161444b38cc2a97d0dfc2aeab60cfaedefde2664f246cd9ac5c6

data/CHANGELOG.md

@@ -1,12 +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,7 +1,7 @@
 PATH
   remote: .
   specs:
-    weighted_list_rank (0.3.1)
+    weighted_list_rank (0.4.0)
 
 GEM
   remote: https://rubygems.org/
@@ -10,18 +10,18 @@ GEM
     json (2.7.2)
     language_server-protocol (3.17.0.3)
     lint_roller (1.1.0)
-    minitest (5.23.1)
-    parallel (1.24.0)
-    parser (3.3.1.0)
+    minitest (5.24.0)
+    parallel (1.25.1)
+    parser (3.3.3.0)
       ast (~> 2.4.1)
       racc
     racc (1.8.0)
     rainbow (3.1.1)
     rake (13.2.1)
     regexp_parser (2.9.2)
-    rexml (3.2.8)
-      strscan (>= 3.0.9)
-    rubocop (1.63.5)
+    rexml (3.3.1)
+      strscan
+    rubocop (1.64.1)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
@@ -37,16 +37,16 @@ GEM
     rubocop-minitest (0.35.0)
       rubocop (>= 1.61, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
-    rubocop-performance (1.21.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)
     ruby-progressbar (1.13.0)
-    standard (1.36.0)
+    standard (1.39.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.63.0)
+      rubocop (~> 1.64.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.4)
     standard-custom (1.0.2)

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? || list.items.count == 1
+        # 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.1"
+  VERSION = "0.4.0"
 end

data/weighted_list_rank.gemspec

@@ -0,0 +1,42 @@
+# 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: weighted_list_rank
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Shane Sherman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-05-26 00:00:00.000000000 Z
+date: 2024-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -89,6 +89,7 @@ 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
@@ -111,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