docs: state that grateful-patient features time every gift against the latest discharge

Open Beginner friendly
  • Is something wrong?
#361 2 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@jimoholayinka01 is already working on this.

Since Nov 11, 2026.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown, python, scikit-learn
Domain
data, documentation

Research direction

Read the Notes sections of GratefulPatientFeaturizer in philanthropy/preprocessing/_grateful_patient.py and EncounterTransformer in philanthropy/preprocessing/_encounters.py, then check docs/explanation/compliance_considerations.md and docs/how-to/build_grateful_patient_features.md. Add the limitation paragraph, pointer, matching docstring sentences, and changelog bullet described in the acceptance criteria. Done means mkdocs build --strict and make ci pass.

Written by the indexing model from the issue text.

Description

documentation good first issue roadmap
Goal

A reader of the grateful-patient docs learns, before they use the features, that a donor with several hospital stays is measured against their most recent discharge, not the stay closest to each gift.

Background

This is the "document the limitation now" half of the decision proposed on #110 (comment of 2026-09-06). It was agreed as cheap and honest but never filed, so the limitation is still undocumented.

What the code does, so the paragraph describes it exactly:

  • GratefulPatientFeaturizer.fit (philanthropy/preprocessing/_grateful_patient.py, "Step 4") groups encounters by merge_key and keeps one last_discharge per donor (grouped[discharge_col].max()), after the as_of cutoff.
  • EncounterTransformer (philanthropy/preprocessing/_encounters.py) stores the same per-donor last_discharge.
  • __getstate__ drops the raw encounter_df so a saved model carries no patient rows (#78). Keying each gift to its own nearest prior discharge would need those rows at transform time, which is why this is a limitation rather than a quick fix.
Acceptance criteria
  • A short "Known limitation: repeat patients" paragraph in docs/explanation/compliance_considerations.md, and a one-line pointer to it from docs/how-to/build_grateful_patient_features.md.
  • It says who is most affected (repeat or long-course patients, e.g. oncology or transplant), what goes wrong (a gift made after an earlier stay is timed against a later one), and that as_of does not fix it (it cuts future encounters, it does not pick the nearest one).
  • It links #110 for the per-gift keying design.
  • A matching sentence in each class's docstring Notes section.
  • mkdocs build --strict and make ci pass; one CHANGELOG bullet under [Unreleased], ### Documentation.
Scope

Docs and docstrings only. Changing the keying itself is #110.

Where to start
  • philanthropy/preprocessing/_grateful_patient.py (fit, __getstate__)
  • philanthropy/preprocessing/_encounters.py
  • docs/explanation/compliance_considerations.md
Dependencies
  • None

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.