MBPSO_Team_Formation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b95dd736a6a8ee8c4af23f99ec498287a3fe7fbcf562c958d68ad5e73e3e2cb
+  data.tar.gz: 6c4006ed7edb1b9979d4eaa2a46aa1b374386c6a6c3ddf75e5c1fabb7a136179
+SHA512:
+  metadata.gz: 807a0817d4a3cbb3af15251462f8f757f02c5734c859e064678e39f3686c358296238c045b5436ef889ef52cb5cb3ae8590ae5bba95946c4f3dd8b1a20e5a491
+  data.tar.gz: 4466bd9d512f0ba43eec8dc86d081a9cf18b793aace5d274f2270a13686b0c861b9c1af26e4fe8eb77b5c5ce8cb89828c1be29839e644f7097804c2fae7c693f

data/lib/MBPSO_Team_Formation.rb

@@ -0,0 +1,9 @@
+
+module MBPSOTeamFormation
+require 'MBPSO_Team_Formation/version'
+require 'MBPSO_Team_Formation/mbpso'
+require 'MBPSO_Team_Formation/validation'
+require "MBPSO_Team_Formation/neighbourhood"
+require "MBPSO_Team_Formation/particle"
+
+end

data/lib/MBPSO_Team_Formation/mbpso.rb

@@ -0,0 +1,401 @@
+# frozen_string_literal: true
+
+require_relative 'neighbourhood'
+require_relative 'validation'
+require_relative 'mvh'
+require 'fileutils'
+
+module MBPSOTeamFormation
+  # Containing the needed functionality for validating the input data, instantiating all needed objects and running tha algorithm
+  class MBPSO
+
+    def initialize(table, team_size: 4, max_iterations: 10000, num_particles: 20, \
+                   gender_weight: 9, ethnicity_weight: 9, initial_inertia: 1.0, final_inertia: 0.2, \
+                   control_param_personal: [0.2, 0.4, 0.55], control_param_local: [0.6, 0.2, 0.9], \
+                   survival_number: nil, final_survival_number: 8, \
+                   skill_table: {0..39 => 1, 40..49 => 2, 50..59 => 3, 60..69 => 4, 70..79 => 5, 80..100 => 6}, \
+                   forbidden_pairs: nil, tolerate_missing_values: true, init_num_particles: 3, \
+                   output_stats: false, output_stats_name: 'stats.csv', neigh_change_interval: 100, inertia_change_interval: 10, \
+                   sn_change_interval: 10, particles_to_move: 2, inertia_changes: 300, sn_changes: 300, convergence_iterations: 300)
+
+      validation = Validation.new
+      mvh = MVH.new
+
+      @table = validation.validate_dataset(table).dup
+      @length = table.length # Extracting number of students
+
+      @teams_size = validation\
+               .validate_number(team_size, 'teams', 'pos_int')
+      # Validating inputs
+      @teams = (@length / @teams_size).to_i
+      @max_iterations = validation\
+                        .validate_number(max_iterations, 'max_iterations', 'pos_int')
+      @num_particles = validation\
+                       .validate_number(num_particles, 'num_particles', 'pos_int')
+      @neigh_change_interval = validation\
+                               .validate_number(neigh_change_interval, 'neigh_change_interval', 'pos_int')
+      @init_num_particles = validation\
+                            .validate_number(init_num_particles, 'init_num_particles', 'pos_int')
+      @inertia_change_interval = validation\
+                                 .validate_number(inertia_change_interval, 'inertia_change_interval', 'pos_int')
+      @sn_change_interval = validation\
+                            .validate_number(sn_change_interval, 'sn_change_interval', 'pos_int')
+      @particles_to_move = validation\
+                           .validate_number(particles_to_move, 'particles_to_move', 'pos_int')
+      @final_survival_number = validation\
+                               .validate_number(final_survival_number, 'final_survival_number', 'pos_int')
+      @inertia_changes = validation\
+                         .validate_number(inertia_changes, 'inertia_changes', 'pos_int')
+      @sn_changes = validation\
+                    .validate_number(sn_changes, 'sn_changes', 'pos_int')
+      @convergence_iterations = validation\
+                                .validate_number(convergence_iterations, 'convergence_iterations', 'pos_int')
+      @gender_weight = validation\
+                       .validate_number(gender_weight, 'gender_weight', 'nn_num')
+      @ethnicity_weight = validation\
+                          .validate_number(ethnicity_weight, 'ethnicity_weight', 'nn_num')
+      @initial_inertia = validation\
+                         .validate_number(initial_inertia, 'initial_inertia', 'nn_num')
+      @final_inertia = validation\
+                       .validate_number(final_inertia, 'final_inertia', 'nn_num')
+      @control_param_personal = validation\
+                                .validate_control_parameters(control_param_personal, 'personal')
+      @control_param_local = validation\
+                             .validate_control_parameters(control_param_local, 'local')
+      if survival_number.nil?
+        @survival_number = @length.to_f
+      else
+        @survival_number = validation\
+                           .validate_survival_number(survival_number, @length).to_f
+      end
+      unless forbidden_pairs.nil?
+        @forbidden_pairs = validation\
+                           .validate_forbidden_pairs(forbidden_pairs).dup
+      end
+
+      @output_stats_name = output_stats_name.to_s
+      @skill_table = validation\
+                     .validate_skill_table(skill_table)
+      @output_stats = validation\
+                      .validate_bool(output_stats, 'output_stats')
+      medians = mvh\
+                .fill_missing_values(table, \
+                                     validation.validate_bool(tolerate_missing_values, 'tolerate_missing_values'))
+
+      # Variable that will hold the extra students, in case the class size
+      # is not a multiple of the team size
+      @separated = nil
+      separate_students(medians)
+      map_grades
+
+      unless forbidden_pairs.nil?
+        @forbidden_pairs = {}
+        hash_forbidden_pairs(validation\
+                             .validate_forbidden_pairs(forbidden_pairs))
+      end
+
+
+      # Calculating neighbourhood count and creating neighbours
+      @num_neighbourhoods = (@num_particles / @init_num_particles).to_i
+      # Adding additional neighbourhood when particles cannot be separated
+      # into neighbourhoods of equal size
+      if (@num_particles % @init_num_particles).positive?
+        @num_neighbourhoods += 1
+      end
+      @neighbourhoods_list = Array.new(@num_neighbourhoods)
+      initialise_neighbourhoods
+
+      # Calculating by how much inertia and survival number
+      # will be changed at each of their updates
+      @inertia_step = ((@initial_inertia - @final_inertia) / @inertia_changes).abs
+      @sn_step = ((@survival_number - @final_survival_number) / @sn_changes).abs
+
+      # For move_particles method, so we dont always start adding
+      # to the first neighbourhood, in case of unequal size neighbourhoods
+      @iter = 0
+
+      # Variables needed for outputting the values during tests
+      @average_global_bests = []
+      @global_bests = []
+
+      # Current iteration indicator
+      @iteration = 0
+    end
+
+    # Separating the needed number of students(between 1 and 3), which will be
+    # added to teams at the last stage, by looking for students matching the
+    # median values of each attributes
+    def separate_students(medians)
+
+      most_frequent_gender = medians[0]
+      most_frequent_ethnicity = medians[1]
+      mean = medians[2]
+      stdev = medians[3]
+      # Checking if the step is needed, terminating otherwise,
+      # also holding the number of students that need to be separated
+      remainder = @length % @teams_size
+      return true if remainder.zero?
+
+      @separated = CSV::Table.new([], headers: %w[id Gender Ethnicity Grade])
+      # Searching for students with attributes matching the most frequent
+      # non numeric values and mean +- the standard deviation grades
+      (0..@length - 1).each do |x|
+        # Safety preacution because of the @length update after
+        # the number of iterations is calculated
+        break if x == @length
+        next unless @table[x]['Gender'] == most_frequent_gender
+
+        next unless @table[x]['Ethnicity'] == most_frequent_ethnicity
+
+        next unless (@table[x]['Grade'].to_f < mean + stdev) || (x['Grade'].to_f > mean - stdev)
+
+        @separated << @table.delete(x)
+
+        remainder -= 1
+        @length -= 1
+        # iterating until no more students are needed to be separated
+        return true if remainder.zero?
+      end
+
+      # If not enough students are found
+      # looks for students only having average grade
+      (0..@length-1).each do |x|
+        break if x == @length
+        next unless (@table[x]['Grade'].to_f < mean + stdev) || (x['Grade'].to_f > mean - stdev)
+        @separated << @table.delete(x)
+        remainder -= 1
+        @length -= 1
+        return true if remainder.zero?
+      end
+
+      # If it fails again. randomly separates students
+      (0..@length - 1).each do |x|
+        break if x == @length
+        y = rand(@table.length - 1)
+
+
+        @separated << @table.delete(y)
+        remainder -= 1
+        @length -= 1
+        return true if remainder.zero?
+      end
+
+    end
+
+    # Replacing the grade entries in the data set variable with skill values
+    # according to the skill mapping Hash
+    def map_grades
+      (0..@length - 1).each do |x|
+        @table[x]['Grade'] = @skill_table\
+                             .find { |r, _v| r.cover?(@table[x]['Grade'].to_i) }[1]
+      end
+    end
+
+    # Reworking the forbidden pairs list, by making it a Hash where for every
+    # students participating in at least one pair, there will be a key with
+    # its ID and a corresponding list of IDs of students which this student
+    # cannot be teamed up with
+    def hash_forbidden_pairs(list)
+      # Adding the reversed pairs of students to the list
+      (0..list.length - 1).each do |x|
+        list.push([list[x][1], list[x][0]])
+      end
+
+      # Making all unique first elements of the pairs in the list keys of the Hash
+      keys = list.map(&:first).uniq
+      # Adding the corresponding values, specified by the second elements in the pairs
+      @forbidden_pairs = keys.map do |k|
+        {k => list.select { |a| a[0] == k }.compact.map(&:last)}
+      end
+      @forbidden_pairs = @forbidden_pairs.reduce({}, :merge)
+      # Removing unique values for each key
+      @forbidden_pairs.keys.each do |x|
+        @forbidden_pairs[x] = @forbidden_pairs[x].uniq
+      end
+    end
+
+    # Initialising the needed number of initial neighbourhoods according to
+    # the user-specified/default parameters
+    def initialise_neighbourhoods
+
+      # With the implementation below, there is
+      # a danger of division by 0 exception
+      # if a single neighbourhood needs to be formed
+      if @num_neighbourhoods == 1
+        @neighbourhoods_list[0] = Neighbourhood\
+                                  .new(@length, @teams, @control_param_personal, @control_param_local, \
+                                       @initial_inertia, @table, @ethnicity_weight, @gender_weight, \
+                                       @init_num_particles, @forbidden_pairs, @survival_number)
+      return true
+      end
+
+      # Initialising all full capacity neighbourhoods
+      (0..@num_neighbourhoods - 2).each do |x|
+        @neighbourhoods_list[x] = Neighbourhood\
+                                  .new(@length, @teams, @control_param_personal, @control_param_local, \
+                                       @initial_inertia, @table, @ethnicity_weight, @gender_weight, \
+                                       @init_num_particles, @forbidden_pairs, @survival_number)
+
+      end
+
+      # Initialising the last neighbourhood which will hold a number
+      # of particles equal to the remained of the division of
+      # the particles number by the initial number of
+      # particles in each neighbourhood
+      @neighbourhoods_list[@num_neighbourhoods - 1] = Neighbourhood\
+                                                      .new(@length, @teams, \
+                                                           @control_param_personal, @control_param_local, @initial_inertia, @table, \
+                                                           @ethnicity_weight, @gender_weight, (@num_particles % (@num_neighbourhoods - 1)), \
+                                                           @forbidden_pairs, @survival_number)
+    end
+
+    # Moving the particles from the last neighbourhood
+    # towards the other neighbourhoods
+    def move_particles
+      moved_particles = 0
+      num_to_move = 2 #@neighbourhoods_list.last.particles_list.size
+      @neighbourhoods_list[0].counter = 0
+
+      while moved_particles != num_to_move && @neighbourhoods_list.length > 1
+        temp = @neighbourhoods_list.last.remove_particle
+
+        # Checking if a particle was removed, or the neighbourhood is empty
+        if temp.nil?
+          @neighbourhoods_list.pop
+        else
+          @neighbourhoods_list[@iter].add_particle(temp)
+
+          # increase the counter indicating to which neighbourhood
+          # the next particle will be added, so they're
+          # added to different neighbourhoods on a roulette principle
+          @iter += 1
+          moved_particles += 1
+        end
+
+        # Start over if a particle was added to each neighbourhood
+        @iter = 0 if @iter == @neighbourhoods_list.length - 1
+      end
+    end
+
+    # Update inertia and topology, at the needed iterations
+    def update_characteristics
+      # Invoking method for topology update if needed
+      if (@iteration % @neigh_change_interval).zero? && @neighbourhoods_list.length > 1
+        move_particles
+      end
+
+      if (@iteration % @sn_change_interval).zero? && (@survival_number > @final_survival_number)
+        @survival_number -= @sn_step
+        @neighbourhoods_list.each do |x|
+          x.update_sn(@survival_number.to_i)
+        end
+        @neighbourhoods_list[0].counter = 0
+      end
+
+      # Checking if inertia should be updated
+      return unless (@iteration % @inertia_change_interval).zero? && (@initial_inertia - @inertia_step) > @final_inertia
+
+      # Resetting converge check counter
+      @neighbourhoods_list[0].counter = 0
+
+      # Calculating new inertia with the precaution of not going past the final value
+
+      @initial_inertia -= @inertia_step
+      # Asking each neighbourhoods to update the inertia weights
+      # of all the particles that belong to it
+      @neighbourhoods_list.each do |x|
+        x.update_inertia(@initial_inertia)
+      end
+
+    end
+
+    # Writing the statistics about the algorithm run to an
+    # external .csv file
+    def export_data
+      folder = "\data"
+      FileUtils.mkdir_p folder
+      CSV.open(File.join(folder, @output_stats_name), 'wb') do |csv|
+        csv << @global_bests
+        csv << @average_global_bests
+        @neighbourhoods_list[0].report_particles.each do |x|
+          csv << x
+        end
+      end
+    end
+
+    # Assigning the separated at the beginning students to random teams
+    # If there were any separated students
+    def assign_separated(result)
+      prev_rand = 0
+      (0..@separated.length-1).each do |x|
+        curr_rand = rand(@teams)
+
+        # Making sure that no more than one of the separated students
+        # is added to a given team, regardless of the probability of that happening
+        curr_rand = rand(@teams) while curr_rand == prev_rand
+        result[curr_rand].append(@separated[x]['id'])
+        prev_rand = curr_rand
+      end
+    end
+
+    # Formatiing and returning the output
+    #
+    # @return [Array] Team allocation in the form of list of lists
+    # containing the IDs of the students allocated to each team
+    def return_teams
+      result = Array.new(@teams) { [] }
+      allocation = @neighbourhoods_list[0].l_best_position
+      (0..@length - 1).each do |x|
+        (0..@teams - 1).each do |y|
+          result[y].append(@table[x]['id']) if allocation[x][y] == 1
+        end
+      end
+      # If there are any separated students
+      # Assign them to teams
+      assign_separated(result) unless @separated.nil?
+      result
+    end
+
+    # Starting the algorithm
+    def run
+      while @max_iterations > @iteration
+        # Array that will contain the local bests for the current iteration
+        temp = []
+
+        # Get every neighbourhood to iterate all its particles
+        @neighbourhoods_list.each do |x|
+          x.iterate_particles
+          temp.push(x.l_best_fitness)
+        end
+
+        # Add the global bests and the average local best fitness
+        # to the values storing them
+        @global_bests << temp.max
+        @average_global_bests << (temp.sum / temp.length)
+        @iteration += 1
+
+        # Check if the first neighbourhood is signalling for
+        # a long period with no improvements in the local best fitness
+        if @neighbourhoods_list[0].counter > @convergence_iterations
+          @iteration = @max_iterations
+        end
+
+        # Invoke the method that will check if the control
+        # parameters need to be updated and will act accordingly
+        update_characteristics
+      end
+
+      # Check if exporting the run statistics are desired by the user
+      # and export if needed
+      export_data if @output_stats
+
+      # Printing the attributes of the best allcoation
+      @neighbourhoods_list[0].print_best
+
+      # Return the proposed allocation
+      return_teams
+    end
+
+    private :separate_students, :map_grades, :hash_forbidden_pairs, :initialise_neighbourhoods, :move_particles
+  end
+end

