Route service users to appropriate support

Classify referrals to support pathways

This builds a model to recommend appropriate support pathways. Adapt the features to your service model and needs assessment.

import pandas as pd
import numpy as np
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split
from sklearn.metrics import classification_report, confusion_matrix

# Load historical referral data
# Columns: referral_id, assessment features, pathway_allocated, outcome_success
referrals = pd.read_csv('historical_referrals.csv')

print(f"Loaded {len(referrals)} historical referrals")
print(f"Pathways: {referrals['pathway_allocated'].unique()}")
print(f"Success rate: {referrals['outcome_success'].mean()*100:.1f}%")

# Define features that predict pathway suitability
# Adapt these to your needs assessment and service model
feature_cols = [
    'risk_level',  # 1-5 scale
    'housing_stable',  # 0/1
    'support_network_strength',  # 1-5 scale
    'previous_service_completion',  # 0/1
    'mental_health_needs',  # 0/1
    'substance_use_needs',  # 0/1
    'employment_needs',  # 0/1
    'crisis_indicators',  # 0/1
    'ready_for_group_work',  # 0/1
    'months_since_last_service'  # numeric
]

# Prepare data
X = referrals[feature_cols]
y = referrals['pathway_allocated']  # The pathway they were allocated to

# Filter to successful referrals only for training
# We want to learn patterns of successful allocations
successful_referrals = referrals[referrals['outcome_success'] == 1]
X_successful = successful_referrals[feature_cols]
y_successful = successful_referrals['pathway_allocated']

print(f"\nTraining on {len(successful_referrals)} successful referrals")

# Split into train/test
X_train, X_test, y_train, y_test = train_test_split(
    X_successful, y_successful,
    test_size=0.3,
    random_state=42,
    stratify=y_successful  # Ensure all pathways represented
)

# Train Random Forest classifier
rf = RandomForestClassifier(
    n_estimators=100,
    max_depth=10,
    random_state=42,
    class_weight='balanced'  # Handle imbalanced pathways
)
rf.fit(X_train, y_train)

# Evaluate
y_pred = rf.predict(X_test)
print("\nModel Performance:")
print(classification_report(y_test, y_pred))

# Confusion matrix shows which pathways get confused
print("\nConfusion Matrix:")
print(confusion_matrix(y_test, y_pred))

# Feature importance
feature_importance = pd.DataFrame({
    'feature': feature_cols,
    'importance': rf.feature_importances_
}).sort_values('importance', ascending=False)

print("\nMost important factors for pathway recommendations:")
print(feature_importance.head(10))

# Function to recommend pathway for new referral
def recommend_pathway(assessment_data):
    """
    Generate pathway recommendation with confidence and explanation
    assessment_data: dict with feature values
    """
    # Convert to format model expects
    features = [assessment_data[col] for col in feature_cols]
    features_array = np.array(features).reshape(1, -1)

    # Get probabilities for each pathway
    pathways = rf.classes_
    probabilities = rf.predict_proba(features_array)[0]

    # Get top recommendation
    top_idx = np.argmax(probabilities)
    recommended_pathway = pathways[top_idx]
    confidence = probabilities[top_idx] * 100

    # Get alternative
    sorted_indices = np.argsort(probabilities)[::-1]
    alternative_idx = sorted_indices[1]
    alternative_pathway = pathways[alternative_idx]
    alternative_confidence = probabilities[alternative_idx] * 100

    # Identify key factors driving recommendation
    # Which features contributed most to this decision
    feature_values = pd.DataFrame({
        'feature': feature_cols,
        'value': features,
        'importance': rf.feature_importances_
    })

    # Features that are "active" (high value) and important
    feature_values['contribution'] = feature_values['value'] * feature_values['importance']
    top_factors = feature_values.nlargest(3, 'contribution')

    recommendation = {
        'recommended_pathway': recommended_pathway,
        'confidence': round(confidence, 1),
        'alternative_pathway': alternative_pathway,
        'alternative_confidence': round(alternative_confidence, 1),
        'key_factors': top_factors['feature'].tolist(),
        'all_pathway_scores': {
            pathway: round(prob * 100, 1)
            for pathway, prob in zip(pathways, probabilities)
        }
    }

    return recommendation

# Example: Recommend for new referral
new_referral = {
    'risk_level': 3,
    'housing_stable': 1,
    'support_network_strength': 4,
    'previous_service_completion': 1,
    'mental_health_needs': 1,
    'substance_use_needs': 0,
    'employment_needs': 1,
    'crisis_indicators': 0,
    'ready_for_group_work': 1,
    'months_since_last_service': 6
}

recommendation = recommend_pathway(new_referral)

print("\n" + "="*60)
print("Example Recommendation for New Referral:")
print("="*60)
print(f"\nRecommended pathway: {recommendation['recommended_pathway']}")
print(f"Confidence: {recommendation['confidence']}%")
print(f"\nAlternative: {recommendation['alternative_pathway']}")
print(f"Confidence: {recommendation['alternative_confidence']}%")
print(f"\nKey factors driving recommendation:")
for factor in recommendation['key_factors']:
    print(f"  - {factor}")
print(f"\nAll pathway scores:")
for pathway, score in recommendation['all_pathway_scores'].items():
    print(f"  {pathway}: {score}%")

print("\n" + "="*60)
print("IMPORTANT:")
print("- This is a recommendation, NOT a decision")
print("- Professional must review considering full context")
print("- Never route automatically without human oversight")
print("- Model can't see everything (recent changes, cultural factors, etc.)")
print("="*60)

# Save model for use
import pickle
with open('pathway_recommendation_model.pkl', 'wb') as f:
    pickle.dump(rf, f)

print("\nModel saved to pathway_recommendation_model.pkl")
print("\nNext steps:")
print("1. Review model performance with service delivery team")
print("2. Test recommendations against professional judgement")
print("3. Implement with mandatory human oversight")
print("4. Track outcomes and refine monthly")