Merge pull request #4 from tgrandje/dev

Update documentation
tgrandje · Jun 28, 2024 · 03db044 · 03db044
2 parents 4045faa + 5bbf0a3
commit 03db044
Show file tree

Hide file tree

Showing 10 changed files with 9,667 additions and 89 deletions.
diff --git a/docs/config.md b/docs/config.md
@@ -27,7 +27,7 @@ A noter que la configuration des proxy par variable d'environnement sera
 fonctionnelle pour à la fois pynsee et geopy.
 
 ## Gestion des sessions web
-`pynsee` et `geopy` utilisent leur propres gestionnaires de session web.
+`pynsee` et `geopy` utilisent leurs propres gestionnaires de session web.
 
 Ainsi, les objets `Session` passés en argument à french-cities ne seront
 **PAS** partagés avec `pynsee` ou `geopy`.

diff --git a/docs/use_cases/usecase_1_notebook.html b/docs/use_cases/usecase_1_notebook.html
@@ -3,7 +3,7 @@
 <html lang="en">
 <head><meta charset="utf-8"/>
 <meta content="width=device-width, initial-scale=1.0" name="viewport"/>
-<title>Untitled</title><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"></script>
+<title>french-cities | cas d'usage n°1</title><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"></script>
 <style type="text/css">
     pre { line-height: 125%; }
 td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }

diff --git a/docs/use_cases/usecase_2_notebook.html b/docs/use_cases/usecase_2_notebook.html
@@ -3,7 +3,7 @@
 <head><meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 
-<title>usecase_2</title><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"></script>
+<title>french-cities | cas d'usage n°2</title><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"></script>
 
 
 

diff --git a/docs/use_cases/usecase_3_notebook.html b/docs/use_cases/usecase_3_notebook.html
@@ -3,7 +3,7 @@
 <html lang="en">
 <head><meta charset="utf-8"/>
 <meta content="width=device-width, initial-scale=1.0" name="viewport"/>
-<title>usecase_2</title><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"></script>
+<title>french-cities | cas d'usage n°3</title><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"></script>
 <style type="text/css">
     pre { line-height: 125%; }
 td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }

diff --git a/docs/use_cases/usecase_4.md b/docs/use_cases/usecase_4.md
@@ -9,4 +9,88 @@ nav_order: 4
 ---
 
 # Cas d'usage
-## En construction
+## Millésimer un jeu de données
+
+
+Accéder <a href="./../usecase_4_notebook.html" target="_blank">au notebook ici</a>.
+
+La qualité de l’opendata français continue à s’améliorer d’année en année et ce
+cas d’usage devient aujourd’hui rare (dans les jeux de données mis à
+disposition).
+
+Néanmoins ce cas est encore fréquent parmi les jeux de données métier (non
+ouverts) historiques : parfois compilés sur plusieurs années, les codes
+communes ont été saisis "à date" lors de la création d'une entité dans la base
+et jamais tenus à jour.
+
+Dans cet exemple, nous allons nous intéresser aux 
+[sites pollués gérés par l'ADEME](https://data.ademe.fr/datasets/srd-ademe).
+
+
+Pour en savoir plus sur les sites pollués, le lecteur est invité à consulter
+[cette page](https://georisques.gouv.fr/consulter-les-dossiers-thematiques/pollutions-sols-sis-anciens-sites-industriels)
+sur le site georisques.gouv.fr.
+
+### Constituer le jeu de données
+
+```python
+import io
+import os
+import pandas as pd
+from requests_cache import CachedSession
+
+s = CachedSession()
+
+url = "https://data.ademe.fr/data-fair/api/v1/datasets/srd-ademe/lines?size=10000&page=1&format=csv"
+
+r = s.get(url)
+df = pd.read_csv(io.BytesIO(r.content), sep=",", dtype=str)
+```
+
+### Corriger le jeu de données
+
+Certains codes INSEE ont été mal formatés dans le fichier source : 
+malgré la précaution de spécifier un type "str", il manque des 0 en tête de
+code commune pour les neuf premiers départements français.
+
+```python
+ix = df[df.Code_INSEE.str.len() == 4].index
+print(df.loc[ix, "Code_INSEE"])
+df["Code_INSEE"] = df["Code_INSEE"].str.zfill(5)
+print(df.loc[ix, "Code_INSEE"])
+```
+
+### Millésimer le jeu de données
+
+```python
+
+from french_cities import set_vintage
+
+# =============================================================================
+# Configuration de l'API INSEE
+# =============================================================================
+os.environ["insee_key"] = "********************"
+os.environ["insee_secret"] = "********************"
+
+# =============================================================================
+# Stocker les codes initiaux pour effectuer une comparaison ultérieure
+# =============================================================================
+init = df["Code_INSEE"].copy()
+init.name = "initial"
+
+# =============================================================================
+# Utiliser french-cities
+# =============================================================================
+df = set_vintage(df, 2024, "Code_INSEE")
+
+# =============================================================================
+# Comparer les résultats aux données initiales
+# =============================================================================
+new = df["Code_INSEE"].copy()
+new.name = "final"
+
+print((init == new).all())
+ix = init[init != new].index
+
+print(init.to_frame().join(new).loc[ix])
+```