balanced-group-system 0.1.0__tar.gz

balanced_group_system-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Joshua Si
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

balanced_group_system-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.3
+Name: balanced-group-system
+Version: 0.1.0
+Summary: A management system to create balanced groups of participants
+Author: Joshua Si
+Author-email: josh.j.si@proton.me
+Requires-Python: >=3.9.0,<4.0.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13

balanced_group_system-0.1.0/balanced_group_system/__init__.py

@@ -0,0 +1,3 @@
+from .group_system import GroupSystem
+from .balanced_group_system import BalancedGroupSystem
+from .available_group_scheduler import AvailableGroupScheduler

balanced_group_system-0.1.0/balanced_group_system/available_group_scheduler.py

@@ -0,0 +1,88 @@
+import random
+from . import group_system
+
+"""
+AvailableGroupScheduler.py
+
+This module contains a subclass of GroupScheduler that creates groups based on the
+familiarity matrix and takes into account member availability. It creates groups
+in such a way that members meet as many new members as possible and minimize
+repeat meetings.
+
+Author: Joshua Si
+"""
+
+class AvailableGroupScheduler(group_system.GroupSystem):
+  def __init__(self, members: list[str] = [], availability_schedules: list[list[bool]] = []):
+    super().__init__(members)
+    self.familiarity_matrix: dict[frozenset[tuple[str, str]], int] = {frozenset((self.members[i], self.members[j])) : 0 for i in range(len(self.members)) for j in range(i+1, len(self.members))}
+    self.participation_count: dict[int] = {member: 0 for member in self.members}
+    if len(availability_schedules) == 0:
+      self.availability_schedules: list[list[bool]] = [[True for _ in range(len(members))]]
+    else:
+      self.availability_schedules: list[list[bool]] = availability_schedules
+
+  def add_schedule(self, availability: list[bool]) -> None:
+    self.availability_schedules.append(availability)
+
+  def update_participation(self, group: set[str]) -> None:
+    for member in group:
+      self.participation_count[member] += 1
+      for m in group:
+        if member != m:
+          self.familiarity_matrix[frozenset((member, m))] += 1
+
+  def create_balanced_schedules(self, group_size: int) -> list[set[str]]:
+    self.familiarity_matrix: dict[frozenset[tuple[str, str]], int] = {frozenset((self.members[i], self.members[j])) : 0 for i in range(len(self.members)) for j in range(i+1, len(self.members))}
+    self.participation_count: dict[int] = {member: 0 for member in self.members}
+    schedules = []
+    for availability in range(len(self.availability_schedules)):
+      candidates = set(member for member, avail in zip(self.members, self.availability_schedules[availability]) if avail)
+      # if less candidates than desired group_size, put all possible candidates in the group
+      if len(candidates) < group_size:
+        schedules.append(candidates)
+        continue
+      # otherwise filter for those who have participated the least to maximize new members
+      min_threshold = min(self.participation_count[member] for member in candidates)
+      min_participation_candidates = set(member for member in candidates if self.participation_count[member] == min_threshold)
+      if len(min_participation_candidates) > group_size:
+        # now select based on familiarity matrix
+        group = self.get_balanced_group(min_participation_candidates, set(), group_size)
+        schedules.append(group)
+        self.update_participation(group)
+      else:
+        candidates = set(member for member in candidates if member not in min_participation_candidates)
+        min_threshold += 1
+        new_candidates = set(member for member in candidates if self.participation_count[member] == min_threshold)
+        while len(min_participation_candidates) + len(new_candidates) < group_size:
+          min_participation_candidates = min_participation_candidates | new_candidates
+          min_threshold += 1
+          new_candidates = set(member for member in candidates if self.participation_count[member] == min_threshold)
+        group = self.get_balanced_group(new_candidates, min_participation_candidates, group_size)
+        schedules.append(group)
+        self.update_participation(group)
+    return schedules
+
+  # returns group of size group_size, consisting of existing members and adding from candidates based on familiarity
+  def get_balanced_group(self, candidates: set[str], existing: set[str], group_size: int) -> set[str]:
+    group = existing
+    scores = {frozenset(group): 0}
+    # Memoized version of evaluate_group for evaluating score when adding one member
+    def evaluate_member(group: set[str], member: str) -> int:
+      group_key = frozenset(group)
+      new_key = frozenset(group | {member})
+      if new_key in scores:
+        return scores[new_key]
+      score = scores[group_key]
+      for m in group:
+        score += self.familiarity_matrix[frozenset((m, member))]
+      scores[new_key] = score + 1
+      return score + 1
+
+    # Balance and distribute members
+    while len(group) < group_size and len(candidates) > 0:
+      min_candidate = min(candidates, key=lambda c: evaluate_member(group, c))
+      group.add(min_candidate)
+      candidates.remove(min_candidate)
+
+    return group

balanced_group_system-0.1.0/balanced_group_system/balanced_group_system.py

