requipso 0.2.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. requipso/__init__.py +27 -0
  2. requipso/cli.py +11 -0
  3. requipso/completer.py +103 -0
  4. requipso/data.py +72 -0
  5. requipso/descriptive_pipeline.py +271 -0
  6. requipso/docs/macros.py +226 -0
  7. requipso/docs/mkdocs.yml +140 -0
  8. requipso/docs/pages/assets/consort_flowchart.png +0 -0
  9. requipso/docs/pages/assets/demo.gif +0 -0
  10. requipso/docs/pages/blocs/age.md +61 -0
  11. requipso/docs/pages/blocs/ald.md +65 -0
  12. requipso/docs/pages/blocs/biometry.md +98 -0
  13. requipso/docs/pages/blocs/cim10.md +80 -0
  14. requipso/docs/pages/blocs/cisp2.md +59 -0
  15. requipso/docs/pages/blocs/code-postal.md +47 -0
  16. requipso/docs/pages/blocs/consultations.md +65 -0
  17. requipso/docs/pages/blocs/departement.md +50 -0
  18. requipso/docs/pages/blocs/est-vivant.md +44 -0
  19. requipso/docs/pages/blocs/genre.md +46 -0
  20. requipso/docs/pages/blocs/index.md +40 -0
  21. requipso/docs/pages/blocs/insurance.md +55 -0
  22. requipso/docs/pages/blocs/medecin-traitant.md +56 -0
  23. requipso/docs/pages/blocs/paquet-annees.md +70 -0
  24. requipso/docs/pages/blocs/prescription-atc.md +69 -0
  25. requipso/docs/pages/blocs/regex-consultation.md +64 -0
  26. requipso/docs/pages/blocs/regex-nlp.md +107 -0
  27. requipso/docs/pages/blocs/regex-patient-observation.md +81 -0
  28. requipso/docs/pages/blocs/regex-prescription.md +64 -0
  29. requipso/docs/pages/guide/application.md +81 -0
  30. requipso/docs/pages/guide/combiner-blocs.md +61 -0
  31. requipso/docs/pages/guide/demarrage.md +74 -0
  32. requipso/docs/pages/guide/erreurs.md +83 -0
  33. requipso/docs/pages/guide/exemple-complet.md +67 -0
  34. requipso/docs/pages/guide/google-sheet.md +50 -0
  35. requipso/docs/pages/guide/onglet-inclusion.md +91 -0
  36. requipso/docs/pages/guide/onglet-projet.md +48 -0
  37. requipso/docs/pages/guide/onglet-tableau-descriptif.md +124 -0
  38. requipso/docs/pages/guide/parametres.md +162 -0
  39. requipso/docs/pages/index.md +73 -0
  40. requipso/docs/pages/stylesheets/extra.css +3 -0
  41. requipso/docs/pages/technique/ajouter-un-bloc.md +147 -0
  42. requipso/docs/pages/technique/architecture.md +80 -0
  43. requipso/docs/pages/technique/blocs-internes.md +176 -0
  44. requipso/docs/pages/technique/chargement-sheet.md +107 -0
  45. requipso/docs/pages/technique/developpement.md +124 -0
  46. requipso/docs/pages/technique/donnees.md +106 -0
  47. requipso/docs/pages/technique/export-signatures.md +131 -0
  48. requipso/docs/pages/technique/nlp.md +82 -0
  49. requipso/docs/pages/technique/parametres-internes.md +140 -0
  50. requipso/docs/pages/technique/pipeline.md +66 -0
  51. requipso/docs/pages/technique/tableau-descriptif.md +74 -0
  52. requipso/google.py +168 -0
  53. requipso/io.py +95 -0
  54. requipso/notebooks/marimo/run.py +352 -0
  55. requipso/pipeline.py +364 -0
  56. requipso/pipeline_loader.py +572 -0
  57. requipso/pipes/__init__.py +43 -0
  58. requipso/pipes/atcd.py +365 -0
  59. requipso/pipes/base.py +431 -0
  60. requipso/pipes/biometry.py +170 -0
  61. requipso/pipes/consultations.py +117 -0
  62. requipso/pipes/insurance.py +90 -0
  63. requipso/pipes/params.py +283 -0
  64. requipso/pipes/patient.py +377 -0
  65. requipso/pipes/prescription.py +134 -0
  66. requipso/pipes/processors.py +250 -0
  67. requipso/polars.py +24 -0
  68. requipso/resources/pathology/__init__.py +7 -0
  69. requipso/signature_exporter.py +473 -0
  70. requipso/stats.py +130 -0
  71. requipso-0.2.2.dist-info/METADATA +102 -0
  72. requipso-0.2.2.dist-info/RECORD +75 -0
  73. requipso-0.2.2.dist-info/WHEEL +5 -0
  74. requipso-0.2.2.dist-info/entry_points.txt +2 -0
  75. requipso-0.2.2.dist-info/top_level.txt +1 -0
