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,147 @@
1
+ # Ajouter un bloc
2
+
3
+ Ce tutoriel ajoute un bloc `Acte` qui recherche des **actes cotés** (table `act`) par code, datés par
4
+ leur consultation.
5
+
6
+ ## 1. Choisir le fichier
7
+
8
+ Les blocs sont rangés par domaine dans `requipso/pipes/` (`patient.py`, `atcd.py`, `biometry.py`…).
9
+ Créez un nouveau module si aucun ne convient, ici `requipso/pipes/act.py`. **Aucun enregistrement
10
+ n'est nécessaire** : tout module de `requipso.pipes` est parcouru par `build_block_registry`.
11
+
12
+ ## 2. Écrire la classe de paramètres
13
+
14
+ Partez de la classe de base la plus proche (voir [Paramètres](parametres-internes.md)) et surchargez les
15
+ défauts adaptés au cas « au moins un événement » de l'onglet `Inclusion` :
16
+
17
+ ```python
18
+ from pydantic import Field
19
+
20
+ from .params import MultiStringParam, TransformFunc
21
+
22
+
23
+ class ActeParams(MultiStringParam):
24
+ value: list[str] = Field(
25
+ default=[],
26
+ description="[HELP] Code d'acte / Codes séparés de '|' / Liste de codes (ex. 'JKHD001').",
27
+ )
28
+ agg_func: TransformFunc = Field(default="COUNT(x)", description="Aggregation: count acts.")
29
+ post_func: TransformFunc = Field(default="x>=1", description="Post-transform: True if at least one act.")
30
+ include_mtr_package: bool = Field(
31
+ default=True, description="If False, drop acts included in the MTR package."
32
+ )
33
+ ```
34
+
35
+ - La description de `value` commence par `[HELP]` : c'est l'aide affichée dans `🔒 Blocks`.
36
+ - Les champs supplémentaires (`include_mtr_package`) deviennent des clés de `supplementary_params`.
37
+ - `extra="forbid"` est hérité : une clé inconnue dans le Sheet lèvera une erreur explicite.
38
+
39
+ ## 3. Écrire le bloc
40
+
41
+ ```python
42
+ import polars as pl
43
+
44
+ from .base import BlockConfig, OutputType, TableBlock
45
+
46
+
47
+ class Acte(TableBlock[ActeParams]):
48
+ config = BlockConfig(
49
+ output_type=OutputType.CATEGORY,
50
+ block_type="event",
51
+ date_column=("consultation_start_datetime", "consultation_end_datetime"),
52
+ description="Retourne les actes cotés du patient dont le code commence par les codes spécifiés.",
53
+ )
54
+
55
+ def transform( # type: ignore[override]
56
+ self,
57
+ act: pl.DataFrame,
58
+ consultation: pl.DataFrame,
59
+ ) -> pl.DataFrame:
60
+ acts = act.filter(pl.col("act_value").str.contains(self.params.get_regex(prefix=True)))
61
+ if not self.params.include_mtr_package:
62
+ acts = acts.filter(~pl.col("act_is_in_mtr_package"))
63
+
64
+ return acts.join(
65
+ consultation.select(
66
+ "consultation_id", self.start_date_column, self.end_date_column
67
+ ),
68
+ on="consultation_id",
69
+ how="inner",
70
+ ).select(
71
+ "patient_id",
72
+ pl.col("act_value").alias(self.name),
73
+ self.start_date_column,
74
+ self.end_date_column,
75
+ )
76
+ ```
77
+
78
+ Le contrat de `transform` :
79
+
80
+ | Règle | Pourquoi |
81
+ | --- | --- |
82
+ | Les **noms des arguments** sont des noms de tables RED (`act`, `consultation`). | `execute` charge les tables d'après la signature et les filtre sur les patients d'entrée. |
83
+ | Renvoyer `patient_id` et une colonne **`self.name`** (la valeur `x`). | Agrégation, `post_func` et résultats travaillent sur cette colonne. |
84
+ | Renvoyer les colonnes de `config.date_column`. | `execute` les copie dans `start_date` / `end_date`. |
85
+ | Ne pas agréger, ne pas filtrer sur les dates, ne pas rajouter les patients manquants. | C'est le rôle de `execute`, piloté par `agg_func`, `date_sql` et la jointure finale. |
86
+ | Utiliser `self.reference_date` si le calcul dépend de la date de référence. | Il est résolu avant l'appel (voir `Age`). |
87
+
88
+ Si le bloc a besoin d'un traitement NLP, composez un [`RegexProcessor`](nlp.md) dans `__init__`.
89
+
90
+ ## 4. Vérifier que le bloc est découvert
91
+
92
+ ```bash
93
+ uv run python -c "from requipso.pipeline_loader import build_block_registry; print(sorted(build_block_registry()))"
94
+ ```
95
+
96
+ `Acte` doit apparaître. Sinon, le module a probablement une erreur d'import (elle est ignorée en
97
+ silence par le registre) : importez-le directement pour voir l'erreur.
98
+
99
+ ## 5. Tester sur les données
100
+
101
+ ```python
102
+ import datetime
103
+ from requipso import Data
104
+ from requipso.pipes.act import Acte, ActeParams
105
+
106
+ data = Data("/chemin/vers/final_data")
107
+ block = Acte(name="frottis", params=ActeParams(value="JKHD001", date_sql="start_date <= reference_date"))
108
+ block.execute(data, reference_date=datetime.datetime(2024, 12, 31))
109
+
110
+ data.all_results["frottis"]["post"] # une ligne par patient
111
+ data.all_results["frottis"]["dates"] # les actes retenus
112
+ ```
113
+
114
+ ## 6. Mettre à jour les onglets de référence du Sheet
115
+
116
+ Les onglets `🔒 Blocks` et `🔒 Definitions` du template sont générés depuis le code :
117
+
118
+ ```bash
119
+ uv run python scripts/signature_exporter.py # écrit dans le Sheet de référence (SHEET_ID)
120
+ uv run python scripts/signature_exporter.py --json # affiche aussi les signatures en JSON
121
+ ```
122
+
123
+ Voir [Export des signatures de blocs](export-signatures.md) pour le détail.
124
+
125
+ ## 7. Documenter le bloc
126
+
127
+ 1. Créez `requipso/docs/pages/blocs/acte.md` en suivant le plan des autres fiches, avec les macros :
128
+
129
+ {% raw %}
130
+ ```markdown
131
+ # `Acte` : actes cotés
132
+
133
+ {{ bloc_resume("Acte") }}
134
+
135
+ ## Paramètres
136
+
137
+ {{ bloc_parametres("Acte") }}
138
+ ```
139
+ {% endraw %}
140
+
141
+ 2. Ajoutez la page dans `nav` de `requipso/docs/mkdocs.yml`.
142
+ 3. Ajoutez le bloc dans `FAMILIES` et `PAGES` de `requipso/docs/macros.py` (sinon il apparaît dans une
143
+ famille « Autres », sans lien, dans le catalogue).
144
+ 4. Vérifiez avec `uv run mkdocs build -f requipso/docs/mkdocs.yml --strict`.
145
+
146
+ Les tableaux de paramètres et la fiche résumée sont générés : ils restent à jour tant que les
147
+ descriptions des `Field` et de `BlockConfig` le sont.
@@ -0,0 +1,80 @@
1
+ # Architecture
2
+
3
+ Cette section s'adresse aux contributeurs. Elle décrit comment une définition d'étude dans un Google
4
+ Sheet devient un flowchart et un tableau descriptif.
5
+
6
+ ## Vue d'ensemble
7
+
8
+ ```mermaid
9
+ flowchart TB
10
+ subgraph google [Google]
11
+ sheet["Google Sheet<br/>Project / Inclusion / Descriptive_table"]
12
+ results["Onglet 🔒 Results"]
13
+ drive["Drive : flowchart PNG"]
14
+ end
15
+
16
+ subgraph app [Application marimo : notebooks/marimo/run.py]
17
+ connector["GoogleConnector<br/>(google.py)"]
18
+ builder["PipelineBuilder<br/>(pipeline_loader.py)"]
19
+ inclusion["Pipeline<br/>(pipeline.py)"]
20
+ descriptive["DescriptivePipeline<br/>(descriptive_pipeline.py)"]
21
+ end
22
+
23
+ parquet[("Fichiers parquet RED")] --> dataObj["Data<br/>(data.py, io.py)"]
24
+
25
+ sheet --> connector --> builder
26
+ builder -->|"build()"| inclusion
27
+ builder -->|"build_descriptive()"| descriptive
28
+ dataObj --> inclusion
29
+ inclusion -->|"data.all_results"| descriptive
30
+ inclusion -->|"graph()"| drive
31
+ descriptive -->|"upload_stats()"| results
32
+ ```
33
+
34
+ Le déroulé d'un clic sur **« (re)lancer la pipeline »** :
35
+
36
+ 1. `GoogleConnector.set_spreadsheet(nom)` ouvre la feuille choisie.
37
+ 2. `PipelineBuilder(connector).build()` lit les onglets `Inclusion` et `Project`, instancie un bloc
38
+ par groupe de lignes et les ajoute à un `Pipeline` (un graphe orienté).
39
+ 3. `Pipeline.iter_run(data)` exécute les étapes dans l'ordre du graphe ; chaque bloc écrit ses
40
+ résultats dans `data.all_results`.
41
+ 4. `Pipeline.graph("graph")` dessine le flowchart (Graphviz), puis `GoogleConnector.upload_file`
42
+ le dépose sur le Drive.
43
+ 5. `PipelineBuilder.build_descriptive(data, inclusion)` lit `Descriptive_table` et les populations ;
44
+ `DescriptivePipeline.run_iter(data)` calcule chaque variable pour chaque population.
45
+ 6. `format_stats` met en forme le tableau, `upload_stats` l'écrit dans `🔒 Results`.
46
+
47
+ ## Carte des modules
48
+
49
+ | Module | Rôle |
50
+ | --- | --- |
51
+ | `requipso/cli.py` | Point d'entrée `requipso` : lance `marimo run` sur l'application. |
52
+ | `requipso/notebooks/marimo/run.py` | L'application marimo (interface utilisateur). |
53
+ | `requipso/data.py` | `Data` : charge toutes les tables, stocke les résultats des blocs. |
54
+ | `requipso/io.py` | `LocalIO` / `S3IO` : lecture et écriture des tables parquet. |
55
+ | `requipso/google.py` | `GoogleConnector` : authentification avec le compte Google de l'utilisateur, Drive, Sheets. |
56
+ | `requipso/pipeline_loader.py` | `PipelineBuilder` : traduit les onglets du Sheet en objets Python. |
57
+ | `requipso/pipeline.py` | `Pipeline` (graphe d'étapes) et `dag_to_consort_flowchart`. |
58
+ | `requipso/descriptive_pipeline.py` | `DescriptivePipeline` : tableau descriptif et upload. |
59
+ | `requipso/stats.py` | Statistiques booléennes, catégorielles et quantitatives. |
60
+ | `requipso/pipes/base.py` | Hiérarchie des blocs : `BaseBlock`, `TableBlock`, `CombinedBlock`. |
61
+ | `requipso/pipes/params.py` | Modèles Pydantic des paramètres (`BlockParams` et dérivés). |
62
+ | `requipso/pipes/processors.py` | `RegexProcessor` (edsnlp) et `RegexParams`. |
63
+ | `requipso/pipes/{patient,atcd,biometry,consultations,insurance,prescription}.py` | Les blocs concrets. |
64
+ | `requipso/polars.py` | Namespace Polars `df.ipso` (post-traitements utilitaires). |
65
+ | `requipso/completer.py` | Complétion IPython des noms de colonnes dans `pl.col("…")`. |
66
+ | `requipso/signature_exporter.py` | Exporte la signature des blocs vers les onglets `🔒 Blocks` / `🔒 Definitions` ([détail](export-signatures.md)). `scripts/signature_exporter.py` le lance en ligne de commande. |
67
+ | `requipso/docs/` | Cette documentation (`mkdocs.yml`, pages, `macros.py` qui génère les tableaux de paramètres). |
68
+
69
+ ## Principes de conception
70
+
71
+ - **Le Google Sheet est l'interface.** Toute la configuration utilisateur passe par des cellules :
72
+ les paramètres sont des chaînes (SQL, listes `a|b`, JSON) validées et converties par Pydantic.
73
+ - **Un bloc = une classe.** Les blocs sont découverts automatiquement par introspection
74
+ (`build_block_registry`) : ajouter une classe dans `requipso/pipes/` suffit à la rendre disponible.
75
+ - **Les tables nécessaires sont déduites de la signature.** Les noms des arguments de
76
+ `transform(self, patient, biometry)` sont les noms des tables à charger.
77
+ - **Tout est Polars.** Les tables sont des `pl.DataFrame` en mémoire ; les expressions utilisateur
78
+ (`agg_func`, `post_func`, `date_sql`) sont converties en expressions Polars via `pl.sql_expr`.
79
+ - **Les résultats sont partagés.** Chaque bloc écrit dans `data.all_results[nom]` ; les étapes
80
+ suivantes, les références de dates et le tableau descriptif y lisent.
@@ -0,0 +1,176 @@
1
+ # Les blocs : fonctionnement interne
2
+
3
+ Tout le code est dans `requipso/pipes/base.py`.
4
+
5
+ ## Hiérarchie
6
+
7
+ ```mermaid
8
+ classDiagram
9
+ class BaseBlock {
10
+ <<abstract>>
11
+ +name: str
12
+ +has_date: bool
13
+ +execute(data, reference_date, patient_ids) Data
14
+ }
15
+ class TableBlock~ParamsT~ {
16
+ <<abstract>>
17
+ +config: BlockConfig
18
+ +params: ParamsT
19
+ +reference_date: DataFrame
20
+ +transform(**tables) DataFrame
21
+ +get_tables()
22
+ +set_reference_date()
23
+ +filter_date()
24
+ }
25
+ class CombinedBlock {
26
+ +blocks: list~BaseBlock~
27
+ +operator: list
28
+ +expose_date_for_future_references: list~bool~
29
+ }
30
+ class BlockConfig {
31
+ +output_type: OutputType
32
+ +block_type: patient or event
33
+ +date_column: str or tuple or None
34
+ +description: str
35
+ }
36
+ BaseBlock <|-- TableBlock
37
+ BaseBlock <|-- CombinedBlock
38
+ TableBlock --> BlockConfig
39
+ CombinedBlock o-- BaseBlock
40
+ TableBlock <|-- Age
41
+ TableBlock <|-- CIM10
42
+ TableBlock <|-- Consultations
43
+ ```
44
+
45
+ - **`BaseBlock`** définit l'interface commune : `execute(data, reference_date, patient_ids) -> Data`.
46
+ Pipelines et `CombinedBlock` ne manipulent que cette interface.
47
+ - **`TableBlock[ParamsT]`** est la base des blocs concrets, qui lisent des tables brutes. Il est
48
+ générique sur sa classe de paramètres : `class Age(TableBlock[AgeParams])`. C'est ce paramètre
49
+ générique que lisent `PipelineBuilder` et `signature_exporter` pour savoir quels paramètres
50
+ instancier.
51
+ - **`CombinedBlock`** compose plusieurs blocs booléens avec `AND` / `OR`. Il peut contenir d'autres
52
+ `CombinedBlock`.
53
+
54
+ ## `BlockConfig`
55
+
56
+ Chaque bloc concret déclare un attribut de classe `config` :
57
+
58
+ ```python
59
+ class Age(TableBlock[AgeParams]):
60
+ config = BlockConfig(
61
+ output_type=OutputType.NUMBER,
62
+ block_type="patient",
63
+ date_column="patient_birth_date",
64
+ description="Retourne l'âge du patient en années au moment de la référence.",
65
+ )
66
+ ```
67
+
68
+ | Champ | Rôle |
69
+ | --- | --- |
70
+ | `output_type` | Type de la valeur produite par `transform` (`BOOLEAN`, `NUMBER`, `STRING`, `CATEGORY`). Documentaire aujourd'hui : il n'est pas vérifié à l'exécution. |
71
+ | `block_type` | `"patient"` (une ligne par patient) ou `"event"` (plusieurs lignes, à agréger). Documentaire. |
72
+ | `date_column` | `None` (pas de date), un nom de colonne (date ponctuelle : début = fin) ou un tuple `(début, fin)`. Active `has_date`, le filtrage `date_sql` et le stockage des dates. |
73
+ | `description` | Affichée dans `🔒 Blocks` et dans cette documentation. **En français, destinée aux utilisateurs.** |
74
+
75
+ ## Cycle d'exécution de `TableBlock.execute`
76
+
77
+ ```mermaid
78
+ sequenceDiagram
79
+ participant P as Pipeline
80
+ participant B as TableBlock
81
+ participant D as Data
82
+ P->>B: execute(data, reference_date, patient_ids)
83
+ B->>B: noms des tables = arguments de transform()
84
+ B->>D: get_tables(noms, patient_ids)
85
+ B->>B: set_reference_date(data, reference_date)
86
+ B->>B: df = transform(**tables)
87
+ B->>B: ajoute start_date / end_date (end_date vide = aujourd'hui)
88
+ alt has_date
89
+ B->>B: filter_date(df) avec date_sql
90
+ B->>B: tri par patient_id, date
91
+ B->>D: all_results[name]["dates"] = df
92
+ end
93
+ opt agg_func
94
+ B->>B: group_by(patient_id).agg(agg_func(x))
95
+ end
96
+ B->>B: jointure gauche avec tous les patients d'entrée
97
+ opt post_func
98
+ B->>B: post_func(x)
99
+ end
100
+ B->>D: all_results[name]["post"] = df
101
+ B-->>P: data
102
+ ```
103
+
104
+ Points importants :
105
+
106
+ 1. **Les tables sont déduites de la signature.** `inspect.signature(self.transform)` donne les noms
107
+ des arguments, qui sont les noms des tables. Elles sont filtrées sur `patient_ids` (les patients
108
+ retenus par l'étape parente) si elles ont une colonne `patient_id`.
109
+ 2. **`transform` renvoie** un DataFrame contenant au moins `patient_id` et une colonne nommée
110
+ `self.name` (la valeur `x`), plus les colonnes de date déclarées dans `config.date_column`.
111
+ 3. **Les dates** sont recopiées dans `start_date` / `end_date`. Une `end_date` vide est remplacée par
112
+ la date du jour (événement en cours).
113
+ 4. **`filter_date`** joint la date de référence par patient (`reference_date`) puis applique
114
+ `pl.sql_expr(date_sql)`. Si les dates portent un fuseau horaire, `reference_date` est aligné dessus.
115
+ Sans `has_date`, `date_sql` n'est jamais évalué.
116
+ 5. **Le tri** par `patient_id` puis date de début garantit le sens de `FIRST(x)` / `LAST(x)`.
117
+ 6. **L'agrégation** n'a lieu que si `agg_func` est défini : `group_by("patient_id").agg(agg_func(pl.col(name)))`.
118
+ 7. **La jointure gauche** sur la liste des patients d'entrée (ou tous les patients) garantit une ligne
119
+ par patient ; les patients sans ligne ont `null`.
120
+ 8. **`post_func`** est appliqué colonne entière, nulls compris.
121
+
122
+ ## Résolution de la date de référence
123
+
124
+ `set_reference_date` fixe `self.reference_date`, un DataFrame `(patient_id, reference_date)` :
125
+
126
+ ```mermaid
127
+ flowchart TD
128
+ start{"params.reference_date_block<br/>défini ?"}
129
+ start -->|oui| ref["all_results[bloc]['dates']<br/>group_by(patient_id)<br/>.agg(reference_date_sql)"]
130
+ start -->|non| kind{"type de reference_date"}
131
+ kind -->|datetime| lit["même date pour tous<br/>les patients de data.patient"]
132
+ kind -->|DataFrame| df["DataFrame fourni<br/>(1 ligne par patient)"]
133
+ kind -->|None| none["pas de date de référence"]
134
+ ```
135
+
136
+ - `reference_date_sql` vaut `MIN(start_date)` par défaut ; c'est une **agrégation** SQL évaluée par
137
+ patient sur les dates du bloc référencé.
138
+ - Les patients absents du bloc référencé n'ont pas de date de référence : la jointure gauche de
139
+ `filter_date` leur donne `null` et toute comparaison les élimine.
140
+ - Si le bloc référencé n'a pas de dates, `all_results[bloc]["dates"]` n'existe pas : `KeyError`.
141
+
142
+ ## `CombinedBlock`
143
+
144
+ ```python
145
+ CombinedBlock(
146
+ blocks=[CIM10(params=...), CISP2(params=...)],
147
+ operator=["OR"], # len(blocks) - 1, ou une seule chaîne
148
+ name="diabete",
149
+ expose_date_for_future_references=[True, True],
150
+ )
151
+ ```
152
+
153
+ - Le nom par défaut est construit à partir des sous-blocs : `(_A_OR_B)`.
154
+ - `execute` exécute chaque sous-bloc sur les **mêmes** `patient_ids`, puis joint leurs colonnes
155
+ `post` et calcule l'expression **de gauche à droite sans priorité** : `((A op1 B) op2 C)`. Les nulls
156
+ sont remplacés par `False`.
157
+ - `store_intermediate_results=True` (défaut) conserve les colonnes des sous-blocs dans
158
+ `all_results[name]["post"]`.
159
+ - **Dates** : pour chaque sous-bloc daté dont `expose_date_for_future_references` est vrai, ses dates
160
+ (restreintes aux patients pour lesquels il est vrai) sont concaténées dans
161
+ `all_results[name]["dates"]`, et `has_date` du groupe devient vrai.
162
+
163
+ Dans l'onglet du Sheet, les sous-blocs s'appellent `<nom>_0`, `<nom>_1`, … (voir
164
+ [Chargement du Sheet](chargement-sheet.md)).
165
+
166
+ ## Types de valeurs et nulls
167
+
168
+ | Situation | Valeur de `x` |
169
+ | --- | --- |
170
+ | Patient sans aucune ligne après `transform` / `date_sql` | `null` |
171
+ | `COUNT(x)` sur un patient sans ligne | `null` (pas `0` : la jointure gauche a lieu **après** l'agrégation) |
172
+ | `x >= 1` sur `null` | `null` |
173
+ | Étape d'inclusion | `filter(pl.col(name))` : `null` est traité comme `False` |
174
+ | Tableau descriptif booléen | `null` compté en `missing` |
175
+
176
+ C'est la raison des recommandations `COALESCE(x, 0)` du guide utilisateur.
@@ -0,0 +1,107 @@
1
+ # Chargement du Google Sheet
2
+
3
+ Le module `requipso/pipeline_loader.py` traduit les onglets du Sheet en objets Python. Son point
4
+ d'entrée est `PipelineBuilder`.
5
+
6
+ ```python
7
+ from requipso.google import GoogleConnector
8
+ from requipso.pipeline_loader import PipelineBuilder
9
+
10
+ connector = GoogleConnector().set_spreadsheet("Mon étude")
11
+ builder = PipelineBuilder(connector)
12
+
13
+ inclusion = builder.build() # Pipeline
14
+ inclusion.run(data)
15
+ descriptive = builder.build_descriptive(data, inclusion) # DescriptivePipeline
16
+ stats = descriptive.run(data) # calcule, formate et uploade
17
+ ```
18
+
19
+ ## Constantes
20
+
21
+ | Constante | Valeur |
22
+ | --- | --- |
23
+ | `PIPELINE_SHEET_NAME` | `"Inclusion"` |
24
+ | `DESCRIPTIVE_PIPELINE_SHEET_NAME` | `"Descriptive_table"` |
25
+ | `PROJECT_SHEET_NAME` | `"Project"` |
26
+ | `COMMON_PARAM_COLUMNS` | `value`, `agg_func`, `post_func`, `reference_date_block`, `reference_date_sql`, `date_sql` |
27
+
28
+ ## Registre des blocs : `build_block_registry`
29
+
30
+ Au constructeur, `PipelineBuilder` parcourt `requipso.pipes` avec `pkgutil.walk_packages`, importe
31
+ chaque module et retient toutes les sous-classes de `TableBlock` définies dans `requipso.pipes.*` :
32
+
33
+ ```python
34
+ registry = {"Age": Age, "CIM10": CIM10, ...} # clé = nom de la classe
35
+ ```
36
+
37
+ Le nom de la classe **est** la valeur attendue dans la colonne `block_type`. Un module qui échoue à
38
+ l'import est ignoré silencieusement : un bloc absent du registre est souvent le signe d'une erreur
39
+ d'import.
40
+
41
+ ## Regroupement des lignes : `_iter_block_groups`
42
+
43
+ ```mermaid
44
+ flowchart LR
45
+ rows["Lignes de l'onglet<br/>(sans block_type : ignorées)"] --> iter["_iter_block_groups"]
46
+ iter --> g1["groupe 'vivants'<br/>1 ligne"]
47
+ iter --> g2["groupe 'diabete'<br/>3 lignes"]
48
+ g1 --> b1["TableBlock"]
49
+ g2 --> b2["CombinedBlock<br/>diabete_0 OR diabete_1 OR diabete_2"]
50
+ ```
51
+
52
+ - Les lignes sans `block_type` sont retirées (`dropna(subset="block_type")`).
53
+ - Une ligne dont `block_name` est non vide **et différent** du nom courant ouvre un nouveau groupe ;
54
+ sinon elle est rattachée au groupe courant.
55
+ - `_extract_operators` exige un `operator` `AND`/`OR` sur chaque ligne de continuation.
56
+ - `parse_row_groups` (inclusion) lit `parent_step`, `text` et `excluded_text` sur la **première** ligne
57
+ et collecte `expose_date_for_future_references` sur toutes les lignes (booléen exigé sur les lignes
58
+ de continuation).
59
+ - `parse_descriptive_row_groups` lit `variable_type` (validé contre `VARIABLE_TYPE`),
60
+ `variable_description` et `subsets` (parsé par `parse_subsets` : JSON, JSON avec `'`, puis
61
+ `ast.literal_eval`).
62
+
63
+ ## Instanciation : `build_block_from_row`
64
+
65
+ Pour chaque ligne :
66
+
67
+ 1. `block_cls = registry[row.block_type]` (sinon `Unknown block type`).
68
+ 2. `params_cls = extract_params_type(block_cls)` lit l'argument générique de `TableBlock[...]` dans
69
+ `__orig_bases__`. S'il n'y en a pas, le bloc est instancié sans paramètres.
70
+ 3. Les colonnes de `COMMON_PARAM_COLUMNS` non vides sont copiées dans un dictionnaire.
71
+ `reference_date_block` est résolu en **objet bloc** parmi les blocs déjà construits (d'où l'exigence
72
+ qu'il soit défini plus haut).
73
+ 4. `supplementary_params` est parsé par `parse_supplementary_params` (JSON, normalisation des
74
+ guillemets et des clés non quotées, puis `ast.literal_eval` ; `{}` en cas d'échec, avec un
75
+ avertissement dans les logs) et fusionné dans le dictionnaire.
76
+ 5. `params_cls(**params_dict)` valide le tout (voir [Paramètres](parametres-internes.md)), puis
77
+ `block_cls(name=name, params=params)`.
78
+
79
+ `build_block_for_group` renvoie le bloc seul pour un groupe d'une ligne, ou un `CombinedBlock` dont les
80
+ sous-blocs s'appellent `<nom>_<i>`.
81
+
82
+ ## `build()` : le pipeline d'inclusion
83
+
84
+ 1. `parse()` relit l'onglet `Inclusion`.
85
+ 2. `fetch_reference_date()` lit la cellule **B1** de `Project` (`header_rows=0`, donc `iloc[0, 1]`)
86
+ au format `%d/%m/%Y`.
87
+ 3. Pour chaque groupe : construction du bloc, puis
88
+ `pipeline.add_step(block, text=..., excluded_text=..., parent_step=...)`.
89
+
90
+ ## `build_descriptive()` : le tableau descriptif
91
+
92
+ 1. `fetch_populations()` lit la ligne 2 de `Project` : A2 doit valoir `Populations`, les cellules
93
+ suivantes non vides sont les noms de population.
94
+ 2. L'onglet `Descriptive_table` est lu et regroupé.
95
+ 3. `built_blocks` est **initialisé avec les étapes d'inclusion** (`inclusion_pipeline.steps_names`) :
96
+ une variable peut donc utiliser une étape d'inclusion comme `reference_date_block`.
97
+ 4. Chaque groupe est ajouté par `descriptive.add_row(step, variable_type, display_name, subsets)`.
98
+
99
+ ## Le hash du pipeline
100
+
101
+ `fetch_pipeline_df()` calcule `pipeline_hash = pd.util.hash_pandas_object(df).sum()` sur le contenu de
102
+ l'onglet `Inclusion`. L'application le compare à la valeur stockée dans un `mo.state` pour éviter de
103
+ relancer l'inclusion si l'onglet n'a pas changé.
104
+
105
+ !!! note "Limite connue"
106
+ Le hash ne couvre que l'onglet `Inclusion` : un changement de date de référence dans `Project`
107
+ ne déclenche pas de recalcul de l'inclusion dans la même session.
@@ -0,0 +1,124 @@
1
+ # Développement
2
+
3
+ ## Installation
4
+
5
+ Prérequis système : un compilateur C/C++ et Graphviz (pour le flowchart).
6
+
7
+ === "macOS"
8
+
9
+ ```bash
10
+ brew install graphviz
11
+ ```
12
+
13
+ === "Debian / Ubuntu"
14
+
15
+ ```bash
16
+ sudo apt update
17
+ sudo apt install build-essential graphviz
18
+ ```
19
+
20
+ Puis, à la racine du dépôt, avec [uv](https://docs.astral.sh/uv/) :
21
+
22
+ ```bash
23
+ uv sync # Python 3.12, dépendances du projet et outils de documentation
24
+ ```
25
+
26
+ Le groupe `docs` (MkDocs) est installé par défaut (`[tool.uv] default-groups` dans
27
+ `pyproject.toml`).
28
+
29
+ L'accès au Sheet et au Drive se fait avec le compte Google `@ipsosante.fr` de l'utilisateur. Au
30
+ premier lancement, un onglet du navigateur s'ouvre pour se connecter ; le jeton est ensuite conservé
31
+ dans `~/.config/requipso/google_token.json` (le supprimer pour changer de compte). Le fichier
32
+ `google_oauth_client.json` (client OAuth « Desktop » du projet Google Cloud) doit être présent à la
33
+ racine du dépôt.
34
+
35
+ ## Lancer l'application
36
+
37
+ ```bash
38
+ uv run requipso # = marimo run requipso/notebooks/new/marimo/run.py --show-tracebacks
39
+ uv run requipso --port 2718 # les arguments sont transmis à marimo
40
+ ```
41
+
42
+ `requipso` sert aussi cette documentation sur <http://127.0.0.1:8001> (`mkdocs serve` en
43
+ arrière-plan, arrêté avec l'application) et l'ouvre dans un nouvel onglet après quelques secondes.
44
+ Si MkDocs n'est pas installé, l'application démarre seule avec un message.
45
+
46
+ L'application mémorise le dernier dossier de données et la dernière feuille dans
47
+ `requipso/notebooks/marimo/.requipso_last.json` (ignoré par git).
48
+
49
+ ## Notebooks
50
+
51
+ | Fichier | Usage |
52
+ | --- | --- |
53
+ | `requipso/notebooks/marimo/run.py` | L'application utilisateur (lancée par `requipso`). |
54
+
55
+ Pour éditer un notebook marimo :
56
+
57
+ ```bash
58
+ uv run marimo edit requipso/notebooks/marimo/dev.py
59
+ ```
60
+
61
+ `[tool.marimo.runtime] on_cell_change = "autorun"` est configuré dans `pyproject.toml`.
62
+
63
+ Dans IPython / Jupyter, importer `requipso` installe une complétion des noms de colonnes dans
64
+ `pl.col("…")` (`requipso/completer.py`).
65
+
66
+ ## Qualité du code
67
+
68
+ ```bash
69
+ uv run ruff check .
70
+ uv run ruff format .
71
+ uv run mypy requipso
72
+ ```
73
+
74
+ La configuration mypy (`pyproject.toml`) est modérément stricte : `check_untyped_defs`,
75
+ `disallow_incomplete_defs`, `warn_return_any`… Les surcharges de `transform` avec des arguments
76
+ nommés par table portent un `# type: ignore[override]`.
77
+
78
+ ## Documentation
79
+
80
+ La documentation (ce site) est générée avec [MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
81
+
82
+ ```bash
83
+ uv run mkdocs serve -f requipso/docs/mkdocs.yml # http://127.0.0.1:8000, rechargement automatique
84
+ uv run mkdocs build -f requipso/docs/mkdocs.yml --strict # génère site/ et échoue sur tout avertissement
85
+ ```
86
+
87
+ La documentation est dans le paquet (`requipso/docs/`, déclarée en `package-data`) pour que
88
+ `requipso` puisse la servir aussi depuis une installation hors dépôt.
89
+
90
+ | Élément | Emplacement |
91
+ | --- | --- |
92
+ | Configuration et navigation | `requipso/docs/mkdocs.yml` |
93
+ | Pages | `requipso/docs/pages/` (`guide/`, `blocs/`, `technique/`) |
94
+ | Images | `requipso/docs/pages/assets/` |
95
+ | Macros (tableaux générés) | `requipso/docs/macros.py` |
96
+
97
+ `macros.py` réutilise `BlockExporter` de
98
+ [`requipso/signature_exporter.py`](export-signatures.md) et fournit trois macros
99
+ utilisables dans toute page :
100
+
101
+ | Macro | Rendu |
102
+ | --- | --- |
103
+ | `bloc_resume("Nom")` | Encadré « Fiche du bloc » : niveau, type de valeur, dates, chemin du code. |
104
+ | `bloc_parametres("Nom")` | Tableaux des paramètres communs (valeurs par défaut du bloc) et spécifiques. |
105
+ | `blocs_tableau()` | Tableau récapitulatif de tous les blocs, par famille. |
106
+
107
+ Le build importe `requipso.pipes` (et donc edsnlp) : il nécessite l'environnement du projet.
108
+
109
+ ## Image Docker
110
+
111
+ `docker/Dockerfile` construit une image basée sur `inseefrlab/onyxia-marimo-python` (plateforme
112
+ Onyxia) :
113
+
114
+ ```bash
115
+ docker build -f docker/Dockerfile -t requipso .
116
+ docker run -p 2718:2718 requipso
117
+ ```
118
+
119
+ L'image installe le projet avec `uv sync --frozen` dans `/opt/python` et lance
120
+ `uv run --no-sync requipso --host 0.0.0.0 --port 2718`.
121
+
122
+ ## Publication d'une version
123
+
124
+ TODO pour GiHub + PyPi