data/lib/MBPSO_Team_Formation/mvh.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+module MBPSOTeamFormation
+  # Missing Values Handler
+  class MVH
+
+
+    # Checking for missing values in the data set
+    def check_missing_values(table)
+      temp = Array.new(3) { [] } # Array that will hold the results, each array
+      # inside it holds the indexes for a particular attribute
+
+      # Checking Genders
+      (0..table['Gender'].length - 1).each do |x|
+        temp[0].append(x) if table['Gender'][x].nil?
+      end
+
+      # Checking ethnicities
+      (0..table['Ethnicity'].length - 1).each do |x|
+        temp[1].append(x) if table['Ethnicity'][x].nil?
+      end
+
+      # Checking grades
+      (0..table['Grade'].length - 1).each do |x|
+        temp[2].append(x) if table['Grade'][x].nil?
+      end
+
+      # Checking results
+      if !temp[0].empty? || !temp[1].empty? || !temp[2].empty?
+        temp
+      else
+        false
+      end
+    end
+
+    # Calculating the mean and standard deviation of data,
+    # to be used when replacing missing grades
+    def calculate_stdev(data)
+      data = data.compact.map(&:to_i)
+      mean = data.sum.to_f / data.size
+      sum = 0
+
+      data.each { |v| sum += (v - mean) ** 2 }
+      stdev = Math.sqrt(sum / data.size)
+
+      [mean, stdev]
+    end
+
+    # Replacing missing values by the most frequent values for non-numeric
+    # attributes and keeping original distribution when it comes to grades
+    def fill_missing_values(table, tolerate_missing_values)
+      # Running only in case of missing values
+      missing_values = check_missing_values(table)
+
+      most_frequent_gender, most_frequent_ethnicity, mean_grade, stdev = nil
+
+      mean_grade, stdev = calculate_stdev(table['Grade'])
+
+      frequencies = table['Gender']\
+                    .each_with_object(Hash.new(0)) { |v, h| h[v] += 1; }
+      most_frequent_gender = table['Gender'].max_by { |v| frequencies[v] }
+
+      frequencies = table['Ethnicity']\
+                    .each_with_object(Hash.new(0)) { |v, h| h[v] += 1; }
+      most_frequent_ethnicity = table['Ethnicity'].max_by { |v| frequencies[v] }
+
+      return [most_frequent_gender, most_frequent_ethnicity, mean_grade, stdev, true] unless missing_values
+
+      # Notifying the user for the missing values and proceeding
+      # according to the tolerance parameter
+      unless tolerate_missing_values
+        raise ArgumentError, 'Missing values are present in the data set'
+      end
+
+      warn('WARNING! There are missing values in the data set,'\
+           ' which will be automatically handled.')
+
+      # Replacing missing gender values with the most frequent gender in the data set
+      unless missing_values[0].empty?
+        missing_values[0].each do |x|
+          table[x]['Gender'] = most_frequent_gender
+        end
+      end
+
+      # Replacing missing ethnicity values with the most frequent gender in the data set
+      unless missing_values[1].empty?
+        missing_values[1].each do |x|
+          table[x]['Ethnicity'] = most_frequent_ethnicity
+        end
+      end
+
+      # Replacing missing grade values according to the mean and standard
+      # deviation of the data to keep the original distribution
+      unless missing_values[2].empty?
+        missing_values[2].each do |x|
+          case (rand * 100).round
+          when 0..1
+            table[x]['Grade'] = [(mean_grade - 3 * stdev).round, 0].max
+          when 2..9
+            table[x]['Grade'] = [(mean_grade - 2 * stdev).round, 0].max
+          when 10..33
+            table[x]['Grade'] = (mean_grade - stdev).round
+          when 34..66
+            table[x]['Grade'] = mean_grade.round
+          when 67..91
+            table[x]['Grade'] = (mean_grade + stdev).round
+          when 92..99
+            table[x]['Grade'] = [(mean_grade + 2 * stdev).round, 100].min
+          when 99..100
+            table[x]['Grade'] = [(mean_grade - 3 * stdev).round, 100].min
+          end
+        end
+      end
+      # Returning the already calculated most statistical parameters to be
+      # used for finding students with close to median attributes if necessary
+      # puts "mean - #{mean}, stdev - #{stdev}"
+      [most_frequent_gender, most_frequent_ethnicity, mean_grade, stdev]
+    end
+
+    private :check_missing_values, :calculate_stdev
+  end
+end

