A webapp that generates fair groups for field trips (IB Group 4 Project).
https://pyxidatol-c.github.io/group-m4ker/
(instructions for MacOS)
- Download the latest build from https://github.com/Pyxidatol-C/group-m4ker/releases/latest
- Unzip the downloaded file to an easily findable location. We will use
~/Desktop
. - Open up terminal. Type in the following lines:
cd Desktop/build/ # you can tab for auto-complete
python -m SimpleHTTPServer # or `python3 -m http.server`
- Open http://0.0.0.0:8000/ in your browser - done!
Firstly, you need to have a spreadsheet of the students' information, like:
Student | Gender | Leadership | Bio | Chm | Phy |
---|---|---|---|---|---|
Jingjie Yang | M | HL | HL | ||
Lilia Evgeniou | F | Yes | HL | HL |
If you just want to try the app out, a mock data file is available: examples/data_oui.csv
Refer to here for specifications on the header name and cell values of the columns.
- You can upload a different list of students by clicking on the cross at the top-left corner.
- You can edit, delete, or add a row using the corresponding buttons.
- It is possible to filter by a value or search for a name using the corresponding fields.
- Once you have finished editing, remember to save the csv using Export as CSV near the top-right corner if you wish to keep the changes after closing the tab.
- Click on the tick at the top-right corner to proceed.
- Use the + and - buttons to adjust the number of groups you wish to generate.
- Click on the black icon to generate the groups. This process can be slow.
- Alternatively, you can upload a saved groups file by clicking on the white icon - more on this later.
- You may now view the generated groups.
- After selecting a student, all other students of the same profile (same gender, subjects, leadership) will be highlighted.
- Once two students of the same profile are selected, you can use the red "Swap!" button located at the bottom-right corner to swap them. In this way, it is usually possible to separate students who do not get along together without compromising the fairness of the groups.
- You can undo, redo, and save the swaps made - but don't forget to download the groups file by clicking on the button at the top-right corner.
- This happens when the list of students used to generate the groups does not match the loaded list. The consequences include missing or mismatched information and possibly an unfair distribution of students.
- You can re-upload/generate the groups using the loaded list of students by clicking the "OK" button;
- alternatively, you can view/edit the loaded list of students and maybe upload a different list using the "VIEW STUDENTS" button.
Other unidentified issues may occur. Please
- take a screenshot (with the console if possible) and open an issue on https://github.com/Pyxidatol-C/group-m4ker/issues
- reload the page and continue using the app, hoping that you can't reproduce the bug
Below we detail the requirements for the headers and cells for each column.
Note that the headers are case and space insensitive - " "
s are ignored and "A"
is considered the same as "a"
.
- the header must include
Name
orStudent
- e.g.
Student
,Name
, orStudent Name
- e.g.
- the cells can be anything
- the header must include
Gender
orM/F
- the cells can be either
M
for male,F
for female, or other values (default if the column is not found).
- the header must include
Leader
- e.g.
Leadership
- e.g.
- the cells can be either:
- non-empty, e.g.
Yes
- the student is considered as a strong leader - empty - otherwise (default)
- non-empty, e.g.
- the header must include
BIO
-
e.g.
BIO level
-
If 2 column headers both include
BIO
, the column on the left will be chosen:... BIO Level BIO Group ... ... SL G4 ... Here
BIO Level
and notBIO Group
will be identified as the column for the students' biology levels.
-
- the cells have to be one of:
SL
- standard levelHL
- higher level- anything else - not taking this subject (default)
- the header must include
CHM
- e.g.
CHM level
- e.g.
- the cells have to be one of:
SL
- standard levelHL
- higher level- anything else - not taking this subject (default)
- the header must include
PHY
- e.g.
PHY level
- e.g.
- the cells have to be one of:
SL
- standard levelHL
- higher level- anything else - not taking this subject (default)
Finally, please export your spreadsheet in csv
format so that the app will work properly.
- This project was bootstrapped with Create React App.
- The nice-looking tables and buttons n all are from Material-UI and material-table.
- The webapp is deployed on github pages using gh-pages
- To publish the zip for offline usages, remove the
homepage
entry in package.json
- This project has no testing whatsoever.
- The code is written in roughly 3 days by someone who has not done any front-end development since a year ago.
- The group generation algorithm is copied from https://github.com/ejm-programming-club/Group-M4ker, a no longer maintained iOS version of this app.
- The algorithm finds and executes the swap that decreases the differences between groups by the greatest amount, until any swap would make the groups worse.
- I do not actually know if steepest descent is more effective than random descent, or if the returned grouping is a local or global optimum - todos for
neverlater.