differential 1.0.1

data/lib/differential/calculator/group.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Differential
+  module Calculator
+    # A Report has 0 or more Group objects and a Group has 0 or more Item objects.
+    # Report -> Group -> Item
+    # A Group is, as the name implies, a grouping of items.  It is up to the consumer application
+    # to define how to group (i.e. group based on this attribute's value or
+    # group based on these two  attributes' values.)
+    class Group
+      include ::Differential::Calculator::HasTotals
+
+      attr_reader :id
+
+      def initialize(id)
+        raise ArgumentError, 'id is required' unless id
+
+        @id = id
+      end
+
+      def items
+        items_by_id.values
+      end
+
+      def add(record, side)
+        raise ArgumentError, 'record is required' unless record
+        raise ArgumentError, 'side is required'   unless side
+        raise ArgumentError, "mismatch: #{record.group_id} != #{id}" if id != record.group_id
+
+        totals.add(record.value, side)
+
+        upsert_item(record, side)
+
+        self
+      end
+
+      private
+
+      def upsert_item(record, side)
+        item_id = record.id
+
+        # Create a new item if one does not exist
+        items_by_id[item_id] = Item.new(item_id) unless items_by_id.key?(item_id)
+
+        items_by_id[item_id].add(record, side)
+
+        nil
+      end
+
+      def items_by_id
+        @items_by_id ||= {}
+      end
+    end
+  end
+end

data/lib/differential/calculator/has_totals.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Differential
+  module Calculator
+    # There are multiple classes that all need calculation support (The Total class.)
+    # Instead of using inheritance, those classes can use this mix-in for composition.
+    module HasTotals
+      extend Forwardable
+
+      def_delegators :totals, :a_sigma, :b_sigma, :delta
+
+      def totals
+        @totals ||= ::Differential::Calculator::Totals.new
+      end
+    end
+  end
+end

data/lib/differential/calculator/item.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Differential
+  module Calculator
+    # Consider this as being line-level and is the lowest point of calculation.
+    # Ultimately a Report object will turn all added Record objects into Item objects (placed
+    # in Group objects.)
+    class Item
+      include ::Differential::Calculator::HasTotals
+      include ::Differential::Calculator::Side
+
+      attr_reader :id, :a_records, :b_records
+
+      def initialize(id)
+        raise ArgumentError, 'id is required' unless id
+
+        @id         = id
+        @a_records  = []
+        @b_records  = []
+      end
+
+      def add(record, side)
+        raise ArgumentError, 'record is required' unless record
+        raise ArgumentError, 'side is required'   unless side
+        raise ArgumentError, "mismatch: #{record.id} != #{id}" if id != record.id
+
+        totals.add(record.value, side)
+
+        account_for_record(record, side)
+
+        self
+      end
+
+      private
+
+      def account_for_record(record, side)
+        case side
+        when A
+          @a_records << record
+        when B
+          @b_records << record
+        else
+          raise ArgumentError, "unknown side: #{side}"
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/differential/calculator/report.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Differential
+  module Calculator
+    # This class is responsible for building an entire report.  Usage:
+    # - Instantiate a Reader.
+    # - Instantiate a Report.
+    # - Feed in dataset(s) into the Reader to generate Record objects.
+    # - Feed in Record objects, generated by a Reader, by calling Report#add.
+    # The Report object will keep running sums and deltas of all added records.
+    class Report
+      include HasTotals
+
+      def groups
+        groups_by_id.values
+      end
+
+      def add(record, side)
+        raise ArgumentError, 'record is required' unless record
+        raise ArgumentError, 'side is required'   unless side
+
+        totals.add(record.value, side)
+
+        upsert_group(record, side)
+
+        self
+      end
+
+      private
+
+      def upsert_group(record, side)
+        group_id = record.group_id
+
+        # Create a new group if one does not exist
+        groups_by_id[group_id] = Group.new(group_id) unless groups_by_id.key?(group_id)
+
+        groups_by_id[group_id].add(record, side)
+
+        nil
+      end
+
+      def groups_by_id
+        @groups_by_id ||= {}
+      end
+    end
+  end
+end

data/lib/differential/calculator/side.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Differential
+  module Calculator
+    # Differential can currently only compute calculations for two datasets, represented as:
+    # A and B.  Ultimately, how you define what A and B are up to the consuming application.
+    module Side
+      A = :a
+      B = :b
+    end
+  end
+end

