Match volunteers to roles automatically

Match volunteers to roles by skills and availability

This calculates match scores between volunteers and roles. Adapt the weights and criteria to your organisation's needs.

import pandas as pd
import numpy as np

# Load your data
volunteers = pd.read_csv('volunteers.csv')
roles = pd.read_csv('roles.csv')

print(f"Loaded {len(volunteers)} volunteers and {len(roles)} roles")

# Example volunteer data structure:
# name, skills, availability, interests, experience, location
# "Sarah", "events, social media, youth work", "Tue,Wed,Thu", "youth work", "intermediate", "Manchester"

# Example role data structure:
# role_name, required_skills, preferred_skills, availability_needed, experience_needed, location
# "Event Coordinator", "events, communication", "social media", "Tue,Wed", "intermediate", "Manchester"

def calculate_skill_match(volunteer_skills, required_skills, preferred_skills):
    """Calculate how well volunteer skills match role requirements"""
    volunteer_skills_set = set([s.strip().lower() for s in volunteer_skills.split(',')])
    required_set = set([s.strip().lower() for s in required_skills.split(',')])
    preferred_set = set([s.strip().lower() for s in preferred_skills.split(',')]) if pd.notna(preferred_skills) else set()

    # Must have all required skills
    required_match = len(volunteer_skills_set & required_set) / len(required_set) if required_set else 0

    # Bonus for preferred skills
    preferred_match = len(volunteer_skills_set & preferred_set) / len(preferred_set) if preferred_set else 0

    # Weighted score: required skills are critical, preferred are bonus
    return (required_match * 0.8) + (preferred_match * 0.2)

def calculate_availability_match(volunteer_days, role_days):
    """Check if volunteer availability overlaps with role needs"""
    vol_days = set([d.strip() for d in volunteer_days.split(',')])
    role_days = set([d.strip() for d in role_days.split(',')])

    overlap = len(vol_days & role_days)
    needed = len(role_days)

    return overlap / needed if needed > 0 else 0

def calculate_experience_match(volunteer_exp, role_exp):
    """Check if experience level is appropriate"""
    exp_levels = ['beginner', 'intermediate', 'experienced']

    try:
        vol_level = exp_levels.index(volunteer_exp.strip().lower())
        role_level = exp_levels.index(role_exp.strip().lower())

        # Perfect match is 1.0, one level off is 0.5, two levels is 0
        diff = abs(vol_level - role_level)
        return max(0, 1 - (diff * 0.5))
    except (ValueError, AttributeError):
        return 0.5  # Default if experience not specified

def calculate_location_match(volunteer_loc, role_loc):
    """Simple location match (same city/area)"""
    if pd.isna(volunteer_loc) or pd.isna(role_loc):
        return 0.5  # Neutral if location not specified

    return 1.0 if volunteer_loc.strip().lower() == role_loc.strip().lower() else 0.3

# Match each volunteer to each role
matches = []

for _, role in roles.iterrows():
    print(f"\nMatching volunteers to: {role['role_name']}")

    role_matches = []

    for _, volunteer in volunteers.iterrows():
        # Calculate individual scores
        skill_score = calculate_skill_match(
            volunteer['skills'],
            role['required_skills'],
            role.get('preferred_skills', '')
        )

        availability_score = calculate_availability_match(
            volunteer['availability'],
            role['availability_needed']
        )

        experience_score = calculate_experience_match(
            volunteer['experience'],
            role['experience_needed']
        )

        location_score = calculate_location_match(
            volunteer.get('location'),
            role.get('location')
        )

        # Weighted overall match score
        # Adjust these weights based on what matters for your organisation
        overall_score = (
            skill_score * 0.40 +           # Skills most important
            availability_score * 0.30 +    # Then availability
            experience_score * 0.20 +      # Then experience level
            location_score * 0.10          # Location nice-to-have
        )

        role_matches.append({
            'role': role['role_name'],
            'volunteer': volunteer['name'],
            'overall_score': overall_score,
            'skill_match': skill_score,
            'availability_match': availability_score,
            'experience_match': experience_score,
            'location_match': location_score,
            'volunteer_skills': volunteer['skills'],
            'volunteer_availability': volunteer['availability']
        })

    # Sort by overall score
    role_matches = sorted(role_matches, key=lambda x: x['overall_score'], reverse=True)

    # Show top 5 matches for this role
    print(f"\nTop 5 matches for {role['role_name']}:")
    for i, match in enumerate(role_matches[:5], 1):
        print(f"{i}. {match['volunteer']}: {match['overall_score']:.0%} match")
        print(f"   Skills: {match['skill_match']:.0%} | Availability: {match['availability_match']:.0%} | Experience: {match['experience_match']:.0%}")
        print(f"   Has: {match['volunteer_skills']}")
        print(f"   Available: {match['volunteer_availability']}")

    matches.extend(role_matches)

# Export all matches
matches_df = pd.DataFrame(matches)
matches_df = matches_df.sort_values(['role', 'overall_score'], ascending=[True, False])
matches_df.to_csv('volunteer_role_matches.csv', index=False)

print("\n" + "="*60)
print("Matching complete! Saved to volunteer_role_matches.csv")
print("\nTips:")
print("- Adjust the weights (0.40, 0.30, 0.20, 0.10) based on what matters most")
print("- Check if top matches make intuitive sense")
print("- Use scores as guidance, not absolute decisions")
print("- Consider creating a 'shortlist' of top 3 for each role to contact")