GatorGrouper is a Python 3 program that assigns a list of students to groups of a specified size. The output of this program could then be communicated to the students in a specific class. Then, if a course instructor is using GitHub Classroom, you can ask the students in your class to create and join their assigned group.
As a Python 3 program, GatorGrouper relies on pip for installation. To ensure that all of the dependencies are installed correctly, please type the following commands before running GatorGrouper.
pip3 install --upgrade pip
pip3 install -r requirements.txt
Note that you may have Python 3 setup in different ways on your computer. For
instance, you may prefer to install GatorGrouper's dependencies in a site-wide
location and then you would have to type sudo pip install -r requirements.txt
. Alternatively, you may choose to install the dependencies by
typing pip install --user -r requirements.txt
.
GatorGrouper was developed to easily run in conjunction with a venv-based
Python 3 virtual environment. This
means that if you are in the directory that contains gatorgrouper
then you could type python3 -m venv gatorgrouper
to create all of
the components of a venv-based virtual environment in the gatorgrouper
directory. Once you complete this step, you can type the command source gatorgrouper/bin/activate
to activate the venv-based virtual environment.
Interested in learning more about the basics of virtual environments in Python
3? You can read this
article
to further develop your understanding of this topic.
GatorGrouper requires users to use Python 3. You can type python --version
into the terminal window to check the current version of Python on your
workstation. If you do not have the right Python version, you can go to
Python to download the latest version of
Python. If you can not download or upgrade Python on your workstation, you can
download the Pyenv tool to set up a virtual
environment for the newest Python version.
To install Pyenv, you can use Pyenv Installer by typing the command in terminal:
curl https://pyenv.run | bash
After the completion of this command, Pyenv should be installed. Please make
sure that you have the following lines in your ~/.bashrc
or similar file
types. Notices that different development evironment may have different
configuration configuration files (i.e., "dotfiles"). You can see more examples
and learn more in the instructions of Professor Kapfhammer's
dotfiles repository.
export PATH="~/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
Once Pyenv is installed, you can install the latest version of Python
for your Pyenv. We suggest developers to use Python 3.7.2
for gatorgrouper
.
However, any version after Python 3.6.8
would work well. To install, you
should restart your terminal window by typing pyenv install 3.7.2
and pyenv global 3.7.2
.
After you finish this process, you should be able
to type python --version
and get Python 3.7.2
or other version after
Python 3.6.8
in your terminal.
Ensure that you have installed gspread and oauth2client in the root directory of the repository. In the terminal use the command:
python3 -m pip install --user gspread oauth2client
Create a Google Sheets spreadsheet and a Google Form in Google Drive. In the Form, create yes or no questions to measure the capabilities and skills of the students that you wish to group. After you have at least one submission of the Form, you can go to the responses tab and click on the green icon with the white cross through it. This will enable you to link the Sheet to the Form. You can either create a new Sheet or link to a preexisting one. If you need to change the destination, you can click on the three dot icon menu to the right of the green icon and select "Select response destination".
Open the .json
file in the gatorgrouper
repository and find the "client-email"
.
Copy the quoted text that looks like an email address. Return to the Sheet and
open the sharing options. Paste the address and click send. Alternatively, if
you would like to create your own service account for confidentiality and
security, follow the tutorial found at www.twolio.com
to create a personal service account.
Within defaults.py
, update the DEFAULT_WORKBOOK
constant to the name of your
Sheet.
GatorGrouper accepts command line arguments and then generates output in your
terminal window. Using the defaults of storing your student identifiers in the
file called students.csv
and creating groups of two students means that you
will run GatorGrouper with this command:
python3 gatorgrouper.py
In order to see all the possible commands and their descriptions, enter the following command:
python3 gatorgrouper.py -h
To specify the size of the groups, use the flag --group-size
.
python3 gatorgrouper.py --group-size 4
This indicates that groups should each contain 4 members. The provided group size should be greater than 1 and equal to or less than half the total number of students. If the group size is not specified, the default group size is 3.
To specify the number of groups the students should be placed in, use the flag
--num-groups
.
python3 gatorgrouper.py --num-groups 4
This indicates that the students should be divided into 4 groups. The number of
groups should be at minimum 1 and at maximum the number of students to be placed
into groups. If the number of groups is not specified or is specified as '0' the
flag is ignored. This flag can be used along side --absentees
, --random
, and
--round-robin
.
To randomly group the students, use the flag --random
.
python3 gatorgrouper.py --random
This will randomly group the list of students you have provided, and is the default grouping method used when none is provided. This method of grouping is appropriate for cases where the assignment does not require that groups have a minimum number of members that have responded as having a skill related to the assignment. Consider using this method for assignments like in class exercises, small discussion groups, or peer editing.
To group students using the round-robin method, use the flag --round-robin
.
python3 gatorgrouper.py --round-robin
The round-robin method takes the responses from the Sheet into account when sorting students into groups. The yes and no responses from the Sheet are represented as true and false. Round-robin randomizes the categories and assigns a student, one at a time, to each group by using the first value indicated as true. When all of the students with true values are assigned, it goes back and adds a student to each group until there are no students remaining. This method of grouping is appropriate for cases where the assignment or task would be more effective if every group had a relatively even spread of students that responded as having a skill related to the assignment. Consider using this method for assignments where students might have specialized roles. Take for example a poll that asks the students if they would be interested in taking on more responsibility as a team leader. Using the random method and the -v flag to see additional output, GatorGrouper may produce an output like this:
scores: [4, 4, 2, 0, 6, 4]
average: 3
The score of a group is determined by the amount of students that answered "yes" to a particular question. In this example, there is one group that has no students that are willing to be a team leader. However if you use the round robin grouping method, one possible output would be:
scores: [4, 6, 4, 2, 2, 2]
average: 3
In this case, the average score is the same as with the random grouping method, but all the groups have atleast one student willing to be a team leader. This has the potential to make the assignment more effective by maximizing team effectiveness.
To indicate which students are absent so they are not grouped, use the
flag --absentees
. The arguments can be entered in the following ways:
python3 gatorgrouper.py --absentees student1 student2
python3 gatorgrouper.py --absentees 'student1' 'student2'
python3 gatorgrouper.py --absentees "student1" "student2"
Note that the absent students' names must be separated by spaces, not quotes. The names can be surrounded by single or double quotes if desired.
If no absentees are indicated with this flag, then the program will assume that there are no students absent.
To bypass the Google Forms integration and instead supply a list of students
directly to the program, use the --students-file
flag.
python3 gatorgrouper.py --students-file "file_name.csv"
python3 gatorgrouper.py --students-file file_name.csv
To see detailed general output to monitor progress, use the flag -v
or
--verbose
.
python3 gatorgrouper.py --verbose
To see detailed technical output to diagnose problems, use the flag -d
or
--debug
.
python3 gatorgrouper.py --debug
If neither of these flags are set, logging will only be shown if an error occurs.
$ python3 gatorgrouper.py --group-size 3 --absentees becky george --random
GatorGrouper: Automatically Assign Students to Groups
https://github.com/gkapfham/gatorgrouper
Successfully placed 9 students into 3 groups
Group 1
smithj
robertss
johnsont
Group 2
peggys
stevensons
ronp
Group 3
georgeh
youngr
harrisonf
Each of the previous commands were run on an Ubuntu 16.04 workstation running Python 3.5.2. However, GatorGrouper should run correctly on a wide variety of operating systems that support Python version 3.
The test suite is designed to test the different functions of gatorgrouper.py
.
The first function the test suites test is to make sure that there are the
correct amount of students in each group. The test suite also makes sure that
the shuffle function is working correctly. There are also test cases to make
sure that the professor has the option to mark students absent, and these
students will not get grouped. Lastly, the test suite test checks to see if
students are being correctly grouped based on category.
The test suite requires pytest-flake8
, which can be installed with the
following command:
pip3 install --user pytest-flake8
From the root directory, the test suite can be ran with the following command:
python3 -m pytest tests
For any future issues with linting, you can install an autolinting tool with:
pip3 install --user autopep8
To run the tool, type the following into the main directory.
autopep8 --in-place --aggressive *.py
If there are any linting issues that were not fixed by the tool, the error message from the test suite will direct you to where the issue is and tell you what it is in order for you to fix it.
Test coverage reporting is handled with pytest-coverage
. The following
commands will install and run pytest-coverage
.
pip install pytest-cov
coverage run --source tests -m py.test
coverage report
If you have any problems with installing or using GatorGrouper, then please create an issue associated with this Git repository using the "Issues" link at the top of this site. The contributors to GatorGrouper will do all that they can to resolve your issue and ensure that the entire tool works well in your teaching and development environment.