was 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35789d2f200b0436e67730bf7e2811cd61665f6bef985bc1f2cb091ed1797a5b
-  data.tar.gz: efd553a27afd03bb2da2443d80945239b7e22487dac6e850982d498ec32d5d01
+  metadata.gz: 974fa97c47b4fe794512983c75fa065b9bdd40370e5987b1e4523d01791bdd2a
+  data.tar.gz: 9f6e783dd2fbad215e8c2b16c820a1b8642b843efba424ed2d35e5aa1e7e2b92
 SHA512:
-  metadata.gz: 630fc202315d1b3d90c28214f97d23ba66f7f5daba3a43651cf720d21a7ece94c6d2533715267933edc2f6b18f662301d71d6590c7d9db655aa30dbcc90703d6
-  data.tar.gz: 9e95ffaddcbae72fba82c4957b7ac20bb6db44bc219c6e13b445281799aafead6a9c722b0a7235975d737f877828da63dfc70e0284b65288e284e0245b54614a
+  metadata.gz: 43d1c61377ad1da1477d5edf911fd55b22acea765ffcf10e53c3cdc2c181e7968bd3bc02223721a82146c57b5186f79d25b75557026cedecb30dfc218a56e801
+  data.tar.gz: 6c09a8018b3d7fb5634985e3144d75adc942a21b3b6b459057192b1f0918bfee840b54a8897dc9ad25983623cbdf858b40c9e72f84ab073d3a891592998e5d41

data/README.md

@@ -14,8 +14,14 @@ Scenario:
   * 'C' is 50%
   * 'D' is 0%
 * The practical is a simple mark out of 10.
-  * 4 out of 10 is 40% 
-* The person is given a final score out of 1000.  
+  * 4 out of 10 is 40%
+* The person is given a final score out of 1000.
+
+### Install the RubyGem
+
+```bash
+gem install was
+```
 
 ### Define score classes
 
@@ -25,21 +31,30 @@ require "was"
 class ReportScore < WAS::Score
   maximum_score 1000
 
-  with :exam,     class_name: "ExamScore",      weight: 0.75
-  with :practical class_name: "PracticalScore", weight: 0.25
+  with :exam,      class_name: "ExamScore",      weight: 0.75
+  with :practical, class_name: "PracticalScore", weight: 0.25
 end
 
 class ExamScore < WAS::Score
-  def calculation
-    return 1    if input == "A"
-    return 0.75 if input == "B"
-    return 0.5  if input == "C"
+  context :grade_a, score: 1 do |input|
+    input == "A"
+  end
+
+  context :grade_b, score: 0.75 do |input|
+    input == "B"
+  end
+
+  context :grade_c, score: 0.5 do |input|
+    input == "C"
+  end
+
+  context :flunk do
     0
   end
 end
 
 class PracticalScore < WAS::Score
-  def calculation
+  context :score do |input|
     input / 10.0
   end
 end
@@ -68,8 +83,8 @@ Omitting the `maximum_score` will return a composed percentage represented as a
 ```ruby
 # report_score.rb
 class ReportScore < WAS::Score
-  with :exam,     class_name: "ExamScore",      weight: 0.75
-  with :practical class_name: "PracticalScore", weight: 0.25
+  with :exam,      class_name: "ExamScore",      weight: 0.75
+  with :practical, class_name: "PracticalScore", weight: 0.25
 end
 ```
 
