Welcome to the SortingHat docs! Here you’ll find instructions on how to run the program as well as what kind of outputs you should expect to see.
To report a problem, view the source code, or submit a pull request, checkout the github repo.
Click the “Choose file” button under the sections tab to upload a csv containing information about sections. This file must have the following headers (order does not matter):
Presently no additional headers are supported.
Click the “Choose file” button under the students tab to upload a csv containing information about students. This file must have the following headers (order does not matter):
Other headers and columns are permitted to be in the student csv file, but the program will not be able to use data from columns that have headers named something other than what is specified above.
SortingHat offers users the ability to control certain aspects of how students are distributed in classes. One such aspect is the ability to set rough minimum ratio for males/females in any section. By moving the sliders users can set a rough minimum percentage of males or females that each section should be composed of. Note that these are rough minimums – because these are percentages and the number of students allowed in a class is a whole number the actual results are not guaranteed to match exactly. Some tinkering may be required to meet user requirements. Fortunately, SortingHat reports the legal sex distribution outcome of each section, so you will know exactly which sections require additional attention.
Users are also given the option of controlling the maximum percentage of student-athletes in a section by adjusting the Athlete slider. Note that this is not an exact guarantee, but it get very close to your target almost all of the time. SortingHat also reports the athlete distribution of individual sections after running so you can see the exact problem areas.
Click the “Run” button to run the program. This typically takes less than 5 seconds, but the time taken will vary based on the number of students and sections provided and the speed of your computer. Upon determining an optimal allocation the program will output a brief summary of the results below the page. If the results are not satisfactory you can click the ‘reset’ button and re-run the program after tinkering with the sliders. Additionally, you can proceed to Step 6. and manually adjust the allocations.
When the results are satisfactory, click on the “Save” button to save the results as a csv file. The saved file will have all of the same headers as the original student file in addition to a new header called “Choice Number”, which indicates how preferable the student’s assignment was to them.
For instance, a “Choice Number” of 1 means the student got their first choice, 2 would be their second choice, and so on. A “Choice Number” of 0 would indicate that the student didn’t get any of their choices and -1 would indicate that they got an illegal section. Note that the “Choice Number” field uses the student’s adjusted preferences (see below).
Additionally, the saved csv file will have updated information in the “Placement” column. Each student will now have this field populated with a Core Section #.
Finally, you will notice that the fields “Choice 1”, “Choice 2”,… and so on will have changed for students who listed illegal preferences (SortingHat lists these student IDs early on in the program). The new “Choice 1”, “Choice 2”, … fields are the student’s adjusted preferences. Choices are adjusted to remove any Core Section #s present in the student’s “Illegal Sections” field and to remove duplicate Core Section #s in the students preferences.