philanthropy 0.6.0

PhilanthroPy: Code for a cause—predictive analytics for advancement teams.

🚀 View the Full Documentation Site

What is PhilanthroPy?

PhilanthroPy is a Python library that slots directly into sklearn.pipeline.Pipeline. It covers the full predictive workflow for nonprofit and academic medical center (AMC) fundraising — from raw CRM cleaning and wealth imputation to major-gift propensity scoring, lapse prediction, and planned-giving intent.

Who it's for

One toolkit, two audiences:

• General nonprofit & university advancement teams (no PHI in scope) — CRM cleaning, RFM segmentation, wealth-screening imputation, and donor-propensity / lapse / planned-giving scoring. Start with CRMCleaner, RFMTransformer, WealthScreeningImputer, and DonorPropensityModel.
• Academic medical center (AMC) foundations running grateful-patient programs (PHI in scope, higher scrutiny) — clinical-encounter featurization via EncounterTransformer, GratefulPatientFeaturizer, and DischargeToSolicitationWindowTransformer. Before production use, read Compliance Considerations: the PII handling here is a name-based heuristic, not formal HIPAA de-identification.

Maturity

Single-maintainer MIT project at v0.6.0 (Beta). Preprocessing and the core classifiers are stable; grateful-patient featurization and philanthropy.ingest are Beta; FinancialForecastModel and philanthropy.experimental.* are Experimental and carry no API guarantees. Per-symbol stability tiers are in the API reference.

Maintenance: maintained by one person on a best-effort basis. For vendor / OSS risk reviews: the bus factor is 1. Issues and PRs are welcome.

Installation

pip install philanthropy

git clone https://github.com/PhilanthroPy-Project/PhilanthroPy.git
cd PhilanthroPy
pip install -e ".[dev]"

Quick Start

from philanthropy.datasets import generate_synthetic_donor_data
from philanthropy.models import DonorPropensityModel

df = generate_synthetic_donor_data(n_samples=500, random_state=42)
X = df[["total_gift_amount", "years_active", "event_attendance_count"]].to_numpy()
y = df["is_major_donor"].to_numpy()

model = DonorPropensityModel(n_estimators=200, random_state=0)
model.fit(X, y)
scores = model.predict_affinity_score(X)   # 0–100 affinity scale

assert scores.shape == (500,)
assert len(set(scores.round(6))) > 1       # a constant score means a broken pipeline

Try it now — zero install:

Runnable scripts: examples/quickstart.py and examples/unischema_to_scores.py run end to end and are smoke-tested in CI.

Output of plot_affinity_distribution(): the 0–100 affinity scores cleanly separate major from non-major donors.

From UniSchema events to scores

PhilanthroPy is the modeling half of an ecosystem. UniSchema normalizes fragmented advancement webhooks (GiveCampus, Slate, NPSP, Cvent, …) into a single ConstituentEvent stream. philanthropy.ingest turns that stream into the donor-level feature table the estimators expect — no glue code between the two projects.

Webhooks → UniSchema egress → read_constituent_events() → constituent_events_to_features() → predict_affinity_score(). Worked, runnable version with the full diagram: Ingest UniSchema events.

Feature overview

Full parameter documentation for every symbol below is rendered in the API reference.

🧹 Preprocessing

🤖 Models

📊 Metrics, splitters, and the rest

Guides

Tutorials — Building your first model · Avoiding temporal data leakage · Building a grateful-patient pipeline

How-to — Use the CLI · Ingest UniSchema events · Handle missing wealth data · Build grateful-patient features · Recommend ask amounts · Score matching-gift eligibility · Measure campaign efficiency · Audit score fairness · Estimate appeal uplift · Save and load models · Develop and test

Explanation — Design principles · Capacity and loyalty · Fundraising metrics · Compliance considerations · Benchmarks

Roadmap

🔜 Next

• philanthropy.visualisation.plot_capacity_heatmap()
• EnsemblePropensityModel (stacked LapsePredictor + DonorPropensityModel)

Research

S. A. Lalakiya, "AI for Advancement: Predictive Donor Analytics and Fundraising Intelligence at Scale," 2025 IEEE 11th ICCED, IEEE, 2025, doi: 10.1109/ICCED68324.2025.11325064.

This is the library author's own related work on the same problem space, using a different dataset and its own models. It is not an independent evaluation or a benchmark of PhilanthroPy. To cite the software itself, see CITATION.cff.

Contributing

See CONTRIBUTING.md for the full local test gate, the new-test-file workflow, and pre-push hook setup. In short: run make ci before every push, and never use git push --no-verify.

License

MIT License — see LICENSE for details.