---
title: "Related work and grouper"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Related work and grouper}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
bibliography: references.bib
--- 


```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Introduction

In this vignette, we provide a brief, non-exhaustive overview of related work to 
assign students to projects, in an educational setting. Finally, we introduce 
our `grouper` package.

## Balancing staff workload and student preferences

One of the earlier papers found was by @anwar2003student. The goal of the educator
in that paper was to assign students to two types of project: individual ones 
and group ones. For the individual projects, students were asked to rank their top
four projects from a list of project briefs. Each student was then assigned to a 
project and a corresponding staff member.

The assignment was carried out using two models. In the first model, the
objective was to minimise the total number of projects that each staff managed.
In the second model, the feasible solutions from the first model were used to
decide upon an assignment that maximised the number of students obtaining their
first choice projects. 

Compared to the models in `grouper`, the primary difference is in the objective
function. In our case, we only work with the student preference; there is no
need to balance staff workload since the projects are run within a single
course.

For the group project, students were asked to rank their top 3 projects
*individually*. They were then allocated groups that maximised their preferences.
Compared to the model in our package, this approach does not allow for
self-formed groups, or for larger projects that involve sub-groups.

## OptAssign

In many ways, the model described in @meyer2009optassign is similar to ours. The
objective function there maximises student preference for project topics. The
model in the paper also discusses an extension whereby some groups of students
can be favoured for particular topics. This is carried out through the inclusion
of weights in the objective function. Another additional feature adds
contstraints to ensure that students with certain skills are included in
particular topics. For instance, a project topic on "Marketing surveys" may
require at least two students with a statistics background in the group.

Overall, this model formulation is very similar to the one in our package.
Again, one difference is in the affordance for self-formed groups, and for
sub-groups in the project team.

## Students to elective courses

This paper @berovs2015integer deals with assignment of students to elective
courses in Croatia. In short, the institution offers a fixed number of such
courses. Every student must be enrolled in a pre-determined number of courses.
Each student selects and ranks a certain number of electives. The integer
programming solution that is derived here maximises the total student
satisfaction, based on these rankings.

## Assigning students to groups based on traits

The master's thesis from @mcguirk2020assigning describes a very complex integer
linear programming model. The assignment was used to assign students to
discussion groups at the University of New Hampshire chemistry department. The
complete objective function can be written as:

\begin{eqnarray}
\text{Minmise:}\; \text{preferences} + \text{sizes} + \text{single-trait} + \text{shared-trait}
\end{eqnarray}

The first component, preferences, incorporates the ranking that put students put 
down for a group. The second component was used to control the overall group size. Note 
that in our formulation, this appears as a constraint. The third component arises 
as a result of the educators experience in teaching this course. They realised that 
if a student is the only one with a certain trait, e.g. gender, year-of-study, etc.,
that student would be disinclined to participate in discussions. This is a very 
interesting point! The final portion of the objective function applies a penalty if
all students in the group share the same trait.

In our formulation, we have avoided using multi-objective functions for the most
part. The reason for this decision is that it is very difficult to decide how each
component should be weighted. It typically requires a further step of post-assignment
sensitivity analysis.

Another similarity with our findings is the recommendation to use Gurobi over 
open source solvers.

## Student-to-project supervisor assignment

The next article we discuss is @ramotsisi2022optimization. The formulation of this 
model was the result of a thorough investigation into the process by which 
students are assigned projects that are supervised by faculty members at the 
University of Botswana. However, similar to @anwar2003student, the objective 
function in this study aims to maximise the total workload of supervisors. It 
does not approach the problem solely from the angle of student preferences.

## Automated group assignments in academic setting

In the final work that we discuss, @bonfert2020improving use a probabilistic 
weighted optimisation routine to perform the group assignment, based on survey 
input data. Questions in the survey pertain to scheduling, desired attributes 
of team members, and indications of whether a student may be isolated. For each
question, a homogeneity score is computed using the answers from all members of a 
group. This score is summed over all questions to result in a "fitness" score 
for each group. A probabilistic hill-climbing algorithm is then used to maximise 
the average fitness score. Out of the papers discussed on this page, this is 
the only one that does not use an integer linear programming model.

# Introducing `grouper` package

`grouper` provides three optimisation models, each formulated as an integer
linear program.

## Diversity-Based Assignment

The Diversity-Based Assignment (DBA) model assigns students to groups and
topics while maximising diversity based on student attributes and balancing
skill levels across groups. Users provide a group composition table,
demographic or dissimilarity information, optional skill scores, and model
parameters controlling group and topic sizes.

## Preference-Based Assignment

The Preference-Based Assignment (PBA) model assigns self-formed student groups
to topics to maximise their submitted preference scores. Topics may be repeated,
and each project team may contain multiple sub-groups. Users provide a group
composition table, a group-by-topic preference matrix, and model parameters
controlling topic repetitions and group sizes.

## Multi-role Workload Allocation

The Multi-role Workload Allocation model assigns TA, grading, and lighter E
duties across individuals. It balances exact role demand, annual workload
spread, role-specific preferences, seniority-based E allocation, and optional
cohort protection. Users provide individual workload data, role demand,
optional TA and grading preference matrices, and objective weights.

## Function organisation

The package API follows the same stages for all three models:

| Stage | Common entry point | Model-specific functions |
|:--|:--|:--|
| Extract inputs | `extract_info()` | `extract_student_info()` for DBA/PBA; `extract_multirole_info()` for multi-role |
| Prepare model | `prepare_model()` | `prepare_diversity_model()`, `prepare_preference_model()`, `prepare_multirole_model()` |
| Solve | `solve_assignment()` | `ompr::solve_model()` for lower-level solver control |
| Format output | handled by `solve_assignment()` | `assign_groups()` for DBA/PBA; `assign_job()` for multi-role |

For DBA and PBA, model parameters can be supplied directly to
`prepare_model()` or read from a YAML file with `extract_params_yaml()`. The
multi-role workflow supplies extraction settings to `extract_info()` and model
weights or bounds to `prepare_model()`.

Refer to the remaining vignettes for more information about the model definition
and application. 

In our package, we use the `ompr` framework for optimisation, which means that
you are free to use any solver. In our small examples, we demonstrate the
package using the `glpk` solver. However, for more complicated problems, we
highly recommend the `gurobi` solver. There is a free academic license for this 
tool. However, the `ROI.plugin.gurobi` and `gurobi` packages are not on CRAN. The 
following links will aid in installing the `gurobi` package:

* [Installing the R package gurobi](https://docs.gurobi.com/projects/optimizer/en/current/reference/r/setup.html)
* [Guide to installing gurobi optimiser](https://cran.r-project.org/package=prioritizr/vignettes/gurobi_installation_guide.html)

The following github repository provides instructions on install the gurobi solver:

* [Installing `ROI.plugin.gurobi`](https://github.com/roigrp/ROI.plugin.gurobi)


# References