Skip to content

Design principles

PhilanthroPy addresses structural problems that recur in nonprofit data science. Six principles shape every estimator.

  • Leakage-safe by design. Temporal leakage across fiscal years produces a model that scores well in backtests and fails in production. PhilanthroPy's transformers and FiscalYearGroupedSplitter anchor cross-validation splits to the organization's fiscal calendar, so each split reads like a real walk-forward prediction.
  • Idempotent transformers. Fill statistics, encounter summaries, and imputation snapshots freeze at fit() time. Call transform() as many times as you like on streaming data: the result is identical and never leaks.
  • scikit-learn native. Public estimators are exercised by a parametrize_with_checks battery over scikit-learn's check_estimator: 20 configured instances, 1016 checks. Four row-reducing or constructor-argument classes (RFMTransformer, MatchingGiftFeaturizer, EncounterTransformer, GratefulPatientFeaturizer) carry hand-written equivalent coverage with a recorded reason instead, and a test fails the build if a public estimator is in neither list. UpliftTLearner is outside the fit(X, y) contract altogether and is documented in the API reference. Each estimator supports set_output(transform="pandas"), cloning, and cross-validation pipelines out of the box.
  • NaN-transparent. Real CRM data is full of empty and irregular fields; third-party imports may miss up to 60% of their values. PhilanthroPy transforms run with allow_nan = True, so nothing is silently dropped and the pattern of missingness becomes a signal you can use.
  • PII-aware. EncounterTransformer drops identifier-like columns by name: its PII_PATTERNS default matches Medical Record Numbers (MRNs), Social Security Identifiers and similar fields, and pii_patterns overrides it. GratefulPatientFeaturizer reaches the same place from the other direction: it reads only encounter metadata (service line, physician, dates) and returns four numeric aggregates, so no identifier can reach the model through it. Column dropping is a configurable, name-based heuristic (defense-in-depth), not formal HIPAA de-identification. See Compliance Considerations.
  • Proxy-bias aware. Wealth and capacity features (estimated net worth, real-estate value, geography) can stand in for protected characteristics, so a model that never sees a protected attribute can still produce disparate outcomes. Audit scored cohorts with philanthropy.metrics.disparate_impact_ratio, and involve your equity and compliance stakeholders before you act on scores.