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.
- requipso/__init__.py +27 -0
- requipso/cli.py +11 -0
- requipso/completer.py +103 -0
- requipso/data.py +72 -0
- requipso/descriptive_pipeline.py +271 -0
- requipso/docs/macros.py +226 -0
- requipso/docs/mkdocs.yml +140 -0
- requipso/docs/pages/assets/consort_flowchart.png +0 -0
- requipso/docs/pages/assets/demo.gif +0 -0
- requipso/docs/pages/blocs/age.md +61 -0
- requipso/docs/pages/blocs/ald.md +65 -0
- requipso/docs/pages/blocs/biometry.md +98 -0
- requipso/docs/pages/blocs/cim10.md +80 -0
- requipso/docs/pages/blocs/cisp2.md +59 -0
- requipso/docs/pages/blocs/code-postal.md +47 -0
- requipso/docs/pages/blocs/consultations.md +65 -0
- requipso/docs/pages/blocs/departement.md +50 -0
- requipso/docs/pages/blocs/est-vivant.md +44 -0
- requipso/docs/pages/blocs/genre.md +46 -0
- requipso/docs/pages/blocs/index.md +40 -0
- requipso/docs/pages/blocs/insurance.md +55 -0
- requipso/docs/pages/blocs/medecin-traitant.md +56 -0
- requipso/docs/pages/blocs/paquet-annees.md +70 -0
- requipso/docs/pages/blocs/prescription-atc.md +69 -0
- requipso/docs/pages/blocs/regex-consultation.md +64 -0
- requipso/docs/pages/blocs/regex-nlp.md +107 -0
- requipso/docs/pages/blocs/regex-patient-observation.md +81 -0
- requipso/docs/pages/blocs/regex-prescription.md +64 -0
- requipso/docs/pages/guide/application.md +81 -0
- requipso/docs/pages/guide/combiner-blocs.md +61 -0
- requipso/docs/pages/guide/demarrage.md +74 -0
- requipso/docs/pages/guide/erreurs.md +83 -0
- requipso/docs/pages/guide/exemple-complet.md +67 -0
- requipso/docs/pages/guide/google-sheet.md +50 -0
- requipso/docs/pages/guide/onglet-inclusion.md +91 -0
- requipso/docs/pages/guide/onglet-projet.md +48 -0
- requipso/docs/pages/guide/onglet-tableau-descriptif.md +124 -0
- requipso/docs/pages/guide/parametres.md +162 -0
- requipso/docs/pages/index.md +73 -0
- requipso/docs/pages/stylesheets/extra.css +3 -0
- requipso/docs/pages/technique/ajouter-un-bloc.md +147 -0
- requipso/docs/pages/technique/architecture.md +80 -0
- requipso/docs/pages/technique/blocs-internes.md +176 -0
- requipso/docs/pages/technique/chargement-sheet.md +107 -0
- requipso/docs/pages/technique/developpement.md +124 -0
- requipso/docs/pages/technique/donnees.md +106 -0
- requipso/docs/pages/technique/export-signatures.md +131 -0
- requipso/docs/pages/technique/nlp.md +82 -0
- requipso/docs/pages/technique/parametres-internes.md +140 -0
- requipso/docs/pages/technique/pipeline.md +66 -0
- requipso/docs/pages/technique/tableau-descriptif.md +74 -0
- requipso/google.py +168 -0
- requipso/io.py +95 -0
- requipso/notebooks/marimo/run.py +352 -0
- requipso/pipeline.py +364 -0
- requipso/pipeline_loader.py +572 -0
- requipso/pipes/__init__.py +43 -0
- requipso/pipes/atcd.py +365 -0
- requipso/pipes/base.py +431 -0
- requipso/pipes/biometry.py +170 -0
- requipso/pipes/consultations.py +117 -0
- requipso/pipes/insurance.py +90 -0
- requipso/pipes/params.py +283 -0
- requipso/pipes/patient.py +377 -0
- requipso/pipes/prescription.py +134 -0
- requipso/pipes/processors.py +250 -0
- requipso/polars.py +24 -0
- requipso/resources/pathology/__init__.py +7 -0
- requipso/signature_exporter.py +473 -0
- requipso/stats.py +130 -0
- requipso-0.2.2.dist-info/METADATA +102 -0
- requipso-0.2.2.dist-info/RECORD +75 -0
- requipso-0.2.2.dist-info/WHEEL +5 -0
- requipso-0.2.2.dist-info/entry_points.txt +2 -0
- 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
|