data/lib/MBPSO_Team_Formation/neighbourhood.rb

@@ -0,0 +1,132 @@
+require_relative 'particle'
+module MBPSOTeamFormation
+  class Neighbourhood
+
+    attr_reader :l_best_position, :l_best_fitness, :terminate, :ret_value, :particles_list
+    attr_accessor :counter
+
+    def initialize(length, teams, control_param_personal, control_param_local, \
+                   inertia, table, ethnicity_weight, gender_weight, \
+                   init_num_particles, forbidden_pairs, survival_number)
+      @particles_list = []
+
+      @l_best_fitness = -90_000
+      @l_best_position = Array.new(length) { Array.new(teams, 0) }
+
+      @length = length
+      @teams = teams
+      @init_num_particles = init_num_particles
+      @table = table
+
+      # Initialising particles
+      initialise_particles(control_param_personal, control_param_local, inertia, \
+table, ethnicity_weight, gender_weight, survival_number, forbidden_pairs)
+
+      # Number of iterations without local best update
+      @counter = 0
+    end
+
+    # Initialising the needed number of particles by adding
+    # to the list of particles for the current neighbourhood object
+    def initialise_particles(cpp, cpl, init_in, table, ew, gw, sn, fp)
+      (0..@init_num_particles - 1).each do |_x|
+        @particles_list.push(Particle\
+                             .new(@length, @teams, cpp, cpl, init_in, \
+                                  table, ew, gw, sn, fp))
+      end
+    end
+
+    # Add particles to the neighbourhood
+    def add_particle(particle)
+      @particles_list.push(particle)
+    end
+
+    # Remove particles from the neighbourhood
+    #
+    # @return [Particle, nil] Return the particle if successfully removed\
+    # or nil if the list of particles is empty
+    def remove_particle
+      @particles_list.pop
+    end
+
+    # Update the local best position and fitness if any of the particles
+    # has fitness higher than the current local best
+    def update_l_best
+      # Indicator of whether the fitness has been updated at the current iteration
+      @flag = false
+
+      (0..@particles_list.length - 1).each do |x|
+        next unless @particles_list[x].p_best_fitness > @l_best_fitness
+
+        @l_best_fitness = @particles_list[x].p_best_fitness
+        @l_best_position = @particles_list[x].p_best_position
+        @flag = true
+      end
+
+      # Checking if local best has been updated to maintain
+      # the counter of iterations with no improvement
+      if @flag
+        @counter = 0
+      else
+        @counter += 1
+      end
+    end
+
+    def iterate_particles
+      @particles_list.each do |x|
+        x.update_velocity(@l_best_position)
+        x.update_position
+        x.calculate_fitness
+        x.update_stats
+      end
+      update_l_best
+      # puts "Global best: #{@l_best_fitness}"
+    end
+
+    #
+    def update_inertia(inertia)
+      @particles_list.each do |x|
+        x.inertia = inertia
+      end
+    end
+
+    def update_sn(survival_number)
+      @particles_list.each do |x|
+        x.survival_number = survival_number
+      end
+    end
+
+
+    def report_particles
+      array = Array.new(@particles_list.length)
+      (0..@particles_list.length - 1).each do |x|
+        array[x] = @particles_list[x].stats
+      end
+      array
+    end
+
+    # Prints the attributes of the resulted alocation
+    def print_best
+      gender = []
+      ethnicity = []
+      grade = []
+
+      (0..@teams - 1).each do |y|
+        (0..@length - 1).each do |x|
+          next unless @l_best_position[x][y] == 1
+
+          gender.push(@table[x]['Gender'])
+          ethnicity.push(@table[x]['Ethnicity'])
+          grade.push(@table[x]['Grade'].to_i)
+        end
+        puts " Team#{y}'s attributes arrays:\nGender: #{gender} \nEthnicity: #{ethnicity} \nGrade:#{grade}"
+        gender.clear
+        ethnicity.clear
+        grade.clear
+      end
+    end
+
+
+    private :update_l_best
+  end
+end

