type_balancer 0.1.0 → 0.1.3

data/lib/type_balancer/distributor.rb

@@ -2,60 +2,33 @@
 
 module TypeBalancer
   module Distributor
-    class << self
-      def calculate_target_positions(total_count, available_count, ratio, available_items = nil)
-        # Input validation
-        return [] if total_count <= 0 || available_count <= 0 || ratio <= 0 || ratio > 1
-        return [] if available_count > total_count
-
-        # Calculate target count
-        target_count = (total_count * ratio).ceil
-        target_count = [target_count, available_count].min
-
-        # Special cases
-        return [] if target_count.zero?
-        return [available_items&.first || 0] if target_count == 1
-
-        # If specific positions are available, use those
-        if available_items
-          # Ensure available_items are valid
-          available_items = available_items.select { |pos| pos >= 0 && pos < total_count }.sort
-          return [] if available_items.empty?
-
-          # If we have fewer available positions than target count, use what we have
-          target_count = [target_count, available_items.size].min
-
-          # Calculate spacing within available positions
-          return [available_items.first] unless target_count > 1
-
-          step = (available_items.size - 1).to_f / (target_count - 1)
-          return target_count.times.map { |i| available_items[(i * step).round] }
-
-        end
-
-        # Calculate spacing for the general case
-        spacing = total_count.to_f / target_count
-
-        # Generate positions
-        positions = Array.new(target_count)
-        target_count.times do |i|
-          # Calculate ideal position
-          ideal_pos = i * spacing
-
-          # Round to nearest integer, ensuring we don't exceed bounds
-          pos = ideal_pos.round
-          pos = [pos, total_count - 1].min
-          pos = [pos, 0].max
-
-          positions[i] = pos
-        end
-
-        # Ensure positions are unique and sorted
-        positions.uniq!
-        positions.sort!
-
-        positions
+    def self.calculate_target_positions(total_count:, ratio:, available_positions: nil)
+      # Validate inputs
+      return [] if total_count <= 0 || ratio <= 0 || ratio > 1
+
+      # Calculate target count and round down for specific ratios
+      target_count = if ratio <= 0.34
+                       1 # For ratios <= 0.34, always use 1 position
+                     elsif ratio <= 0.67
+                       2 # For ratios <= 0.67, always use 2 positions
+                     else
+                       (total_count * ratio).ceil
+                     end
+
+      return [] if target_count.zero?
+      return (0...total_count).to_a if target_count >= total_count
+
+      # Special case for 3 slots
+      if total_count == 3
+        return [0] if target_count == 1
+        return [0, 1] if target_count == 2
       end
+
+      TypeBalancer::PositionCalculator.calculate_positions(
+        total_count: total_count,
+        ratio: ratio,
+        available_items: available_positions
+      )
     end
   end
 end

data/lib/type_balancer/position_calculator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  class PositionCalculator
+    class << self
+      def calculate_positions(total_count:, ratio:, available_items: nil)
+        return [] unless valid_input?(total_count, ratio)
+
+        target_count = (total_count * ratio).ceil
+        return [] if target_count.zero?
+        return (0...total_count).to_a if target_count >= total_count
+
+        if available_items
+          calculate_with_available_items(available_items, target_count)
+        else
+          calculate_evenly_spaced_positions(total_count, target_count)
+        end
+      end
+
+      private
+
+      def valid_input?(total_count, ratio)
+        total_count.positive? && ratio.positive? && ratio <= 1
+      end
+
+      def calculate_with_available_items(available_items, target_count)
+        return [] if available_items.empty?
+        return [available_items.first] if target_count == 1
+        return [available_items.first, available_items.last] if target_count == 2
+
+        available_items.take(target_count)
+      end
+
+      def calculate_evenly_spaced_positions(total_count, target_count)
+        return [0] if target_count == 1
+
+        max_pos = total_count - 1
+        return [0, max_pos] if target_count == 2
+
+        calculate_multi_position_spacing(max_pos, target_count)
+      end
+
+      def calculate_multi_position_spacing(max_pos, target_count)
+        first_gap = (max_pos / (target_count - 1.0)).ceil
+        positions = [0]
+        remaining_gaps = target_count - 2
+        remaining_space = max_pos - first_gap
+
+        if remaining_gaps.positive?
+          step = remaining_space / remaining_gaps.to_f
+          (1...target_count - 1).each do |i|
+            positions << (first_gap + ((i - 1) * step)).round
+          end
+        end
+
+        positions << max_pos
+        positions
+      end
+    end
+  end
+end

