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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#361 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
76/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
markdown, python, scikit-learn
Área
data, documentation

Línea de trabajo

Lee las secciones Notes de GratefulPatientFeaturizer en philanthropy/preprocessing/_grateful_patient.py y de EncounterTransformer en philanthropy/preprocessing/_encounters.py; después, revisa docs/explanation/compliance_considerations.md y docs/how-to/build_grateful_patient_features.md. Añade el párrafo sobre la limitación, la referencia, las frases correspondientes para los docstrings y la entrada del changelog descritos en los criterios de aceptación. El trabajo estará terminado cuando mkdocs build --strict y make ci se ejecuten correctamente.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
Python
Estrellas
11
Forks
23
Merge medio
1 d 6 h
PR fusionados (30 d)
34

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de PhilanthroPy-Project/PhilanthroPy

Todos los issues de PhilanthroPy-Project/PhilanthroPy

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.