data/lib/differential/calculator/totals.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Differential
+  module Calculator
+    # Value object that can capture basic calculations:
+    # - a_sigma is the sum of data set A's values.
+    # - b_sigma is the sum of data set B's values.
+    # - delta is the difference: b_sigma - a_sigma.
+    class Totals
+      include ::Differential::Calculator::Side
+
+      attr_reader :a_sigma, :b_sigma
+
+      def initialize
+        @a_sigma = 0
+        @b_sigma = 0
+      end
+
+      def delta
+        b_sigma - a_sigma
+      end
+
+      def add(value, side)
+        case side
+        when A
+          @a_sigma += value
+        when B
+          @b_sigma += value
+        else
+          raise ArgumentError, "unknown side: #{side}"
+        end
+
+        self
+      end
+    end
+  end
+end

data/lib/differential/differential.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require 'forwardable'
+
+require_relative 'calculator/calculator'
+require_relative 'parser/parser'
+
+# This module will serve as the top-level entry point for consumers.
+# You can stick with the API provided here unless you know the internals behind this point.
+module Differential
+  extend ::Differential::Calculator::Side
+
+  class << self
+    def calculate(dataset_a: [], dataset_b: [], reader_config: {})
+      reader = ::Differential::Parser::Reader.new(reader_config)
+      report = ::Differential::Calculator::Report.new
+
+      reader.each(dataset_a) { |record| report.add(record, A) }
+      reader.each(dataset_b) { |record| report.add(record, B) }
+
+      report
+    end
+  end
+end

data/lib/differential/parser/parser.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require_relative 'reader'
+require_relative 'record'

data/lib/differential/parser/reader.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Differential
+  module Parser
+    # This class is used to parse incoming datasets.
+    # Usage:
+    # Instantiate new object with configuration options.
+    # Call read to parse individual hash objects into Record objects.
+    class Reader
+      attr_reader :record_id_key,
+                  :value_key,
+                  :group_id_key
+
+      # Params:
+      # +record_id_key+:: The hash key(s) to use to uniquely identify a record (required)
+      # +value_key+:: The hash key used to extract the value of the record.
+      # +group_id_key+:: The hash key(s) to use to identify which group the record belongs to.
+      def initialize(record_id_key:, value_key:, group_id_key: nil)
+        raise ArgumentError, 'record_id_key is required'  unless record_id_key
+        raise ArgumentError, 'value_key is required'      unless value_key
+
+        @record_id_key  = record_id_key
+        @value_key      = value_key
+        @group_id_key   = group_id_key
+      end
+
+      def each(hashes)
+        return enum_for(:each) unless block_given?
+
+        hashes.each do |hash|
+          record = read(hash)
+          yield record
+        end
+      end
+
+      private
+
+      def read(hash)
+        id        = make_record_id(hash)
+        group_id  = make_group_id(hash)
+        value     = hash[value_key]
+
+        ::Differential::Parser::Record.new(id:        id,
+                                           group_id:  group_id,
+                                           value:     value,
+                                           data:      hash)
+      end
+
+      def make_record_id(hash)
+        record_id_key_array.map { |k| hash[k] }.join(':')
+      end
+
+      def make_group_id(hash)
+        group_id_key_array.map { |k| hash[k] }.join(':')
+      end
+
+      def record_id_key_array
+        @record_id_key_array ||= Array(record_id_key)
+      end
+
+      def group_id_key_array
+        @group_id_key_array ||= Array(group_id_key)
+      end
+    end
+  end
+end

data/lib/differential/parser/record.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Differential
+  module Parser
+    # Represents a parsed record object.  This is ultimately what a Reader creates and
+    # is serves as input into the Calculator module.
+    class Record
+      attr_reader :id, :group_id, :value, :data
+
+      def initialize(id:, group_id:, value:, data:)
+        @id       = id
+        @group_id = group_id
+        @value    = value
+        @data     = data
+      end
+    end
+  end
+end

data/lib/differential/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Differential
+  VERSION = '1.0.1'
+end