data/lib/MBPSO_Team_Formation/particle.rb

@@ -0,0 +1,317 @@
+module MBPSOTeamFormation
+  class Particle
+    attr_reader :p_best_fitness, :p_best_position, :stats, :fitness
+    attr_accessor :position, :inertia, :survival_number
+
+    def initialize(length, teams, \
+                   control_param_personal, control_param_local, inertia, \
+                   table, ethnicity_weight, gender_weight, \
+                   survival_number, forbidden_pairs)
+      @table = table
+
+      @length = length
+      @teams = teams
+
+      @position = Array.new(length) { Array.new(teams, 0) }
+      @velocity = Array.new(length) { Array.new(teams, 0) }
+      @new_velocity = Array.new(length) { Array.new(teams, 0) }
+
+      initial_particle_assignment
+
+      @inertia = inertia
+      @control_param_personal = control_param_personal
+      @control_param_local = control_param_local
+      @ethnicity_weight = ethnicity_weight
+      @gender_weight = gender_weight
+
+      @fitness = 0
+      @p_best_fitness = -900_000
+      @p_best_position = Array.new(length) { Array.new(teams, 0) }
+      # Array holding the particle fitness along
+      # the run of the algorithm, used for testing purposes
+      @stats = []
+
+      # Number of final swapping suggestions
+      # to be considered when updating position
+      @survival_number = survival_number
+
+      # Probability threshold above which only @survival_number of values are left
+      @threshold = 0
+      @forbidden_pairs = forbidden_pairs
+    end
+
+    # Generating the initial position of the particle
+    # by assigning each to student to a random team
+    def initial_particle_assignment
+      array = 0.upto(@length - 1).to_a
+      array = array.shuffle
+      (0..@length - 1).each do |x|
+        student = array[x]
+        @position[student][x % @teams] = 1
+      end
+    end
+
+    # Calculate the fitness of the solution the particle represents
+    def calculate_fitness
+      total_fitness = 0
+
+      # Arrays to hold the attribute values for each team
+      gender = []
+      ethnicity = []
+      grade = []
+      id = []
+
+      (0..@teams - 1).each do |y| # Iterating through all teams
+        (0..@length - 1).each do |x| # Iterating through all students
+          next unless @position[x][y] == 1
+
+          # Only checking for forbidden team formations
+          # if there are any forbidden pairs at all
+          unless @forbidden_pairs.nil?
+            temp = [] # List with students that are forbidden to join the team
+
+            # Checking if the particular student is already in
+            # the list of forbidden students for the particular team
+
+            if temp.include? @table[x]['id'] # If this student cannot be assigned to this team
+              initial_particle_assignment # Change the current postion with a random one
+              calculate_fitness #and calculate its new fitness
+              return false # terminate the method
+            end
+
+            # Adding all forbidden mates of the student to the list with forbidden teammates
+            if @forbidden_pairs.key?(@table[x]['id'])
+              temp.append(@forbidden_pairs[@table[x]['id']])
+            end
+          end
+
+          # Extract attributes of students in the team
+          # into the temporary arrays so the distances can be computed
+          gender.push(@table[x]['Gender'])
+          ethnicity.push(@table[x]['Ethnicity'])
+          grade.push(@table[x]['Grade'].to_i)
+        end
+
+        # Calculate the distances between students
+        (0..grade.length - 2).each do |i|
+          (i + 1..grade.length - 1).each do |index|
+            dist = 0 # sum of distances
+            # As this is non-numeric attribute represented however
+            # by a numeric value, we're interested only if
+            # they are different, not by how much as it is irrelevant
+            dist += @gender_weight unless gender[i] == gender[index]
+            dist += @ethnicity_weight unless ethnicity[i] == ethnicity[index]
+            dist += (grade[i] - grade[index])**2
+
+            # Adding the distances between students for
+            # the current team to the total fitness
+            dist.positive? ? total_fitness += Math.sqrt(dist) : total_fitness -= Math.sqrt(dist.abs)
+          end
+        end
+        case grade.uniq.length
+        when 1
+          total_fitness -= 80
+        when 2
+          total_fitness -= 150
+        when 1
+          total_fitness -= 300
+        end
+
+        gender.clear
+        ethnicity.clear
+        grade.clear
+      end
+
+      @fitness = total_fitness
+      # Check if the current fitness is better than the personal best one
+      update_p_best
+    end
+
+    # Comparing current and local best fitness and updating accordingly
+    def update_p_best
+      return unless @fitness > p_best_fitness
+
+      @p_best_fitness = @fitness
+      @p_best_position = @position
+    end
+
+    # Generating the random components for updating velocities
+    # The passing of parameter makes the method reusable for both
+    # personal and local random factors
+    #
+    # @param [Array] param Control parameter according to
+    # which the random component will be generated
+    # @return [Array] The resulting random component
+    def generate_random_vector(param)
+      random_vector = Array.new(@length) { Array.new(@teams) { rand } } # Generate matrix of random values
+      random_vector.each do |x|
+        x.each do |y|
+          # If the value is higher than the
+          # threshold, put the specified probability there
+          y = y > param[0] ? param[1] : 0
+        end
+      end
+      random_vector
+    end
+
+    # Generate swapping suggestions for velocity updates by applying
+    # logical XOR operator to the corresponding positions in
+    # the current position and personal/local best position matrices
+    # @param [Array] minuend The position to be compared with
+    # the current position - personal or local best
+    # @param [float] param Parameter according to which probabilities
+    # will be updates on the places where swapping suggestions are found
+    # @return [Array] The resulting probability matrix
+    def subtract_position(minuend, param)
+      result = Array.new(@length) { Array.new(@teams, 0) }
+
+      # Iterate through the matrices and update the result matrix
+      # according to the XOR operation output and specified parameter
+      (0..@length - 1).each do |x|
+        (0..@teams - 1).each do |y|
+          result[x][y] = (@position[x][y] != minuend[x][y]) ? param : 0
+        end
+      end
+      result
+    end
+
+    # Calculating the positional sums of the passed probability matrices
+    # @param [Array] args Array of the probability matrices that are to be summed
+    # @return [Array] Resulting probability matrix
+    def sum_probability_matrices(*args)
+      result = Array.new(@length) { Array.new(@teams, 0) }
+      (0..@length - 1).each do |x|
+        (0..@teams - 1).each do |y|
+          (0..args.size - 1).each do |z|
+            result[x][y] += args[z][x][y]
+          end
+        end
+      end
+      result
+    end
+
+    # Calculate and update particle's velocity
+    #
+    # @param [Array] l_best_position The neighbourhood's local best position.
+    # It is passed to the method when called by the neighbourhood object
+    # to avoid storing it for each particle, as well to conserve
+    # the one way relationship between particle and neighbourhood
+    # @return [Array] The resulting velocity
+    def update_velocity(l_best_position)
+      # Generating the second and third parameters in the velocity update equation
+      term2 = sum_probability_matrices(generate_random_vector(@control_param_personal), subtract_position(@p_best_position, @control_param_personal[2]))
+      term3 = sum_probability_matrices(generate_random_vector(@control_param_local), subtract_position(l_best_position, @control_param_local[2]))
+      new_velocity = Array.new(@length) { Array.new(@teams, 0) }
+
+      # Summing the current velocity with the weighted parameters
+      (0..@length - 1).each do |x|
+        (0..@teams - 1).each do |y|
+          new_velocity[x][y] += (@velocity[x][y] * @inertia)
+          new_velocity[x][y] += term2[x][y]
+          new_velocity[x][y] += term3[x][y]
+        end
+      end
+
+      # Normalising the velocity as a fraction
+      # of the maximum value present in the matrix
+      max_probability = new_velocity.flatten.max
+      (0..@length - 1).each do |x|
+        (0..@teams - 1).each do |y|
+          new_velocity[x][y] = new_velocity[x][y] / max_probability
+        end
+      end
+
+      @velocity = new_velocity
+    end
+
+    # Updating particle's position
+    def update_position
+      # Array holding the free slots in each team
+      free_slots = Array.new(@teams, (@length / @teams).to_i)
+      unassigned_students = []
+      new_position = Array.new(@length) { Array.new(@teams, 0) }
+      randomised_current_position = Array.new(@length) { Array.new(@teams, 0) }
+
+      # Sum up current position and velocity
+      @velocity = sum_probability_matrices(randomised_current_position, @velocity)
+
+      # Calculate the survivability threshold
+      @threshold = @velocity.flatten.max(@survival_number.to_i + 1).last
+
+      (0..@length - 1).each do |x|
+        # First assign students where velocity doesnt
+        # suggest changes  to avoid extra swaps
+        if @velocity[x].flatten.max < @threshold
+          (0..@teams - 1).each do |y|
+            new_position[x][y] = @position[x][y]
+            free_slots[y] -= 1 if new_position[x][y] == 1
+          end
+        else
+          unassigned_students.push(x)
+        end
+      end
+
+      probabilities_indices = Array.new { Array.new }
+      unassigned_students2 = []
+      unassigned_students.each do |x|
+        # List of indexes in order that when referenced relates to a sorted list
+        probabilities_indices[x] = @velocity[x].map.with_index.sort.map(&:last)
+        if free_slots[probabilities_indices[x][0]].positive?
+          new_position[x][probabilities_indices[x][0]] = 1
+          free_slots[probabilities_indices[x][0]] -= 1
+        else
+          unassigned_students2.push(x)
+        end
+      end
+      # Implemented like that because in order to generate the indexes
+      # the whole table has to be iterated once anyway
+      # and then continue, therefore some needed actions are squeezed in
+
+      index = 1 # Representing the index of the sorted probabilities
+      temp = unassigned_students2
+      while free_slots.sum.positive? && index < @teams
+        unassigned_students2 = temp.dup
+        temp.clear
+        if index > 4
+          until unassigned_students2[0].nil?
+            (0..@teams - 1).each do |x|
+              next unless free_slots[x].positive?
+
+              new_position[unassigned_students2[0]][x] = 1
+              free_slots[x] -= 1
+              unassigned_students2.shift
+            end
+          end
+        end
+        unassigned_students2.each do |x|
+          if free_slots[probabilities_indices[x][index]].positive?
+            new_position[x][probabilities_indices[x][index]] = 1
+            free_slots[probabilities_indices[x][index]] -= 1
+          else
+            temp.push(x)
+          end
+        end
+        index += 1
+      end
+      @position = new_position
+    end
+
+    # Neatly printing a matrix
+    # @param [Array] array Matrix to be printed
+    def print(array)
+      arr = array.transpose
+      width = arr.flatten.max.to_s.size + 2
+      #=> 4
+      puts(arr.map { |a| a.map { |i| i.round(3).to_s.rjust(width) }.join })
+    end
+
+    # Adding current fitness to the list of stats
+    def update_stats
+      @stats.push(@fitness)
+    end
+
+    private :initial_particle_assignment, :update_p_best, \
+            :generate_random_vector, :subtract_position, :sum_probability_matrices
+
+  end
+end