data/lib/type_balancer/ratio_calculator.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Calculates ratios and positions for balanced distribution of items
+  module RatioCalculator
+    module_function
+
+    # Calculate positions for each type based on ratios and batch size
+    #
+    # @param ratios [Hash<String, Float>] Ratios for each type
+    # @param batch_size [Integer] Size of each batch
+    # @return [Hash<String, Array<Integer>>] Positions for each type in batches
+    def calculate_positions(ratios, batch_size)
+      # Initialize variables
+      positions = {}
+      total_positions = 0
+
+      # First pass: Calculate minimum positions for each type
+      ratios.each do |type, ratio|
+        min_positions = (batch_size * ratio).ceil
+        positions[type] = min_positions
+        total_positions += min_positions
+      end
+
+      # Second pass: Adjust if we have too many positions
+      reduce_positions(positions, batch_size) if total_positions > batch_size
+
+      # Third pass: Fill remaining positions if we have too few
+      fill_remaining_positions(positions, batch_size - total_positions, ratios) if total_positions < batch_size
+
+      positions
+    end
+
+    private
+
+    def reduce_positions(positions, target_size)
+      while positions.values.sum > target_size
+        # Find type with most positions relative to its ratio
+        type_to_reduce = positions.max_by { |_, count| count }[0]
+        positions[type_to_reduce] -= 1
+      end
+    end
+
+    def fill_remaining_positions(positions, remaining_count, ratios)
+      remaining_count.times do
+        # Add position to type with lowest current/ratio ratio
+        type_to_increase = find_type_needing_position(positions, ratios)
+        positions[type_to_increase] += 1
+      end
+    end
+
+    def find_type_needing_position(positions, ratios)
+      ratios.min_by { |type, ratio| positions[type].to_f / (ratio * positions.values.sum) }[0]
+    end
+
+    class << self
+      def calculate_ratios(types, items_by_type)
+        return { types.first => 1.0 } if types.size == 1
+
+        type_counts = calculate_type_counts(types, items_by_type)
+        initial_ratios = calculate_initial_ratios(types, type_counts)
+        normalize_ratios(initial_ratios)
+      end
+
+      private
+
+      def calculate_type_counts(types, items_by_type)
+        types.to_h { |type| [type, items_by_type.fetch(type, []).size] }
+      end
+
+      def calculate_initial_ratios(types, type_counts)
+        total_count = type_counts.values.sum.to_f
+        min_ratio = 0.1
+        remaining_ratio = 1.0 - (min_ratio * types.size)
+
+        type_counts.transform_values do |count|
+          if count.zero?
+            min_ratio
+          else
+            min_ratio + ((count / total_count) * remaining_ratio)
+          end
+        end
+      end
+
+      def normalize_ratios(ratios)
+        sum = ratios.values.sum
+        ratios.transform_values { |ratio| ratio / sum }
+      end
+    end
+  end
+end

data/lib/type_balancer/type_extractor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  class TypeExtractor
+    def initialize(type_field)
+      @type_field = type_field
+    end
+
+    def extract_types(collection)
+      collection.map { |item| get_type(item) }.uniq
+    end
+
+    def group_by_type(collection)
+      collection.group_by { |item| get_type(item) }
+    end
+
+    private
+
+    def get_type(item)
+      if item.respond_to?(@type_field)
+        item.send(@type_field)
+      elsif item.respond_to?(:[])
+        item[@type_field] || item[@type_field.to_s]
+      else
+        raise Error, "Cannot access type field '#{@type_field}' on item #{item}"
+      end
+    end
+  end
+end