data/spec/differential/calculator/report_spec.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2018-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+require './spec/spec_helper'
+
+describe ::Differential::Calculator::Report do
+  it 'should initialize correctly' do
+    report = ::Differential::Calculator::Report.new
+
+    expect(report.a_sigma).to eq(0)
+    expect(report.b_sigma).to eq(0)
+    expect(report.delta).to   eq(0)
+  end
+
+  let(:group_1_plus8) do
+    ::Differential::Parser::Record.new(id: '1', group_id: '1', value: 8, data: { id: '1' })
+  end
+
+  let(:group_1_minus9) do
+    ::Differential::Parser::Record.new(id: '1', group_id: '1', value: -9, data: { id: '1' })
+  end
+
+  let(:group_2_plus3) do
+    ::Differential::Parser::Record.new(id: '2', group_id: '2', value: 3, data: { id: '1' })
+  end
+
+  let(:group_2_minus2) do
+    ::Differential::Parser::Record.new(id: '3', group_id: '2', value: -2, data: { id: '1' })
+  end
+
+  context 'when totaling sigma and deltas at report level' do
+    it 'should compute sigma & delta correctly' do
+      report = ::Differential::Calculator::Report.new
+
+      report.add(group_1_plus8, ::Differential::Calculator::Side::A)
+
+      expect(report.a_sigma).to eq(group_1_plus8.value)
+      expect(report.b_sigma).to eq(0)
+      expect(report.delta).to   eq(-group_1_plus8.value)
+
+      report.add(group_1_minus9, ::Differential::Calculator::Side::B)
+
+      expect(report.a_sigma).to eq(group_1_plus8.value)
+      expect(report.b_sigma).to eq(group_1_minus9.value)
+      expect(report.delta).to   eq(group_1_minus9.value - group_1_plus8.value)
+    end
+  end
+
+  context 'when totaling sigma and deltas at group level' do
+    it 'should compute sigma & delta correctly' do
+      report = ::Differential::Calculator::Report.new
+
+      report.add(group_1_plus8, ::Differential::Calculator::Side::A)
+
+      group1 = report.groups.first
+
+      expect(report.groups.length).to eq(1)
+      expect(group1.id).to eq(group_1_plus8.group_id)
+      expect(group1.a_sigma).to eq(group_1_plus8.value)
+      expect(group1.b_sigma).to eq(0)
+      expect(group1.delta).to eq(-group_1_plus8.value)
+
+      report.add(group_1_minus9, ::Differential::Calculator::Side::B)
+
+      group1 = report.groups.first
+
+      expect(report.groups.length).to eq(1)
+      expect(group1.id).to eq(group_1_plus8.group_id)
+      expect(group1.a_sigma).to eq(group_1_plus8.value)
+      expect(group1.b_sigma).to eq(group_1_minus9.value)
+      expect(group1.delta).to eq(group_1_minus9.value - group_1_plus8.value)
+
+      report.add(group_2_plus3, ::Differential::Calculator::Side::A)
+
+      group2 = report.groups.last
+
+      expect(report.groups.length).to eq(2)
+      expect(group2.id).to eq(group_2_plus3.group_id)
+      expect(group2.a_sigma).to eq(group_2_plus3.value)
+      expect(group2.b_sigma).to eq(0)
+      expect(group2.delta).to eq(-group_2_plus3.value)
+
+      report.add(group_2_minus2, ::Differential::Calculator::Side::B)
+
+      group2 = report.groups.last
+
+      expect(report.groups.length).to eq(2)
+      expect(group2.id).to eq(group_2_plus3.group_id)
+      expect(group2.a_sigma).to eq(group_2_plus3.value)
+      expect(group2.b_sigma).to eq(group_2_minus2.value)
+      expect(group2.delta).to eq(group_2_minus2.value - group_2_plus3.value)
+    end
+  end
+
+  context 'when totaling sigma and deltas at item level' do
+    it 'should compute sigma & delta correctly' do
+      report = ::Differential::Calculator::Report.new
+
+      report.add(group_1_plus8,   ::Differential::Calculator::Side::A)
+      report.add(group_1_minus9,  ::Differential::Calculator::Side::B)
+      report.add(group_2_plus3,   ::Differential::Calculator::Side::A)
+      report.add(group_2_minus2,  ::Differential::Calculator::Side::B)
+
+      group1 = report.groups.first
+      group2 = report.groups.last
+
+      expect(group1.items.length).to eq(1)
+      expect(group2.items.length).to eq(2)
+
+      group1_item1 = group1.items.first
+
+      expect(group1_item1.id).to eq(group_1_plus8.id)
+      expect(group1_item1.a_sigma).to eq(group_1_plus8.value)
+      expect(group1_item1.b_sigma).to eq(group_1_minus9.value)
+      expect(group1_item1.delta).to eq(group_1_minus9.value - group_1_plus8.value)
+
+      group2_item1 = group2.items.first
+      group2_item2 = group2.items.last
+
+      expect(group2_item1.id).to eq(group_2_plus3.id)
+      expect(group2_item1.a_sigma).to eq(group_2_plus3.value)
+      expect(group2_item1.b_sigma).to eq(0)
+      expect(group2_item1.delta).to eq(-group_2_plus3.value)
+
+      expect(group2_item2.id).to eq(group_2_minus2.id)
+      expect(group2_item2.a_sigma).to eq(0)
+      expect(group2_item2.b_sigma).to eq(group_2_minus2.value)
+      expect(group2_item2.delta).to eq(group_2_minus2.value)
+    end
+  end
+end