@@ -0,0 +1,106 @@
1
+ # Données et stockage
2
+
3
+ ## La base RED
4
+
5
+ Les données sont un export de la base **RED** : un fichier parquet par table (`patient.parquet`,
6
+ `consultation.parquet`…). Le schéma complet, avec la description de chaque colonne, les valeurs
7
+ possibles des énumérations et des statistiques de remplissage, est disponible via (ce site)[https://dbdocs.io/thomas.petitjean/RED]
8
+
9
+ Les tables utilisées par les blocs actuels :
10
+
11
+ | Table | Contenu | Blocs |
12
+ | --- | --- | --- |
13
+ | `patient` | Une ligne par patient : naissance, décès, genre, code postal. | `Age`, `EstVivant`, `Genre`, `Departement`, `CodePostal`, `Biometry` (IMC) |
14
+ | `consultation` | Consultations, motifs, statuts, textes libres. | `Consultations`, `RegexConsultation` |
15
+ | `medical_center` | Centres ipso. | `Consultations` |
16
+ | `health_professional` | Professionnels de santé. | `Consultations` |
17
+ | `regular_doctor_history` | Périodes de médecin traitant (MT / MTR). | `MedecinTraitant` |
18
+ | `biometry` | Mesures biométriques. | `Biometry` |
19
+ | `patient_ald` | Affections de longue durée. | `ALD` |
20
+ | `patient_insurance` | Droits d'assurance maladie. | `Insurance` |
21
+ | `drug_prescription`, `drug_posology` | Prescriptions et posologies. | `PrescriptionATC` |
22
+ | `patient_observation` | Rubriques texte du dossier (antécédents, mode de vie…). | `RegexPatientObservation`, `CIM10`, `CISP2`, `PaquetAnnees` |
23
+ | `patient_condition`, `patient_condition_date` | Pathologies reconnues dans les antécédents et leurs dates. | `CIM10`, `CISP2` |
24
+ | `concept`, `concept_relationship` | Terminologies (CIM10, CISP2, ipso) et correspondances. | `CIM10`, `CISP2` |
25
+ | `smoking` | Tabagisme structuré. | `PaquetAnnees` |
26
+
27
+ Toutes les tables patient-dépendantes ont une colonne `patient_id`.
28
+
29
+ ## `Data`
30
+
31
+ `requipso.data.Data` est le conteneur central, passé de bloc en bloc.
32
+
33
+ ```python
34
+ from requipso import Data
35
+
36
+ data = Data("/chemin/vers/final_data") # ou "s3://bucket/prefix"
37
+ data.patient # pl.DataFrame de la table patient
38
+ data.get_table("consultation")
39
+ ```
40
+
41
+ - À la construction, **toutes** les tables du dossier sont chargées en mémoire
42
+ (`load_data`). `Data(path, empty=True)` charge seulement les schémas (0 ligne), utile pour des tests.
43
+ - `Data(path, patient_ids=serie)` restreint dès le chargement toutes les tables à un sous-ensemble de
44
+ patients (pratique pour développer sur un échantillon).
45
+ - Les tables sont accessibles par attribut (`data.patient`), par index (`data["patient"]`) ou par
46
+ `get_table`.
47
+
48
+ ### Les résultats : `all_results`
49
+
50
+ `data.all_results` est un `defaultdict(dict)` indexé par nom de bloc :
51
+
52
+ ```python
53
+ data.all_results["adultes"]["post"] # une ligne par patient : patient_id, adultes
54
+ data.all_results["adultes"]["dates"] # une ligne par événement : patient_id, adultes, start_date, end_date
55
+ ```
56
+
57
+ | Clé | Contenu | Présent |
58
+ | --- | --- | --- |
59
+ | `"post"` | Valeur finale par patient, après agrégation et `post_func`. Pour un `CombinedBlock`, contient aussi les colonnes des sous-blocs. | Toujours |
60
+ | `"dates"` | Événements datés retenus après `date_sql` (dates converties en `pl.Date`). Dans le pipeline d'inclusion, restreint aux patients ayant franchi l'étape. | Seulement si le bloc a des dates |
61
+
62
+ `data.reset()` vide `all_results` ; l'application l'appelle avant chaque nouveau calcul d'inclusion.
63
+
64
+ ## Entrées / sorties : `io.py`
65
+
66
+ `Data` délègue la lecture à un `BaseIO`, choisi selon le chemin :
67
+
68
+ | Classe | Chemin | Remarques |
69
+ | --- | --- | --- |
70
+ | `LocalIO` | Dossier local | Liste `*.parquet` du dossier. |
71
+ | `S3IO` | `s3://bucket/prefix` | Utilise `boto3` ; exige `AWS_ACCESS_KEY_ID` et `AWS_SECRET_ACCESS_KEY` dans l'environnement. |
72
+
73
+ Les deux implémentent `list_tables`, `read_table(name, n_rows)` et `write_table(name, df)`.
74
+
75
+ ## Google : `google.py`
76
+
77
+ `GoogleConnector` s'authentifie avec le **compte Google de l'utilisateur** (OAuth), via
78
+ `get_user_credentials()` :
79
+
80
+ - le client OAuth est lu dans `google_oauth_client.json` (à la racine du dépôt, à côté du package
81
+ `requipso`) ;
82
+ - au premier appel, un navigateur s'ouvre pour la connexion ; le jeton obtenu est mis en cache dans
83
+ `~/.config/requipso/google_token.json` et rafraîchi automatiquement ensuite ;
84
+ - on peut aussi passer des identifiants déjà obtenus : `GoogleConnector(credentials=creds)`.
85
+
86
+ L'utilisateur doit avoir accès au dossier Drive Requipso (lecture pour les Sheets, édition pour
87
+ `upload_file`).
88
+
89
+ - `list_sheets()` liste les Google Sheets du dossier Drive Requipso (`folder_id`).
90
+ - `set_spreadsheet(nom)` ouvre une feuille (via `gspread-pandas`).
91
+ - `open_sheet(onglet, header_rows=1)` lit un onglet en `pandas.DataFrame`. Le contenu transite par un
92
+ CSV pour que pandas infère les types de façon homogène (nombres, booléens `TRUE`/`FALSE`) ; les
93
+ cellules vides deviennent `None`.
94
+ - `upload_file(chemin, nom)` dépose ou remplace un fichier dans le dossier Drive et renvoie son URL.
95
+
96
+ !!! warning "Secret"
97
+ `google_oauth_client.json` identifie l'application et peut être versionné : l'écran de
98
+ consentement est « Interne », seuls les comptes `@ipsosante.fr` peuvent s'y connecter. En
99
+ revanche, `google_token.json` donne accès au Drive de l'utilisateur et ne doit jamais être
100
+ partagé.
101
+
102
+ !!! note "Inférence de types par pandas"
103
+ Le passage par CSV a une conséquence visible côté utilisateur : si une colonne ne contient que des
104
+ nombres, pandas la lit en `int`/`float`, et les paramètres de type liste (`MultiStringParam`)
105
+ échouent (`Input should be a valid list`). Voir le
106
+ [guide utilisateur](../guide/parametres.md#value-la-valeur-principale).
@@ -0,0 +1,131 @@
1
+ # Export des signatures de blocs
2
+
3
+ `requipso/signature_exporter.py` inspecte le code pour lister **tous les blocs disponibles** avec
4
+ leur description et leurs paramètres (`scripts/signature_exporter.py` le lance en ligne de commande).
5
+ Il sert à deux choses :
6
+
7
+ - remplir les onglets de référence `🔒 Blocks` et `🔒 Definitions` du Google Sheet template, que
8
+ les utilisateurs consultent pour savoir quels blocs et paramètres utiliser ;
9
+ - alimenter cette documentation : `requipso/docs/macros.py` s'en sert pour générer les fiches résumées et
10
+ les tableaux de paramètres des pages [Blocs](../blocs/index.md).
11
+
12
+ Il n'y a donc rien à maintenir à la main : il suffit que les `Field(description=…)` et la
13
+ `BlockConfig` des blocs soient à jour.
14
+
15
+ ## Quand le lancer
16
+
17
+ Après toute modification visible par les utilisateurs d'un bloc : ajout ou suppression d'un bloc,
18
+ changement de description, de valeur par défaut ou de paramètre spécifique. La documentation, elle,
19
+ se met à jour toute seule au prochain `mkdocs build` / `mkdocs serve`.
20
+
21
+ ## Utilisation
22
+
23
+ ```bash
24
+ uv run python scripts/signature_exporter.py # met à jour le Sheet template
25
+ uv run python scripts/signature_exporter.py --json # idem + affiche le JSON
26
+ uv run python scripts/signature_exporter.py --json --gsheet "" # JSON seul, sans toucher au Sheet
27
+ uv run python scripts/signature_exporter.py --gsheet <ID> # écrit dans une autre feuille
28
+ ```
29
+
30
+ | Option | Effet |
31
+ | --- | --- |
32
+ | `--gsheet ID` | Identifiant de la feuille à mettre à jour (la longue chaîne de l'URL). **Par défaut, `SHEET_ID`** défini en tête du script : le script écrit donc dans le Sheet même sans option. `--gsheet ""` désactive l'écriture. |
33
+ | `--json` | Affiche toutes les signatures en JSON sur la sortie standard. |
34
+ | `--output-dir` | Sans effet actuellement : l'écriture des CSV est commentée dans `main()`. |
35
+
36
+ Dans tous les cas, le script termine en affichant une ligne par bloc découvert :
37
+
38
+ ```text
39
+ requipso.pipes.patient.Departement [patient] -> DepartementParams
40
+ ```
41
+
42
+ L'écriture dans le Sheet utilise le compte Google de l'utilisateur (même connexion que
43
+ l'application, voir [Développement](developpement.md#installation)) : il faut avoir les droits
44
+ d'édition sur la feuille.
45
+
46
+ !!! warning "Les onglets sont effacés puis réécrits"
47
+ `🔒 Blocks` et `🔒 Definitions` sont vidés à chaque exécution. Toute modification manuelle de ces
48
+ onglets est perdue. Ils sont créés s'ils n'existent pas.
49
+
50
+ ## Comment les blocs sont découverts
51
+
52
+ `BlockExporter()` fait toute la découverte à sa construction :
53
+
54
+ 1. Il importe tous les modules de `requipso.pipes` (`pkgutil.walk_packages`). Un module qui ne
55
+ s'importe pas est ignoré avec un message `[warn] Could not import …` : **ses blocs disparaissent
56
+ alors de l'export**, surveillez ce message.
57
+ 2. Il garde les classes qui héritent de `TableBlock` et sont définies dans `requipso.pipes`.
58
+ 3. Pour chacune, il lit :
59
+ - la classe de paramètres, depuis la base générique `TableBlock[XxxParams]` : un bloc qui
60
+ n'hérite pas directement de `TableBlock[…]` n'a donc aucun paramètre spécifique détecté ;
61
+ - `config.description`, `config.block_type` et la présence de `config.date_column` (`has_date`) ;
62
+ - les champs Pydantic de la classe de paramètres, séparés en **communs** (ceux de
63
+ `BlockParams`, avec les valeurs par défaut propres au bloc) et **spécifiques** (tous les
64
+ autres).
65
+ 4. Les signatures sont triées par module puis par nom de bloc.
66
+
67
+ Chaque bloc donne un `BlockSignature` :
68
+
69
+ ```json
70
+ {
71
+ "module": "requipso.pipes.patient",
72
+ "block_name": "Departement",
73
+ "block_type": "patient",
74
+ "params_name": "DepartementParams",
75
+ "params_module": "requipso.pipes.patient",
76
+ "description": "Retourne le département du patient.",
77
+ "common_parameters": {
78
+ "value": {
79
+ "type": "list[str]",
80
+ "default": "[HELP] Département / Départements séparés de '|' / Liste de départements.",
81
+ "description": "[HELP] Département / Départements séparés de '|' / Liste de départements."
82
+ },
83
+ "...": {}
84
+ },
85
+ "specific_parameters": {},
86
+ "has_date": false
87
+ }
88
+ ```
89
+
90
+ Particularités du format :
91
+
92
+ - Pour `value`, le champ `default` contient la **description** du paramètre (l'aide `[HELP] …`),
93
+ pas sa valeur par défaut : c'est ce texte qui s'affiche dans `🔒 Blocks`.
94
+ - Un paramètre obligatoire a `default: null`.
95
+ - Les types sont rendus en texte (`str | None` devient `str`). Les fonctions (`agg_func`,
96
+ `post_func`…) donnent un type peu lisible (`Callable[[<class 'polars.expr.expr.Expr'>], Expr]`).
97
+ - Une valeur par défaut non sérialisable en JSON est remplacée par son `repr`.
98
+
99
+ ## Contenu des onglets générés
100
+
101
+ **`🔒 Blocks`**: une ligne par bloc.
102
+
103
+ | Colonne | Contenu |
104
+ | --- | --- |
105
+ | `block`, `type`, `description` | Nom de la classe, `patient` / `event`, `BlockConfig.description`. |
106
+ | une colonne par paramètre commun | Valeur par défaut du bloc (aide `[HELP]` pour `value`), vide si aucune. |
107
+ | `has_date` | `True` si le bloc fournit des dates (utilisable avec `date_sql`). |
108
+ | `supplementary_params` | Les paramètres spécifiques et leurs valeurs par défaut, en JSON : un modèle à copier dans la colonne `supplementary_params` du Sheet. |
109
+
110
+ **`🔒 Definitions`**: une ligne par couple (bloc, paramètre spécifique), avec `parameter_name`,
111
+ `parameter_type`, `default_value` et `description`.
112
+
113
+ ## Utilisation depuis Python
114
+
115
+ ```python
116
+ from pathlib import Path
117
+
118
+ from requipso.signature_exporter import BlockExporter
119
+
120
+ exporter = BlockExporter()
121
+ for sig in exporter.signatures:
122
+ print(sig.block_name, sig.params_name, sig.has_date)
123
+
124
+ exporter.to_json() # chaîne JSON
125
+ exporter.to_csv(Path("out")) # blocks_common_parameters.csv + blocks_specific_parameters.csv
126
+ exporter.to_gsheet("<spreadsheet_key>") # onglets 🔒 Blocks / 🔒 Definitions
127
+ ```
128
+
129
+ `to_csv` écrit deux fichiers au format proche des onglets, sans les descriptions des paramètres
130
+ spécifiques ni la colonne `supplementary_params`. Les fichiers `blocks_*.csv` présents à la racine du
131
+ dépôt viennent d'anciennes exécutions et ne sont plus à jour.
@@ -0,0 +1,82 @@
1
+ # Traitement du texte : `RegexProcessor`
2
+
3
+ `requipso/pipes/processors.py` regroupe la logique NLP partagée par les blocs texte. Les blocs
4
+ **composent** un `RegexProcessor` (au lieu d'en hériter) :
5
+
6
+ ```python
7
+ class RegexConsultation(TableBlock[RegexConsultationParams]):
8
+ def __init__(self, params, name=None):
9
+ super().__init__(name=name, params=params)
10
+ p = params.get_regex_and_pipe() # {"pattern": ..., "pipe": ...}
11
+ self.processor = RegexProcessor(
12
+ pattern=p["pattern"], qualifiers=params.qualifiers, pipe=p["pipe"]
13
+ )
14
+
15
+ def transform(self, consultation):
16
+ notes = ... # une ligne par document
17
+ return self.processor.process(
18
+ notes, id_column="consultation_id", text_column="consultation_text",
19
+ output_column_name=self.name,
20
+ )
21
+ ```
22
+
23
+ ## Construction du pipeline edsnlp
24
+
25
+ ```mermaid
26
+ flowchart LR
27
+ blank["edsnlp.blank('eds')"] --> sent["eds.sentences()"]
28
+ sent --> norm["eds.normalizer()"]
29
+ norm --> match{"pipe ?"}
30
+ match -->|"oui"| pipe["eds.nom_du_pipe()"]
31
+ match -->|"non"| matcher["eds.matcher(regex, attr='NORM')"]
32
+ pipe --> quals["qualificatifs<br/>eds.negation, eds.hypothesis, ..."]
33
+ matcher --> quals
34
+ ```
35
+
36
+ - **`eds.normalizer`** produit l'attribut `NORM` (minuscules, sans accents, guillemets et espaces
37
+ normalisés). Le `matcher` regex travaille sur `NORM` : un motif accentué ne correspond jamais.
38
+ - **`get_regex_and_pipe`** : si `value` contient une seule entrée `edsnlp.xxx`, le pipeline `xxx` de
39
+ `edsnlp.pipes` est ajouté à la place du matcher ; sinon les valeurs sont combinées en
40
+ `(?i)(v1|v2|…)`.
41
+ - **Qualificatifs** : chaque nom de `qualifiers` est un composant `edsnlp.pipes` ajouté avec une liste
42
+ de terminaisons étendue (`terminations.termination + ["\n-", "\n\t-"]`), pour que les puces de
43
+ liste bornent la portée d'une négation.
44
+
45
+ !!! note "Effet de bord"
46
+ `termination += [...]` modifie en place la liste globale d'edsnlp : elle grossit à chaque
47
+ instanciation d'un `RegexProcessor` (sans conséquence fonctionnelle connue).
48
+
49
+ ## `process(df, ...)`
50
+
51
+ 1. Copie `id_column` et `text_column` dans `note_id` / `note_text` (format OMOP attendu par edsnlp).
52
+ 2. `edsnlp.data.from_polars(df, converter="omop", doc_attributes=["patient_id"])`, puis
53
+ `map_pipeline(nlp)` avec le backend **multiprocessing** et une barre de progression.
54
+ 3. Conversion des entités (`ents`) en dictionnaires, avec les qualificatifs et l'attribut de sortie
55
+ (`lexical_variant` par défaut, ou un attribut personnalisé passé via
56
+ `output_span_attribute_and_dtype`, comme `PA` pour `PaquetAnnees`).
57
+ 4. Écriture en Polars via `LenientPolarsWriter`.
58
+ 5. Si aucune entité n'est trouvée, un DataFrame vide au bon schéma est construit.
59
+ 6. Les entités portant **un** qualificatif vrai sont retirées :
60
+ `ents.filter(~pl.any_horizontal(*qualifiers))`.
61
+ 7. `note_id` est recopié dans `id_column`, l'attribut de sortie dans `output_column_name`, puis
62
+ `.unique()`.
63
+
64
+ Le résultat contient une ligne par entité : `patient_id`, l'identifiant du document, `start`, `end`,
65
+ `label`, les qualificatifs et la colonne de sortie. Les blocs y joignent ensuite leurs dates
66
+ (ex. `RegexConsultation` joint `consultation_start_datetime` / `consultation_end_datetime`).
67
+
68
+ ## `LenientPolarsWriter`
69
+
70
+ Sous-classe de `edsnlp.data.polars.PolarsWriter`. Le writer d'origine lève une erreur si des colonnes
71
+ de `schema_overrides` sont absentes, ce qui arrive quand **aucune entité** n'est trouvée. La version
72
+ tolérante ne valide les `schema_overrides` que si le résultat est non vide.
73
+
74
+ ## Points d'attention pour les contributeurs
75
+
76
+ - Le texte d'un document est construit en Polars : une concaténation avec une colonne `null` donne
77
+ `null`. Remplacez les valeurs manquantes (`fill_null("")`) avant de concaténer, comme le fait
78
+ `RegexConsultation` pour l'observation et la conclusion.
79
+ - Le multiprocessing impose que le code appelant soit importable (`if __name__ == "__main__":` dans les
80
+ scripts).
81
+ - Pour un attribut personnalisé, l'extension spaCy doit être déclarée avant le traitement
82
+ (`Span.set_extension("PA", getter=..., force=True)` dans `PaquetAnnees`).
@@ -0,0 +1,140 @@
1
+ # Les paramètres : `BlockParams`
2
+
3
+ Tout le code est dans `requipso/pipes/params.py` (et `RegexParams` dans `processors.py`).
4
+
5
+ ## Hiérarchie
6
+
7
+ ```mermaid
8
+ classDiagram
9
+ class BlockParams {
10
+ +value: Any
11
+ +agg_func: TransformFunc
12
+ +post_func: TransformFunc
13
+ +date_sql: str
14
+ +reference_date_block: BaseBlock
15
+ +reference_date_sql: str
16
+ }
17
+ BlockParams <|-- NoParams
18
+ BlockParams <|-- StringParam
19
+ BlockParams <|-- NumberParam
20
+ BlockParams <|-- MultiStringParam
21
+ BlockParams <|-- CategoryParam
22
+ BlockParams <|-- CombineOperatorParam
23
+ MultiStringParam <|-- RegexParams
24
+ NoParams <|-- AgeParams
25
+ MultiStringParam <|-- CIM10Params
26
+ StringParam <|-- BiometryParams
27
+ RegexParams <|-- RegexConsultationParams
28
+ ```
29
+
30
+ | Classe | `value` | Usage |
31
+ | --- | --- | --- |
32
+ | `NoParams` | `None` (inutilisée) | Blocs sans valeur principale (`Age`, `Genre`, `Consultations`…). |
33
+ | `StringParam` | `str`, obligatoire | `Biometry`. |
34
+ | `NumberParam` | `int`, obligatoire | Disponible, non utilisé actuellement. |
35
+ | `MultiStringParam` | `list[str]`, défaut `[]` ; accepte `"a|b|c"` | Codes (`CIM10`, `ALD`, `PrescriptionATC`…). Fournit `get_regex(case, prefix, exact)`. |
36
+ | `CategoryParam` | `str` parmi `allowed` | Disponible, non utilisé actuellement. |
37
+ | `CombineOperatorParam` | `None` + `operator` | Hérité, non utilisé par `CombinedBlock`. |
38
+ | `RegexParams` | `list[str]` (motifs ou `edsnlp.<pipe>`) + `qualifiers` | Blocs NLP. |
39
+
40
+ Chaque bloc définit sa propre sous-classe pour **surcharger les valeurs par défaut** (et la
41
+ description du champ `value`, préfixée par `[HELP]` pour l'aide du Sheet) :
42
+
43
+ ```python
44
+ class CIM10Params(MultiStringParam):
45
+ value: list[str] = Field(
46
+ default=[],
47
+ description="[HELP] Code CIM10 / Codes CIM10 séparés de '|' / Liste de codes CIM10",
48
+ )
49
+ agg_func: TransformFunc = Field(default="COUNT(x)", description="Aggregation function.")
50
+ post_func: TransformFunc = Field(default="x>=1", description="Post-transform: True if at least one match.")
51
+ ```
52
+
53
+ Les champs spécifiques (ex. `mtr_only` de `MedecinTraitantParams`) sont de simples champs Pydantic
54
+ supplémentaires ; ils arrivent depuis la colonne `supplementary_params`.
55
+
56
+ ## Configuration Pydantic
57
+
58
+ ```python
59
+ model_config = ConfigDict(
60
+ extra="forbid", # paramètre inconnu => erreur
61
+ arbitrary_types_allowed=True, # reference_date_block est un BaseBlock
62
+ validate_default=True, # les défauts SQL passent aussi par parse_func
63
+ coerce_numbers_to_str=True, # 75011 -> "75011" pour les champs str
64
+ )
65
+ ```
66
+
67
+ ## Coercition des cellules : `_coerce_sheet_values`
68
+
69
+ Validateur `mode="before"` appliqué au dictionnaire brut issu du Sheet :
70
+
71
+ | Entrée | Résultat |
72
+ | --- | --- |
73
+ | `None` ou chaîne vide | Clé **supprimée** : la valeur par défaut du champ s'applique. |
74
+ | Chaîne commençant par `[` ou `{` | Parsée avec `json.loads`, puis `json.loads` après remplacement `'` → `"`, puis `ast.literal_eval`. Sinon laissée telle quelle. |
75
+ | `"true"` / `"false"` (toute casse) | Booléen. |
76
+ | Autre chaîne | Débarrassée des espaces de bord. |
77
+ | Non-chaîne (nombre, booléen) | Inchangée. |
78
+
79
+ Conséquence : **une cellule vide ne peut pas annuler un défaut** (ex. supprimer le `COUNT(x)` par
80
+ défaut d'un bloc).
81
+
82
+ ## Expressions SQL utilisateur
83
+
84
+ ### `agg_func` / `post_func` → `TransformFunc`
85
+
86
+ `parse_func` (validateur `before`) accepte une chaîne SQL ou un callable :
87
+
88
+ 1. la chaîne est validée immédiatement par `pl.sql_expr(func)` ;
89
+ 2. elle est enveloppée dans `partial(sql_to_polars_expr, sql=func)`, un callable `pl.Expr -> pl.Expr`.
90
+
91
+ `sql_to_polars_expr(col, sql)` :
92
+
93
+ ```python
94
+ expression = parse_one(sql.replace('"', "'")) # sqlglot
95
+ expression = expression.transform( # x -> nom réel de la colonne
96
+ lambda node: exp.column(col.meta.output_name())
97
+ if isinstance(node, exp.Column) and node.name == "x" else node
98
+ )
99
+ return pl.sql_expr(expression.sql())
100
+ ```
101
+
102
+ - Les guillemets doubles sont convertis en simples : `"féminin"` est un littéral, pas un identifiant.
103
+ - Seule la colonne `x` est réécrite. Les autres identifiants sont laissés tels quels et résolus par
104
+ Polars dans le contexte d'évaluation.
105
+
106
+ Côté code, on peut aussi passer directement un callable :
107
+
108
+ ```python
109
+ AgeParams(post_func=lambda x: x.is_between(18, 65))
110
+ ```
111
+
112
+ ### `date_sql` / `reference_date_sql`
113
+
114
+ Validées par `validate_date_sql` : la chaîne doit contenir `start_date` ou `end_date` et être
115
+ acceptée par `pl.sql_expr`. Elles restent des chaînes et sont évaluées dans `filter_date`
116
+ (`df.filter(pl.sql_expr(date_sql))`) et `set_reference_date`
117
+ (`.agg(pl.sql_expr(reference_date_sql))`).
118
+
119
+ ## `MultiStringParam.get_regex`
120
+
121
+ Construit un motif à partir de la liste `value` :
122
+
123
+ | Appel | Motif pour `["E11", "E10"]` | Utilisé par |
124
+ | --- | --- | --- |
125
+ | `get_regex(prefix=True)` | `^(?:E11|E10)` | `CIM10`, `CISP2`, `PrescriptionATC` |
126
+ | `get_regex(exact=True)` | `^(E11|E10)$` | `ALD` |
127
+ | `get_regex()` | `(E11|E10)` | |
128
+ | `get_regex(case=False)` | `(?i)(E11|E10)` | `RegexParams.get_regex_and_pipe` |
129
+
130
+ Les valeurs ne sont **pas échappées** : ce sont des expressions régulières (d'où `30.*` pour l'ALD).
131
+
132
+ ## Validateurs spécifiques
133
+
134
+ | Classe | Validateur | Effet |
135
+ | --- | --- | --- |
136
+ | `MultiStringParam` | `parse_pipe_separated` | `"a|b"` → `["a", "b"]`. |
137
+ | `ALDParams` | `pad_with_zeros` | `8` → `08`, `6.1` → `06.1`. |
138
+ | `RegexParams` | `check_if_value_is_edsnlp_pipe` | Si une seule valeur `edsnlp.xxx`, vérifie que `xxx` existe dans `edsnlp.pipes`. |
139
+ | `RegexPatientObservationParams` | `parse_patient_observation_label` | Une chaîne seule → liste. |
140
+ | `CategoryParam` | `validate_choice` | `value` doit être dans `allowed`. |
@@ -0,0 +1,66 @@
1
+ # Le pipeline d'inclusion
2
+
3
+ `requipso/pipeline.py` contient `Pipeline`, le graphe des étapes d'inclusion, et
4
+ `dag_to_consort_flowchart`, qui le dessine.
5
+
6
+ ## Construction : `add_step`
7
+
8
+ `Pipeline` stocke les étapes dans un `networkx.DiGraph` dont les nœuds sont les **objets blocs**.
9
+
10
+ ```python
11
+ pipeline = Pipeline(reference_date=datetime.datetime(2024, 12, 31))
12
+ pipeline.add_step(EstVivant(), text="Patients vivants", excluded_text="Décédés")
13
+ pipeline.add_step(Age(), text="Patients majeurs", excluded_text="Mineurs") # parent implicite
14
+ pipeline.add_step(Genre(), text="Femmes", parent_step="Age") # parent explicite
15
+ ```
16
+
17
+ | Règle | Détail |
18
+ | --- | --- |
19
+ | Première étape | Devient `source_step` ; un `parent_step` est interdit. |
20
+ | `parent_step=None` | Parent = `last_addded_step`, la dernière étape **ajoutée**. |
21
+ | `parent_step` en chaîne | Résolu via `steps_names` ; doit exister. |
22
+ | Noms | Uniques (`Step … already exists`). |
23
+
24
+ Les attributs de nœud `text`, `excluded_text` et, après exécution, `n` servent au dessin.
25
+
26
+ ## Exécution : `iter_run`
27
+
28
+ ```python
29
+ for step_name, n in pipeline.iter_run(data):
30
+ print(step_name, n)
31
+ ```
32
+
33
+ - Parcours en **profondeur** (`nx.dfs_preorder_nodes`) depuis `source_step` : un parent est toujours
34
+ exécuté avant ses enfants.
35
+ - Pour chaque étape, `input_patients` = patients pour lesquels la colonne du parent est vraie dans
36
+ `all_results[parent]["post"]` (ou `None`, c'est-à-dire tous les patients, pour la racine).
37
+ - `step.execute(data, patient_ids=input_patients, reference_date=self.reference_date)`.
38
+ - `output_patients` = patients pour lesquels la colonne de l'étape est vraie (`null` → exclu).
39
+ - Si l'étape a des dates, `all_results[step]["dates"]` est restreint aux `output_patients` : les
40
+ références de date ultérieures ne voient que les patients inclus.
41
+ - `n` est stocké sur le nœud ; `initial_n` (boîte « Patients ») = nombre de patients de la base.
42
+
43
+ `iter_run` est un générateur pour que l'application puisse afficher une barre de progression ;
44
+ `run(data)` le consomme entièrement.
45
+
46
+ !!! note "Sortie booléenne"
47
+ `iter_run` contient un contrôle de type de sortie (`OutputType.BOOLEAN`) qui n'est pas encore
48
+ branché sur le bloc : une étape non booléenne échoue au moment du `filter(pl.col(name))`.
49
+
50
+ ## Dessin : `dag_to_consort_flowchart`
51
+
52
+ `Pipeline.graph(save_name)` appelle `dag_to_consort_flowchart` et rend un PNG `save_name.png` avec
53
+ Graphviz.
54
+
55
+ Mise en page de type CONSORT :
56
+
57
+ - une colonne principale de haut en bas (`rankdir=TB`, arêtes orthogonales) ;
58
+ - un nœud virtuel `_source` (« Patients (n=…) ») au-dessus de la racine ;
59
+ - pour une étape avec `excluded_text`, un point invisible `_mid_<id>` est inséré sur l'arête entrante,
60
+ et une boîte pointillée `_exc_<id>` (« Excluded … (n=parent − enfant) ») est placée au même rang ;
61
+ - plusieurs enfants d'un même parent sont placés côte à côte (`rank=same`).
62
+
63
+ ![Exemple de flowchart](../assets/consort_flowchart.png){ width="420" }
64
+
65
+ La fonction est indépendante de Requipso : elle accepte n'importe quel `nx.DiGraph` acyclique dont
66
+ les nœuds ont des attributs `text`, `n` et `excluded_text`.
@@ -0,0 +1,74 @@
1
+ # Le tableau descriptif
2
+
3
+ `requipso/descriptive_pipeline.py` (orchestration et upload) et `requipso/stats.py` (statistiques).
4
+
5
+ ## `DescriptivePipeline`
6
+
7
+ ```python
8
+ descriptive = DescriptivePipeline(
9
+ data=data, # data sur laquelle l'inclusion a déjà tourné
10
+ inclusion_pipeline=inclusion,
11
+ populations=["adultes", "diabete"],
12
+ google_connector=connector,
13
+ )
14
+ descriptive.add_row(step=Age(params=AgeParams(post_func="x")), variable_type="numerical", subsets=[18, 65])
15
+ df = descriptive.run(data) # run_iter + format_stats + upload_stats
16
+ ```
17
+
18
+ À la construction :
19
+
20
+ - chaque population doit être une étape de l'inclusion ;
21
+ - `self.populations[nom]` = patients pour lesquels `all_results[nom]["post"]` est vrai ;
22
+ - `self.patient_ids` = union de toutes les populations.
23
+
24
+ `add_row` refuse un bloc dont le nom est déjà une étape d'inclusion (les résultats s'écraseraient
25
+ dans `all_results`).
26
+
27
+ ## `run_iter`
28
+
29
+ 1. Ligne **Total** : effectif de chaque population, et pourcentage par rapport à la **première**
30
+ population.
31
+ 2. Pour chaque variable :
32
+ - `step.execute(data, patient_ids=self.patient_ids, reference_date=self.reference_date)` : le bloc
33
+ est calculé **une seule fois** sur l'union des populations ;
34
+ - contrôle de cohérence entre `variable_type` et le dtype de la colonne (`numerical` → numérique,
35
+ `boolean` → `pl.Boolean`) ;
36
+ - pour chaque population : jointure interne sur ses patients, puis `compute_stats`.
37
+ 3. Le générateur renvoie les statistiques de chaque variable (barre de progression de l'application).
38
+
39
+ ## Statistiques : `stats.py`
40
+
41
+ Chaque fonction renvoie un DataFrame **d'une ligne**, une colonne par statistique formatée.
42
+
43
+ | Fonction | `variable_type` | Colonnes |
44
+ | --- | --- | --- |
45
+ | `compute_stats_boolean` | `boolean` | `(n, %)` (somme des vrais / effectif), `missing (n, %)` (nulls). |
46
+ | `compute_stats_quantitative` | `numerical` | `(mean ± std)`, `(median, IQR)`, `missing (n, %)` (null ou NaN), puis `[a - b[ (n, %)` par classe. |
47
+ | `compute_stats_categories` | `categorical` | `missing (n, %)`, puis une colonne par catégorie ou groupe de catégories. |
48
+
49
+ Détails :
50
+
51
+ - les arrondis sont à 2 décimales (`n_digits`) ;
52
+ - les pourcentages ont pour dénominateur l'effectif de la population (nulls compris) ;
53
+ - `subsets` numériques : bornes inférieures, la dernière classe est ouverte (`a+`) ;
54
+ - `subsets` catégoriels : chaque élément est une catégorie ou une liste de catégories regroupées
55
+ (affichée `(a, b)`) ; sans `subsets`, une colonne par valeur distincte ;
56
+ - pour `categorical`, `missing` est calculé sur une colonne constante : il vaut toujours 0
57
+ (limite connue).
58
+
59
+ ## Mise en forme : `format_stats`
60
+
61
+ Chaque DataFrame de statistiques (une ligne, N colonnes) est **transposé** en N lignes ; les
62
+ populations sont jointes côte à côte sur le nom de la statistique ; une ligne d'en-tête contenant le
63
+ nom du bloc est insérée avant chaque variable. Le résultat est un `pandas.DataFrame` dont la première
64
+ colonne (sans nom) contient les libellés.
65
+
66
+ ## Upload : `upload_stats`
67
+
68
+ 1. Vide entièrement l'onglet `🔒 Results` (`updateCells` avec `fields="*"`, ce qui supprime aussi le
69
+ formatage).
70
+ 2. Écrit le DataFrame à partir de A1 (`gspread_pandas.Spread.df_to_sheet`).
71
+ 3. Applique la mise en forme avec `gspread_formatting` : texte centré, en-tête en gras, lignes de
72
+ titre de variable (toutes les cellules vides hors libellé) en gras sur fond bleu.
73
+
74
+ L'onglet `🔒 Results` doit exister dans la feuille (il est fourni par le template).