| Name | team-formation JSON |
| Version |
1.2.0
JSON |
| download |
| home_page | None |
| Summary | A tool to form teams from a larger group based on clustering and diversity constraints |
| upload_time | 2024-12-20 00:37:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2023 Harvard Business School 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. |
| keywords |
clustering
diversity
team
team formation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Constraint-Based Team Formation
## Problem Statement
Dividing a large learning cohort into smaller teams for group work,
discussion, or other activity is a common requirement in many learning
contexts. It is easy to automate the formation of randomly assigned
teams, but there can be rules, guidelines, and goals guiding the
desired team composition to support learning objectives and other
goals which can complicate manual and automated team creation.
The approach described in this document provides a technical framework
and implementation to support specifying team formation objectives in
a declarative fashion and can automatically generate teams based on
those objectives. There is also a description of how to measure and
evaluate the created teams with respect to the specified objectives.
The team formation objectives currently supported are team size and
*diversification* and *clustering* around participant
attributes. *Diversification* in this context is defined as the goal
of having the distribution of a particular attribute value on each
team reflect the distribution of that attribute value in the overall
learning cohort. For example, if the overall learning cohort has 60%
women and 40% men, a diversification goal on gender would attempt to
achieve 60/40 female/male percentages on each team or, more
specifically, to achieve the female/male participant counts that are
closest to 60%/40% for the particular team size.
*Clustering* is defined as the goal of having all team members share a
particular attribute value. For example, if there is a `job_function`
attribute with values of `Contributor`, `Manager`, and `Executive` a
clustering goal would be to have each team contain participants with a
single value of the `job_function` attribute to facilitate sharing
of common experiences.
Cluster variables can also be multi-valued indicated by a list of
acceptable values for the participant. For example, if there is a
`working_time` variable with hour ranges `00-05`, `05-10`, `10-15`,
`15-20`, and `20-24`. A participant might have the values `["00-05",
"20-24"]` indicating that both those time ranges are acceptable.
In order to balance possibly conflicting objectives and goals of the
team formation process we allow a weight to specified for each
constraint to indicate the priority of the objective in relation
to the others.
## Team Formation as Constraint Satisfaction using CP-SAT
The problem of dividing participants into specified team sizes guided
by diversity and clustering constraints can be stated as a [Constraint
Satisfaction
Problem](https://en.wikipedia.org/wiki/Constraint_satisfaction_problem)
(CSP) with a set of variables with integer domains and constraints on
the allowed combinations.
There is a very efficient constraint solver that uses a variety of
constraint solving techniques from the Google Operational Research
team called [Google OR-Tools
CP-SAT](https://developers.google.com/optimization/cp/cp_solver) that
we are using for this team assignment problem.
The remainder of the document describes how to frame the team
formation problem in the CP-SAT constraint model to be solved by the
CP-SAT solver.
## Input Data
The input to the team formation process is a set of participants with
category-valued attributes, a target team size, and a set of
constraints. The specification of the constraints is done with a
dictionary with keys attribute names from the `participants` data frame as
keys, a type of `diversify` or `cluster`, and a numeric `weight`.
## API
- [API Documentation](https://harvard-hbs.github.io/team-formation)
```
>>> from team_assignment import TeamAssignment
>>> import pandas as pd
>>> participants = pd.DataFrame(
columns=["id", "gender", "job_function", "working_time"],
data=[[8, "Male", "Manager", ["00-05", "20-24"]],
[9, "Male", "Executive", ["10-15", "15-20"]],
[10, "Female", "Executive", ["15-20"]],
[16, "Male", "Manager", ["15-20", "20-24"]],
[18, "Female", "Contributor", ["05-10", "10-15"]],
[20, "Female", "Manager", ["15-20", "20-24"]],
[21, "Male", "Executive", ["15-20"]],
[29, "Male", "Contributor", ["05-10", "10-15"]],
[31, "Female", "Contributor", ["05-10"]]]
)
>>> constraints = pd.DataFrame(
columns=["attribute", "type", "weight"],
data=[["gender", "diversify", 1],
["job_function", "cluster", 1],
["working_time", "cluster", 1]]
)
>>> target_team_size = 3
>>> ta = TeamAssignment(participants, constraints, target_team_size)
>>> ta.solve()
>>> ta.participants.sort_values("team_num")
id gender job_function working_time team_num
4 18 Female Contributor [05-10, 10-15] 0
7 29 Male Contributor [05-10, 10-15] 0
8 31 Female Contributor [05-10] 0
0 8 Male Manager [00-05, 20-24] 1
3 16 Male Manager [15-20, 20-24] 1
5 20 Female Manager [15-20, 20-24] 1
1 9 Male Executive [10-15, 15-20] 2
2 10 Female Executive [15-20] 2
6 21 Male Executive [15-20] 2
>>> ta.evaluate_teams()
team_num team_size attr_name type missed
0 0 3 gender diversify 1
1 0 3 job_function cluster 0
2 0 3 working_time cluster 0
3 1 3 gender diversify 0
4 1 3 job_function cluster 0
5 1 3 working_time cluster 0
6 2 3 gender diversify 0
7 2 3 job_function cluster 0
8 2 3 working_time cluster 0
>>>
```
## Change Log
For a detailed log of changes see [CHANGELOG.md](CHANGELOG.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "team-formation",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "clustering, diversity, team, team formation",
"author": null,
"author_email": "Brent Benson <bbenson@hbs.edu>",
"download_url": "https://files.pythonhosted.org/packages/43/a9/36b9a501269c94e598c07d51146e45c2aaca5fcffd66f43e96dcf6552645/team_formation-1.2.0.tar.gz",
"platform": null,
"description": "# Constraint-Based Team Formation\n\n## Problem Statement\n\nDividing a large learning cohort into smaller teams for group work,\ndiscussion, or other activity is a common requirement in many learning\ncontexts. It is easy to automate the formation of randomly assigned\nteams, but there can be rules, guidelines, and goals guiding the\ndesired team composition to support learning objectives and other\ngoals which can complicate manual and automated team creation.\n\nThe approach described in this document provides a technical framework\nand implementation to support specifying team formation objectives in\na declarative fashion and can automatically generate teams based on\nthose objectives. There is also a description of how to measure and\nevaluate the created teams with respect to the specified objectives.\n\nThe team formation objectives currently supported are team size and\n*diversification* and *clustering* around participant\nattributes. *Diversification* in this context is defined as the goal\nof having the distribution of a particular attribute value on each\nteam reflect the distribution of that attribute value in the overall\nlearning cohort. For example, if the overall learning cohort has 60%\nwomen and 40% men, a diversification goal on gender would attempt to\nachieve 60/40 female/male percentages on each team or, more\nspecifically, to achieve the female/male participant counts that are\nclosest to 60%/40% for the particular team size.\n\n*Clustering* is defined as the goal of having all team members share a\nparticular attribute value. For example, if there is a `job_function`\nattribute with values of `Contributor`, `Manager`, and `Executive` a\nclustering goal would be to have each team contain participants with a\nsingle value of the `job_function` attribute to facilitate sharing\nof common experiences.\n\nCluster variables can also be multi-valued indicated by a list of\nacceptable values for the participant. For example, if there is a\n`working_time` variable with hour ranges `00-05`, `05-10`, `10-15`,\n`15-20`, and `20-24`. A participant might have the values `[\"00-05\",\n\"20-24\"]` indicating that both those time ranges are acceptable.\n\nIn order to balance possibly conflicting objectives and goals of the\nteam formation process we allow a weight to specified for each\nconstraint to indicate the priority of the objective in relation\nto the others.\n\n## Team Formation as Constraint Satisfaction using CP-SAT\n\nThe problem of dividing participants into specified team sizes guided\nby diversity and clustering constraints can be stated as a [Constraint\nSatisfaction\nProblem](https://en.wikipedia.org/wiki/Constraint_satisfaction_problem)\n(CSP) with a set of variables with integer domains and constraints on\nthe allowed combinations.\n\nThere is a very efficient constraint solver that uses a variety of\nconstraint solving techniques from the Google Operational Research\nteam called [Google OR-Tools\nCP-SAT](https://developers.google.com/optimization/cp/cp_solver) that\nwe are using for this team assignment problem.\n\nThe remainder of the document describes how to frame the team\nformation problem in the CP-SAT constraint model to be solved by the\nCP-SAT solver.\n\n## Input Data\n\nThe input to the team formation process is a set of participants with\ncategory-valued attributes, a target team size, and a set of\nconstraints. The specification of the constraints is done with a\ndictionary with keys attribute names from the `participants` data frame as\nkeys, a type of `diversify` or `cluster`, and a numeric `weight`.\n\n## API\n\n- [API Documentation](https://harvard-hbs.github.io/team-formation)\n\n\n```\n >>> from team_assignment import TeamAssignment\n >>> import pandas as pd\n >>> participants = pd.DataFrame(\n columns=[\"id\", \"gender\", \"job_function\", \"working_time\"],\n data=[[8, \"Male\", \"Manager\", [\"00-05\", \"20-24\"]],\n [9, \"Male\", \"Executive\", [\"10-15\", \"15-20\"]],\n [10, \"Female\", \"Executive\", [\"15-20\"]],\n [16, \"Male\", \"Manager\", [\"15-20\", \"20-24\"]],\n [18, \"Female\", \"Contributor\", [\"05-10\", \"10-15\"]],\n [20, \"Female\", \"Manager\", [\"15-20\", \"20-24\"]],\n [21, \"Male\", \"Executive\", [\"15-20\"]],\n [29, \"Male\", \"Contributor\", [\"05-10\", \"10-15\"]],\n [31, \"Female\", \"Contributor\", [\"05-10\"]]]\n )\n >>> constraints = pd.DataFrame(\n columns=[\"attribute\", \"type\", \"weight\"],\n data=[[\"gender\", \"diversify\", 1],\n [\"job_function\", \"cluster\", 1],\n [\"working_time\", \"cluster\", 1]]\n )\n >>> target_team_size = 3\n >>> ta = TeamAssignment(participants, constraints, target_team_size)\n >>> ta.solve()\n >>> ta.participants.sort_values(\"team_num\")\n id gender job_function working_time team_num\n 4 18 Female Contributor [05-10, 10-15] 0\n 7 29 Male Contributor [05-10, 10-15] 0\n 8 31 Female Contributor [05-10] 0\n 0 8 Male Manager [00-05, 20-24] 1\n 3 16 Male Manager [15-20, 20-24] 1\n 5 20 Female Manager [15-20, 20-24] 1\n 1 9 Male Executive [10-15, 15-20] 2\n 2 10 Female Executive [15-20] 2\n 6 21 Male Executive [15-20] 2\n >>> ta.evaluate_teams()\n team_num team_size attr_name type missed\n 0 0 3 gender diversify 1\n 1 0 3 job_function cluster 0\n 2 0 3 working_time cluster 0\n 3 1 3 gender diversify 0\n 4 1 3 job_function cluster 0\n 5 1 3 working_time cluster 0\n 6 2 3 gender diversify 0\n 7 2 3 job_function cluster 0\n 8 2 3 working_time cluster 0\n >>>\n```\n\n## Change Log\n\nFor a detailed log of changes see [CHANGELOG.md](CHANGELOG.md).\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Harvard Business School 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.",
"summary": "A tool to form teams from a larger group based on clustering and diversity constraints",
"version": "1.2.0",
"project_urls": {
"Changelog": "https://raw.githubusercontent.com/harvard-hbs/team-formation/refs/heads/main/CHANGELOG.md",
"Homepage": "https://github.com/harvard-hbs/team-formation/"
},
"split_keywords": [
"clustering",
" diversity",
" team",
" team formation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "12363ce75578296ff47117e5dda114402bb677becb86b810cd96d657bdeac593",
"md5": "92063c66abd2d6126564c52bde5bda9d",
"sha256": "8c7b3cc20772d2ca3873d6fec16251b5c9d66508be7be7cc365e7eaa5a49c95c"
},
"downloads": -1,
"filename": "team_formation-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "92063c66abd2d6126564c52bde5bda9d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 17385,
"upload_time": "2024-12-20T00:37:09",
"upload_time_iso_8601": "2024-12-20T00:37:09.146961Z",
"url": "https://files.pythonhosted.org/packages/12/36/3ce75578296ff47117e5dda114402bb677becb86b810cd96d657bdeac593/team_formation-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "43a936b9a501269c94e598c07d51146e45c2aaca5fcffd66f43e96dcf6552645",
"md5": "d09087912e68e12dd7ba44960485d300",
"sha256": "61173f91ae5114e190d507509917ea3256213c3b15f8b2ea88453e410111f12c"
},
"downloads": -1,
"filename": "team_formation-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "d09087912e68e12dd7ba44960485d300",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15867,
"upload_time": "2024-12-20T00:37:11",
"upload_time_iso_8601": "2024-12-20T00:37:11.115747Z",
"url": "https://files.pythonhosted.org/packages/43/a9/36b9a501269c94e598c07d51146e45c2aaca5fcffd66f43e96dcf6552645/team_formation-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-20 00:37:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "harvard-hbs",
"github_project": "team-formation",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "team-formation"
}
