People pairer 🍐🤝🍐

A simple program for pairing people together, ensuring that participants:

• will not be paired with people in their own team
• will not be paired with the same people from previous iterations

This app was created to support Randomized Coffee Trials at the Strategy Unit and the NHS RAP Code Review Buddies Network.

How to use this package

Data preparation

1. Clone a copy of the repository to your local machine.
2. Create a data folder. Put your participants.csv in the data folder. Your participants.csv should have the columns name, team, email, and active. The active column is Boolean (TRUE/FALSE). A sample participants.csv is provided with dummy data.
3. Create a pairings subfolder and store any previous pairings, if any, there. A sample is provided with dummy data.

Your repository structure should look like the below:

.
├── data/
│   ├── pairings/
│   │   ├── round_1.csv
│   │   └── round_2.csv
│   └── participants.csv
├── src/
│   └── people_pairer/
│       ├── main.py
│       └── ...
├── README.md
├── pyproject.toml
└── ...

Running people_pairer using uv

This package is built using uv. If you have uv installed:

1. Create a new virtual environment with uv venv
2. Install the package locally with uv pip install .
3. Activate the virtual environment with .venv\Scripts\activate on Windows, or source .venv/bin/activate on macOS and Linux
4. Run people pairer with uv run -m people_pairer.main.

Running people_pairer without uv

1. Install the package locally with pip install .
2. Run people pairer with python -m people_pairer.main.

Optional arguments

There are optional arguments:

• --data_filepath if your data is stored an a folder other than data
• --past_pairings for the number of past pairings to consider when creating new pairings. Defaults to 3.

To run people_pairer using data stored in the sample_data folder, ensuring that pairs are not repeated from the previous 5 iterations, the uv command would be: uv run -m people_pairer.main --data_filepath sample_data --past_pairings 5.

Without uv, it would be python -m people_pairer.main --data_filepath sample_data --past_pairings 5

Contributing

This package is maintained by @yiwen-h. Contributions are very welcome, and please feel free to raise any issues you may encounter.

Related packages

The files generated by this package are designed to be used with the rct_streamlit and rct_api packages for automating the sending of emails to the generated pairs. They aren't necessary but may be useful additional tools.