@@ -0,0 +1,95 @@
+import random
+from . import group_system
+
+"""
+BalancedGroupSystem.py
+
+This module contains a subclass of GroupSystem that creates balanced groups based on the familiarity matrix.
+It creates groups in such a way that members meet as many new members as possible and minimize repeat meetings.
+
+Author: Joshua Si
+"""
+
+class BalancedGroupSystem(group_system.GroupSystem):
+  def __init__(self, members: list[str] = []):
+    super().__init__(members)
+    self.familiarity_matrix: dict[frozenset[tuple[str, str]], int] = {
+        frozenset((self.members[i], self.members[j])) : 0
+        for i in range(len(self.members))
+        for j in range(i+1, len(self.members))
+    }
+
+  def __repr__(self) -> str:
+    return f"BalancedGroupSystem({self.members})"
+  
+  def add_member(self, member: str) -> None:
+    super().add_member(member)
+    for i in range(len(self.members)-1):
+      self.familiarity_matrix[frozenset((self.members[i], member))] = 0
+  
+  def remove_member(self, member: str) -> None:
+    try:
+      super().remove_member(member)
+      for m in self.members:
+        self.familiarity_matrix.pop(frozenset((m, member)))
+    except ValueError:
+      raise ValueError("Member '{}' was not in members".format(member))
+    
+  def create_groups(self, groups: list[set[str]]) -> list[set[str]]:
+    super().create_groups(groups)
+    for group in groups:
+      self.__update_familiarity(group)
+    return groups
+
+  def print_familiarity(self) -> None:
+    for i in self.members:
+      print(i, end=' ')
+    print()
+    for i in self.members:
+      print(i, end=' ')
+      for j in self.members:
+        if i == j:
+          print('-', end=' ')
+        else:
+          print(self.familiarity_matrix[frozenset((i, j))], end=' ')
+      print()
+
+  def evaluate_group(self, group: set[str]) -> int:
+    score = 0
+    pairs = ((i, j) for i in group for j in group if i != j)
+    score = sum(self.familiarity_matrix[frozenset(pair)] for pair in pairs)
+    return score
+  
+  def __update_familiarity(self, group: set[str]) -> None:
+    pairs = ((i, j) for i in group for j in group if i != j)
+    for pair in pairs:
+      self.familiarity_matrix[frozenset(pair)] += 1
+
+  # Calculate balanced groups by trying to minimize score when choosing which group to add each member to
+  def __calculate_balanced_groups(self, group_count: int, members: list[str] = [], verbose: bool = False) -> list[set[str]]:
+    random.shuffle(members)
+    groups = [set() for _ in range(group_count)]
+    scores = {(): 0}
+    # Memoized version of evaluate_group for evaluating score when adding one member
+    def evaluate_member(group: set[str], member: str) -> int:
+      new_group: set[str] = group | {member}
+      if frozenset(new_group) in scores:
+        return scores[frozenset(new_group)]
+      score = scores[frozenset(group)] if frozenset(group) in scores else 0
+      for i in group:
+        score += self.familiarity_matrix[frozenset((i, member))]
+      scores[frozenset(new_group)] = score + 2
+      return score + 2
+
+    # Balance and distribute members
+    for member in members:
+      min_group_index = min(range(group_count), key=lambda i: evaluate_member(groups[i], member))
+      groups[min_group_index].add(member)
+      if verbose:
+        print(groups)
+    return groups
+
+
+  def create_balanced_groups(self, group_count: int, verbose: bool = False) -> list[set[str]]:
+    groups = self.__calculate_balanced_groups(group_count, self.members.copy(), verbose)
+    return self.create_groups(groups)

balanced_group_system-0.1.0/balanced_group_system/group_system.py

@@ -0,0 +1,38 @@
+'''
+group_system.py
+
+This module contains a class that represents a group system that creates group_list and stores group history.
+'''
+
+class GroupSystem:  
+  def __init__(self, members: list[str] = []):
+    self.members: list[str] = members
+    self.group_history: list[list[set[str]]] = []
+  
+  def __repr__(self) -> str:
+    return f"GroupSystem({self.members})"
+
+  def print_history(self) -> None:
+    for i, group_set in enumerate(self.group_history):
+      print(i, ':', group_set)
+  
+  def add_member(self, member: str) -> None:
+    self.members.append(member)
+
+  def remove_member(self, member: str) -> None:
+    index = self.members.index(member)
+    self.members.pop(index)
+
+  def create_groups(self, group_list: list[set[str]]) -> None:
+    self.group_history.append(group_list)
+
+  # Slower version of create_groups that validates input
+  def create_and_validate_groups(self, group_list: list[set[str]]) -> None:
+    member_set = set(self.members)
+    for group in group_list:
+      for member in group:
+        try:
+          member_set.remove(member)
+        except KeyError:
+          raise KeyError("Element '{}' was not in members".format(member))
+    self.group_history.append(group_list)

balanced_group_system-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[tool.poetry]
+name = "balanced-group-system"
+version = "0.1.0"
+description = "A management system to create balanced groups of participants"
+authors = ["Joshua Si <josh.j.si@proton.me>"]
+
+[tool.poetry.dependencies]
+python = "^3.9.0"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^6.2.2"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"