data/lib/MBPSO_Team_Formation/validation.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module MBPSOTeamFormation
+  class Validation
+    def raise_arg_error(text, condition)
+      raise ArgumentError, text unless condition
+    end
+
+    def validate_number(var, name, type)
+      case type
+      when 'pos_int'
+        text = "Argument '#{name}' is not a valid positive Integer"
+        condition = (var.is_a?(Integer) &&
+                     var.positive?)
+      when 'nn_num'
+        text = "Argument '#{name}' is not a valid non-negative integer or float"
+        condition = ((var.is_a?(Integer) ||
+                      var.is_a?(Float)) &&
+                      (var >= 0))
+      else
+        text = 'Invalid validation call'
+        condition = false
+      end
+      raise_arg_error(text, condition)
+      var
+    end
+
+    def validate_survival_number(var, length)
+      text = "Argument 'survival_number' is not a valid Integer."\
+             ' Integer in the range [2:Number of students] expected'
+      raise_arg_error(text, (var.is_a?(Integer) &&
+                            (var >= 2) &&
+                            (var <= length)))
+      var
+    end
+
+    def validate_control_parameters(var, name)
+      text = "Unrecognised parameter, 'local' or 'personal' required."
+      raise_arg_error(text, ((name.is_a? String) &&
+                             (%w[local personal].include? name)))
+
+      text = "Argument '#{name}' is not in the required format."\
+             ' Array with 3 floats in the range [0;1] expected'
+
+      raise_arg_error(text, ((var.is_a? Array) && var.length == 3))
+
+      raise_arg_error(text, (var[0].is_a?(Float) || Integer &&
+                            (var[0] <= 1) &&
+                            (var[0] >= 0)))
+
+      raise_arg_error(text, (var[1].is_a?(Float) || Integer &&
+                            (var[1] <= 1) &&
+                            (var[1] >= 0)))
+
+      raise_arg_error(text, (var[2].is_a?(Float) || Integer &&
+                            (var[2] <= 1) &&
+                            (var[2] >= 0)))
+      var
+    end
+
+    def validate_skill_table(var)
+      text = "Argument 'skill_table' has invalid value and/or invalid coverage of the grade range"
+      temp = []
+
+      # Making sure the parameter is the right type
+      raise_arg_error(text, (var.is_a? Hash))
+      # Expanding the ranges and adding them into a temporary array
+      var.each_key.each do |key|
+        # Making sure the keys of the Hash are valid Integer ranges,
+        # as Range can be a String one, for example
+        raise_arg_error(text, (key.is_a?(Range) &&
+                               key.begin.is_a?(Integer) &&
+                               key.end.is_a?(Integer)))
+        temp.append(*key)
+      end
+      temp = temp.sort
+      # Right size ==> No duplicates and full range covered
+      raise_arg_error(text, (temp.length == 101))
+      # Starts with zero
+      raise_arg_error(text, temp[0].zero?)
+      # Ends with 100
+      raise_arg_error(text, temp.last == 100)
+
+      # Checking the skill values grades will be mapped to
+      var.values.each do |x|
+        raise_arg_error(text,\
+                        (x.is_a?(Integer) &&
+                        (x >= 0)))
+      end
+      var
+    end
+
+    def validate_bool(var, name)
+      text = "Argument '#{name}' is not in the required format."\
+             ' Boolean expected'
+      raise_arg_error(text,\
+                      ([true, false].include? var))
+      var
+    end
+
+    def validate_dataset(var)
+      text = "Invalid format of data set. Required: 'CSV::var'"
+      raise_arg_error(text, (var.is_a? CSV::Table))
+
+      text = 'Ivalid number of columns, required 4'
+      raise_arg_error(text, (var.headers.size == 4))
+
+      text = "Invalid Headers. Required: 'id', 'Gender', 'Ethnicity' and 'Grade'"
+      raise_arg_error(text, (var.headers.include?('id') &&
+                             var.headers.include?('Gender') &&
+                             var.headers.include?('Ethnicity') &&
+                             var.headers.include?('Grade')))
+
+      text = 'The data set contains duplicating student IDs'
+      raise_arg_error(text,\
+                      (var['id'].uniq.length == var['id'].length))
+
+      # Regular expressions for each attribute
+      gender_regex = /^(-1|0|1)$/
+      ethnicity_regex = /^(-1|[0-4])$/
+      grade_regex = /^(100|[1-9]?[0-9])$/
+
+      (0..var.length - 1).each do |x|
+        text_gender = "Invalid gender value for student with ID = #{var[x]['id']}"\
+                      '.Required: integer in the range [-1:1]'
+        text_ethn = "Invalid ethnicity value for student with ID = #{var[x]['id']}"\
+                    '.Required: integer in the range [-1:4]'
+        text_grade = "Invalid grade value for student with ID = #{var[x]['id']}"\
+                     '.Required: integer in the range [0:100].'
+
+        raise_arg_error(text_gender,\
+                        (var[x]['Gender'].to_s =~ gender_regex ||
+                                                  var[x]['Gender'].nil?))
+        raise_arg_error(text_ethn,\
+                        (var[x]['Ethnicity'].to_s =~ ethnicity_regex ||
+                                                     var[x]['Ethnicity'].nil?))
+        raise_arg_error(text_grade,\
+                        (var[x]['Grade'].to_s =~ grade_regex ||
+                                                 var[x]['Grade'].nil?))
+      end
+      var
+    end
+
+    def validate_forbidden_pairs(var)
+      text = "Invalid format of the 'forbidden_pairs' argument."\
+             'Array or CSV::Table required.'
+      raise_arg_error(text,\
+                      ((var.is_a? Array) ||
+                       (var.is_a? CSV::Table)))
+
+      flag = true
+      (0..var.length - 1).each do |x|
+        flag = false unless var[x].length == 2
+        text = "Invalid size of sub-array at index #{x}."\
+               ' Pair, i.e. array of two elements required.'
+        raise_arg_error(text, flag)
+      end
+      var
+    end
+
+    private :raise_arg_error
+  end
+end

data/lib/MBPSO_Team_Formation/version.rb

@@ -0,0 +1,3 @@
+module MBPSOTeamFormation
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: MBPSO_Team_Formation
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- 'Anton Pashov '
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-04-21 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- anton.pashov@kcl.ac.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/MBPSO_Team_Formation.rb
+- lib/MBPSO_Team_Formation/mbpso.rb
+- lib/MBPSO_Team_Formation/mvh.rb
+- lib/MBPSO_Team_Formation/neighbourhood.rb
+- lib/MBPSO_Team_Formation/particle.rb
+- lib/MBPSO_Team_Formation/validation.rb
+- lib/MBPSO_Team_Formation/version.rb
+homepage: https://github.kcl.ac.uk/k1631446/MBPSO_Team_Formation
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.kcl.ac.uk/k1631446/MBPSO_Team_Formation
+  source_code_uri: https://github.kcl.ac.uk/k1631446/MBPSO_Team_Formation
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Automated team formation using modified binary particle swarm optimisation.
+test_files: []