~arjca/vassign

CLI tool for assigning volunteer to their tasks at an event
feat: initial push to Git

refs

dev
browse  log 

clone

read-only
https://git.sr.ht/~arjca/vassign
read/write
git@git.sr.ht:~arjca/vassign

You can also use your local clone with git send-email.

#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