docs: check whether a donor score is calibrated, by decile, on your own file

Open
  • Is something wrong?
#343 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
70/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python, scikit-learn
Domain
documentation, machine-learning

Research direction

Read docs/how-to/estimate_donor_lifetime_value.md for the held-out-year pattern and philanthropy/datasets/_panel.py for make_donor_panel. Write the new page docs/how-to/check_score_calibration.md, then add it to docs/how-to/index.md and mkdocs.yml. Done when the decile table runs without a download and mkdocs build --strict passes.

Written by the indexing model from the issue text.

Description

documentation good first issue roadmap
Goal

A user can tell whether "a score of 0.3" means about 30% of those donors give, using only scikit-learn, before they put the number in front of a gift officer.

Acceptance criteria
  • New how-to docs/how-to/check_score_calibration.md: fit DonorPropensityModel on the earlier fiscal years of a gift panel, score the last year, and compare predicted vs actual per decile with sklearn.calibration.calibration_curve(y, p, n_bins=10, strategy="quantile").
  • It shows the table, not only a plot, and says in plain words what an over- or under-confident decile means for a mailing list.
  • It shows CalibratedClassifierCV(..., method="sigmoid") as the fix and fits it on a fold the model was not trained on. The project's floor is scikit-learn 1.6, where cv="prefit" is deprecated: wrap the already-fitted model as CalibratedClassifierCV(FrozenEstimator(model), method="sigmoid") (from sklearn.frozen import FrozenEstimator).
  • It says what the library already does, so nobody calibrates twice: MajorGiftClassifier is Platt-calibrated internally over 5 folds, and the DonorPropensityModel docstring reports that an isotonic wrapper lowered the top-10% hit rate on all five KDD Cup 1998 seeds. The point of the page is checking calibration on a later year of your own file, not re-fitting it by default.
  • Runs on philanthropy.datasets.make_donor_panel so it needs no download; added to docs/how-to/index.md and mkdocs.yml; mkdocs build --strict passes.
Scope

Docs only. No new public function: scikit-learn already has calibration_curve and CalibratedClassifierCV.

Where to start
  • docs/how-to/estimate_donor_lifetime_value.md for the held-out-year pattern
  • philanthropy/datasets/_panel.py
Dependencies
  • None

Phase order is a release plan, not a rule against picking up independent work early. Comment on this issue before you start so two people don't build the same thing.

Dominant language
Python
Stars
11
Forks
23
Avg merge
15h 13m
Merged PRs (30d)
30

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from PhilanthroPy-Project/PhilanthroPy

All issues in PhilanthroPy-Project/PhilanthroPy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.