was 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32828b1a84ec32fd591c751dcb5df91f277af4d6bc840179b9070345f3345e24
-  data.tar.gz: 57bfb59c5ee299e3e0ed0376e44b4ad0c62f98ca23574cf366fc5f7461a1dd95
+  metadata.gz: 974fa97c47b4fe794512983c75fa065b9bdd40370e5987b1e4523d01791bdd2a
+  data.tar.gz: 9f6e783dd2fbad215e8c2b16c820a1b8642b843efba424ed2d35e5aa1e7e2b92
 SHA512:
-  metadata.gz: e006ec3f57273eafe64336a6ba55efc358bed7064a11be9ff67089a147b3683e8452c447d09caf59f306a573265ab52bc4f1fd411f25e5020b3773a55355df4d
-  data.tar.gz: 24f01eb4452fa8b691bbcf1c639cd16ae72d53f10920f2482281ef853ce0b0f9b792aea36c3a7498a2caf22f2ced4aecc3fa5f0e8bf46d9ee2d387c4234cbfeb
+  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,8 +31,8 @@ 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
@@ -77,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
 ```
 
@@ -91,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

@@ -45,9 +45,12 @@ module WAS
 
       calc = calculation(:tree)
       tree = if calc.is_a?(Hash)
-        calc.merge({ max: self.class.max_score })
+        calc.merge(additional_score_attributes(calc[:score]))
       else
-        { score: calc }.merge({ max: self.class.max_score })
+        {}.tap do |t|
+          t.merge!(score: calc)
+          t.merge!(additional_score_attributes(calc))
+        end
       end
 
       transform_scores_relative_to_max_score(tree)
@@ -63,6 +66,13 @@ module WAS
 
     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
@@ -71,7 +81,7 @@ module WAS
         next if key != :with
 
         value.each do |scorer, branch|
-          adjust_branch_score_and_max(branch, max_score)
+          adjust_values_relative_to_max_score(branch, max_score)
         end
 
         value.transform_values! do |nested_tree|
@@ -80,9 +90,10 @@ module WAS
       end
     end
 
-    def adjust_branch_score_and_max(branch, max_score)
-      branch[:max]   = branch[:max] * max_score * branch[:weight]
+    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?
@@ -99,7 +110,10 @@ module WAS
 
     def nested_score_calcuation(option)
       if option == :tree
-        { score: sum, with: with_attribute }
+        WAS::Tree.new.tap do |t|
+          t[:score] = sum
+          t[:with]  = with_attribute
+        end
       else
         sum
       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.7.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.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Mark Connell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-02-20 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