data/lib/type_balancer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypeBalancer
-  VERSION = '0.1.0'
+  VERSION = '0.1.3'
 end

data/lib/type_balancer.rb

@@ -2,43 +2,62 @@
 
 require 'type_balancer/version'
 require 'type_balancer/calculator'
+require_relative 'type_balancer/balancer'
+require_relative 'type_balancer/ratio_calculator'
+require_relative 'type_balancer/batch_processing'
+require 'type_balancer/position_calculator'
 
 module TypeBalancer
   class Error < StandardError; end
   class ConfigurationError < Error; end
+  class ValidationError < Error; end
+  class EmptyCollectionError < Error; end
+  class InvalidTypeError < Error; end
 
   # Load Ruby implementations
   require_relative 'type_balancer/distribution_calculator'
   require_relative 'type_balancer/ordered_collection_manager'
   require_relative 'type_balancer/alternating_filler'
   require_relative 'type_balancer/sequential_filler'
-  require_relative 'type_balancer/balancer'
   require_relative 'type_balancer/distributor'
 
   def self.calculate_positions(total_count:, ratio:, available_items: nil)
-    PositionCalculator.calculate_positions(
+    Distributor.calculate_target_positions(
       total_count: total_count,
       ratio: ratio,
-      available_items: available_items
+      available_positions: available_items
     )
   end
 
-  def self.balance(collection, type_field: :type, type_order: nil)
-    Balancer.new(collection, type_field: type_field, types: type_order).call
+  def self.balance(items, type_field: :type, type_order: nil)
+    # Input validation
+    raise EmptyCollectionError, 'Collection cannot be empty' if items.empty?
+
+    # Extract and validate types
+    types = extract_types(items, type_field)
+    raise Error, "Invalid type field: #{type_field}" if types.empty?
+
+    # Group items by type
+    items.group_by { |item| extract_type(item, type_field) }
+
+    # Initialize balancer with type order if provided
+    balancer = Balancer.new(types, type_order: type_order)
+
+    # Balance items
+    balancer.call(items)
   end
 
-  def self.extract_types(collection, type_field)
-    collection.map do |item|
-      if item.respond_to?(type_field)
-        item.send(type_field)
-      elsif item.respond_to?(:[])
-        item[type_field] || item[type_field.to_s]
-      else
-        raise Error, "Cannot access type field '#{type_field}' on item #{item}"
-      end
-    end.uniq
+  def self.extract_types(items, type_field)
+    items.map { |item| extract_type(item, type_field) }.uniq
   end
 
-  # Error raised when input validation fails
-  class ValidationError < StandardError; end
+  def self.extract_type(item, type_field)
+    if item.is_a?(Hash)
+      item[type_field] || item[type_field.to_s]
+    else
+      item.public_send(type_field)
+    end
+  rescue NoMethodError
+    nil
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: type_balancer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.3
 platform: ruby
 authors:
 - Carl Smith
 bindir: exe
 cert_chain: []
-date: 2025-04-10 00:00:00.000000000 Z
+date: 2025-04-28 00:00:00.000000000 Z
 dependencies: []
 description: Balances types in collections by ensuring each type appears a similar
   number of times
@@ -17,6 +17,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".DS_Store"
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
@@ -36,18 +37,26 @@ files:
 - benchmark_results/ruby3.3.7_yjit.txt
 - benchmark_results/ruby3.4.2.txt
 - benchmark_results/ruby3.4.2_yjit.txt
+- docs/README.md
+- docs/balance.md
 - docs/benchmarks/README.md
+- docs/calculate_positions.md
+- docs/quality.md
+- examples/balance_test_data.yml
 - examples/quality.rb
 - lib/type_balancer.rb
 - lib/type_balancer/alternating_filler.rb
 - lib/type_balancer/balancer.rb
+- lib/type_balancer/batch_processing.rb
 - lib/type_balancer/calculator.rb
 - lib/type_balancer/distribution_calculator.rb
 - lib/type_balancer/distributor.rb
 - lib/type_balancer/ordered_collection_manager.rb
+- lib/type_balancer/position_calculator.rb
+- lib/type_balancer/ratio_calculator.rb
 - lib/type_balancer/sequential_filler.rb
+- lib/type_balancer/type_extractor.rb
 - lib/type_balancer/version.rb
-- sig/type_balancer.rbs
 - type_balancer.gemspec
 homepage: https://github.com/llwebconsulting/type_balancer
 licenses:

data/sig/type_balancer.rbs

@@ -1,85 +0,0 @@
-module TypeBalancer
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-
-  class Error < StandardError
-  end
-
-  class ConfigurationError < Error
-  end
-
-  class ValidationError < Error
-  end
-
-  # Main class responsible for balancing items in a collection based on their types
-  class Balancer
-    def initialize: (Array[untyped] collection, ?type_field: Symbol | String, ?types: Array[String]?) -> void
-    def call: -> Array[untyped]
-
-    private
-    def calculate_ratios: (Hash[String, Array[untyped]] items_by_type) -> Array[Float]
-    def get_type: (untyped item) -> String
-    def extract_types: -> Array[String]
-  end
-
-  module Ruby
-    class Calculator
-      def self.calculate_positions: (total_count: Integer, ratio: Float, ?available_items: Array[Integer]?) -> Array[Integer]
-
-      private
-      def self.validate_inputs: (Integer total_count, Float ratio) -> void
-      def self.validate_available_items: (Array[Integer]? available_items, Integer total_count) -> void
-      def self.calculate_positions_without_available: (Integer total_count, Integer target_count) -> Array[Integer]
-      def self.calculate_positions_with_available: (Integer total_count, Integer target_count, Array[Integer] available_items) -> Array[Integer]
-    end
-
-    class BatchCalculator
-      class PositionBatch
-        attr_reader total_count: Integer
-        attr_reader available_count: Integer
-        attr_reader ratio: Float
-
-        def initialize: (total_count: Integer, available_count: Integer, ratio: Float) -> void
-        def valid?: -> bool
-      end
-
-      def self.calculate_positions_batch: (PositionBatch batch, ?Integer iterations) -> Array[Integer]
-      private
-      def self.calculate_target_count: (PositionBatch batch) -> Integer
-    end
-  end
-
-  class OrderedCollectionManager
-    def initialize: (Integer size) -> void
-    def place_at_positions: (Array[untyped] items, Array[Integer] positions) -> void
-    def fill_gaps_alternating: (Array[untyped] primary_items, Array[untyped] secondary_items) -> void
-    def fill_remaining_gaps: (Array[Array[untyped]] items_arrays) -> void
-    def result: -> Array[untyped]
-    private
-    def find_empty_positions: -> Array[Integer]
-  end
-
-  class SequentialFiller
-    def initialize: (Array[untyped] collection, Array[Array[untyped]] items_arrays) -> void
-    def self.fill: (Array[untyped] collection, Array[Integer] positions, Array[Array[untyped]] items_arrays) -> void
-    def fill_gaps: (Array[Integer] positions) -> void
-  end
-
-  class AlternatingFiller
-    def initialize: (Array[untyped] collection, Array[untyped] primary_items, Array[untyped] secondary_items) -> void
-    def self.fill: (Array[untyped] collection, Array[Integer] positions, Array[untyped] primary_items, Array[untyped] secondary_items) -> void
-    def fill_gaps: (Array[Integer] positions) -> void
-  end
-
-  class DistributionCalculator
-    def initialize: (?Float target_ratio) -> void
-    def calculate_target_positions: (Integer total_count, Integer available_items_count, ?Float target_ratio) -> Array[Integer]
-  end
-
-  module Distributor
-    def self.calculate_target_positions: (Integer total_count, Integer available_count, Float ratio) -> Array[Integer]
-  end
-
-  def self.balance: (Array[untyped] collection, ?type_field: Symbol | String, ?type_order: Array[String]?) -> Array[untyped]
-  def self.extract_types: (Array[untyped] collection, Symbol | String type_field) -> Array[String]
-end