~arjca/vassign

#vassign -- Volunteers Assignment

A CLI tool based on Constraint Solving Programming for assigning posts to the volunteers at an event.

#Installation

Clone that repository on your computer and cd into the cloned folder;
Setup a virtual environment: python -m venv .venv;
Activate the virtual environment: source .venv/bin/activate;
Install the CLI tool: pip install -e ..

As long as the virtual environment is activated, you now have the vassign command in your $PATH!

#How does it work?

#Input

There program takes four input files:

A setup file for stating base information;
A file containing the list of posts to fulfill along the day;
A file containing the preferences of volunteers toward the missions;
A file containing the availability of volunteers.

In this section, we briefly explain the format of these files. Examples can be found in the /samples folder.

#Format of the setup file

The setup file is a YAML file that has this form:

slots:
    - Slot_1
    - Slot_2
    - ...

missions:
    - name: Mission_1
      requires_training: false
    - name: Mission_2
      requires_training: true
    - ...

pauses:
    - name: Lunch
      slots:
          - Slot_2
          - Slot_3
      min_number_of_volunteered_slots: 2
    - ...

The file starts with a list of slots, that are labels for how the day is cut (for instance, a slot can be "today from 8AM to 9AM). These labels are used throughout the software;
Then, there is a list of missions. A mission has a name that will be used in other configuration files, and may require training: people that are assigned to this mission should stay longer if possible;
Finally, volunteers can earn a (or several!) break during the day. Each break times derive from a list of pauses. Each pause has a name and a list of slots during which the break can take place. Each pause requires a minimum number of volunteered slots (for instance, you will not be offered lunch if you have not volunteered for at least two slots).

#Format of the posts file

The posts file is a CSV file that looks like the following:

Mission,   Slot_1, Slot_2, ...
Mission_1, 1,      2,      ...
Mission_2, 3,      2,      ...
...

As you may have guessed, it indicates the number of volunteers required to complete each mission at any given time slot.

#Format of the volunteers missions preferences file

The file containing the preferences of volunteers towards missions is a CSV file that looks like the following:

Volunteer, Mission_1, Mission_2, ...
Corinne,   ENJOY,     REFUSE,    ...
Michelle,  ACCEPT,    ACCEPT,    ...
...

It states, for each volunteer, how they like each missions. They have three choices:

REFUSE the mission, so they cannot be assigned to it;
ACCEPT the mission, so they can be assigned to it but this is not their preference;
ENJOY the mission, so they can be assigned to it and they will be prioritary if there is a choice to make.

#Format of the volunteers time slots file

The file containing the availability of volunteers is a CSV file that looks like the following:

Volunteer, Slot_1, Slot_2, ...
Corinne,   T,      F,      ...
Michelle,  T,      T,      ...

It states if the volunteers are available at a given slot (T, as in True) or not (F as in False).

Note that the volunteers mentioned here must be the same as is the volunteers missions preferences file.

#Output

The output of the program is a CSV file that contain the mission of each volunteer at each slot. For instance:

Volunteer, Slot_1,    Slot_2,    ...
Corinne,   Mission_1, -,         ...
Michelle,  +,         [Lunch],   ...
...

For each slots, volunteers have four possibilities:

They are assigned to a mission, so the name of the mission is written as-is;
They have a break time, so the name of the pause is written enclosed in brackets ([ and ]);
They have not been assigned to a mission (because all mandatory posts have been fulfilled) but they are available: it is denoted by a +;
They are not available: -.

#Command

The command is the following:

vassign --setup [SETUP] \
        --posts [POSTS] \
        --volunteers_missions [VOLUNTEERS_MISSIONS] \
        --volunteers_slots [VOLUNTEERS_SLOTS] \
        --output [OUTPUT]

Each argument is a path to a file that follow the previously presented formats, except for the output argument that is the path where the output file must be generated

refs

clone