@@ -82,9 +97,80 @@ ReportScore.new({
 #> 0.875
 ```
 
+### Working with a score tree
+
+For more complex scenarios, we might need to know more about how the score was composed.
+
+Using the example `ReportScore`, `ExamScore`, and `PracticalScore` classes as
+an example, we can generate a tree of scores:
+
+```ruby
+tree = ReportScore.new({
+  exam: "A",
+  practical: 5
+}).calculate(:tree)
+
+#> tree
+{
+  score: 875.0,
+  max: 1000,
+  deduction: -125.0,
+  with: {
+    exam: {
+      score: 750.0,
+      max: 750.0,
+      deduction: 0.0,
+      weight: 0.75
+    },
+    practical: {
+      score: 125.0,
+      max: 250.0,
+      deduction: -125.0,
+      weight: 0.25
+    }
+  }
+}
+```
+
+This result is a `WAS::Tree` object. Basically a `Hash` with some extra
+added to it.
+
+#### Ordering by attribute
+
+For each of the key attributes `:score`, `:max`, `:weight`, and
+`:deduction`, we can order our tree interally by that key:
+
+```ruby
+#> tree.order(:deduction)
+{
+  score: 875.0,
+  max: 1000,
+  deduction: -125.0
+  with: {
+    practical: {
+      score: 125.0,
+      max: 250.0,
+      deduction: -125.0,
+      weight: 0.25
+    },
+    exam: {
+      score: 750.0,
+      max: 750.0,
+      deduction: 0.0,
+      weight: 0.75
+    }
+  }
+}
+```
+
+For `:deduction`, results adjacent to each other are ordered by the
+_most negative_. For all other options, the values are ordered largest
+value first.
+
 ### View all weights
 
-If you want to see all of the weights that are used to compose the score, there is a convenience method `.weights`:
+If you want to see all of the weights that are used to compose the score,
+there is a convenience method `.weights`:
 
 ```ruby
 ReportScore.weights

data/lib/was/score.rb

@@ -40,20 +40,62 @@ module WAS
       @input = input
     end
 
-    def calculate
-      calculation
+    def calculate(option = nil)
+      return calculation if option != :tree
+
+      calc = calculation(:tree)
+      tree = if calc.is_a?(Hash)
+        calc.merge(additional_score_attributes(calc[:score]))
+      else
+        {}.tap do |t|
+          t.merge!(score: calc)
+          t.merge!(additional_score_attributes(calc))
+        end
+      end
+
+      transform_scores_relative_to_max_score(tree)
     end
 
-    def calculation
+    def calculation(option = nil)
       if contexts?
         context_score_calculation
       else
-        nested_score_calcuation
+        nested_score_calcuation(option)
       end
     end
 
     private
 
+    def additional_score_attributes(score_value)
+      {
+        max: self.class.max_score,
+        deduction: (score_value - self.class.max_score).round(8)
+      }
+    end
+
+    def transform_scores_relative_to_max_score(tree, max_score = nil)
+      max_score = max_score || self.class.max_score
+      return tree if self.class.max_score == 1
+
+      tree.each do |key, value|
+        next if key != :with
+
+        value.each do |scorer, branch|
+          adjust_values_relative_to_max_score(branch, max_score)
+        end
+
+        value.transform_values! do |nested_tree|
+          transform_scores_relative_to_max_score(nested_tree, nested_tree[:max])
+        end
+      end
+    end
+
+    def adjust_values_relative_to_max_score(branch, max_score)
+      branch[:max] = branch[:max] * max_score * branch[:weight]
+      branch[:score] = branch[:score] * branch[:max]
+      branch[:deduction] = branch[:score] - branch[:max]
+    end
+
     def contexts?
       !!self.class.instance_variable_get("@contexts")
     end
@@ -61,16 +103,36 @@ module WAS
     def context_score_calculation
       self.class.instance_variable_get("@contexts").each do |context|
         output = context[:code].call(input)
-        next unless output
+        next if !output
         return context[:score] || output
       end
     end
 
-    def nested_score_calcuation
-      self.class.scorers.sum do |name, scorer|
+    def nested_score_calcuation(option)
+      if option == :tree
+        WAS::Tree.new.tap do |t|
+          t[:score] = sum
+          t[:with]  = with_attribute
+        end
+      else
+        sum
+      end
+    end
+
+    def sum
+      @sum ||= self.class.scorers.sum do |name, scorer|
         score = Object.const_get(scorer[:class_name]).new(input[name.to_sym]).calculate
         score * scorer[:weight]
       end * self.class.max_score
     end
+
+    def with_attribute
+      {}.tap do |with|
+        self.class.scorers.each do |name, scorer|
+          with[name] = Object.const_get(scorer[:class_name]).new(input[name.to_sym]).calculate(:tree)
+          with[name][:weight] = scorer[:weight]
+        end
+      end
+    end
   end
 end

data/lib/was/tree.rb

@@ -0,0 +1,31 @@
+module WAS
+  class Tree < Hash
+    def order(order_key = :deduction)
+      self.dup.tap do |tree|
+        return tree if tree[:with].nil?
+
+        sort_with_by!(order_key, tree)
+      end
+    end
+
+    private
+
+    def sort_with_by!(order_key, tree)
+      return tree if tree[:with].nil?
+
+      tree[:with].each do |_, subtree|
+        sort_with_by!(order_key, subtree)
+      end
+
+      array = tree[:with].sort_by do |_, subtree|
+        subtree[order_key]
+      end
+
+      tree[:with] = if order_key == :deduction
+        array.to_h
+      else
+        array.reverse.to_h
+      end
+    end
+  end
+end

data/lib/was/version.rb

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

data/lib/was.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "was/version"
+require_relative "was/tree"
 require_relative "was/score"
 
 module WAS

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: was
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Mark Connell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-18 00:00:00.000000000 Z
+date: 2025-02-26 00:00:00.000000000 Z
 dependencies: []
 description: A simple gem/dsl for generating Weighted Average Score calculations.
 email:
@@ -23,6 +23,7 @@ files:
 - Rakefile
 - lib/was.rb
 - lib/was/score.rb
+- lib/was/tree.rb
 - lib/was/version.rb
 - sig/was.rbs
 - was.gemspec