py-school-match 0.2.0

Py-school-match, a Python package that implements matching algorithms for the student-to-school assignation problem.

Py-school-match

Py-school-match is an open-source Python package that implements multiple matching algorithms in order to assign students to schools.

It provides multiple algorithms ready to use:

• Top Trading Cycles (TTC)

• Deferred acceptance with multiple tie-breaking (DAMTB)

• Deferred acceptance with single tie-breaking (DASTB)

• Stable improvement cycles (SIC)

• Deferred Acceptance with multiple tie-breaking, plus stable cycles (MSIC)

• Deferred Acceptance with single tie-breaking, plus non-stable cycles (NSIC)

Py-school-match is designed specifically for the student-to-school assignation problem. Because of this, you can focus on evaluating different settings and algorithms, without the need to adapt or develop a complete solution.

Sample code

import py_school_match as psm

# Creating three students.
st0 = psm.Student()
st1 = psm.Student()
st2 = psm.Student()

# Creating a criteria. This means 'vulnerable' is now a boolean.
vulnerable = psm.Criteria('vulnerable', bool)

# Assigning st1 as vulnerable
student_vulnerable = psm.Characteristic(vulnerable, True)
st1.add_characteristic(student_vulnerable)

# Creating three schools, each with one seat available.
sc0 = psm.School(1)
sc1 = psm.School(1)
sc2 = psm.School(1)

# Defining preferences (from most desired to least desired)
st0.preferences = [sc0, sc1, sc2]
st1.preferences = [sc0, sc2, sc1]
st2.preferences = [sc2, sc1, sc0]

# Creating a lists with the students and schools defined above.
schools = [sc0, sc1, sc2]
students = [st0, st1, st2]

# Defining a ruleset
ruleset = psm.RuleSet()

# Defining a new rule from the criteria above.
rule_vulnerable = psm.Rule(vulnerable)

# Adding the rule to the ruleset. This means that a 'vulnerable' student has a higher priority.
# Note that rules are added in order (from higher priority to lower priority)
ruleset.add_rule(rule_vulnerable)

# Creating a social planner using the objects above.
planner = psm.SocialPlanner(students, schools, ruleset)

# Selecting an algorithm
algorithm = psm.SIC()

# Running the algorithm.
planner.run_matching(algorithm)

# inspecting the obtained assignation
for student in students:
    print("Student {} was assigned to School {}".format(student.id, student.assigned_school.id))

Installation

Dependencies

• graph-tool (>= 2.27)

User installation

pip install py-school-match

Or you can clone the repo and install it:

git clone https://github.com/igarizio/py-school-match
cd py-school-match
python setup.py install

Remember to first install graph-tool.

Development

Contributions are more than welcome. Feel free to open an issue or contact me!

Remember that this package does not provide ANY WARRANTY OF ANY KIND.

How to cite?

Insert citation here.